[SciPy-dev] Scipy Tutorial (and updating it)

[Alan G Isaac]

> On Thu, Dec 04, 2008 at 10:25:36AM +0100, R. Bastian  wrote:
>>> I think the tutorial would be much more usable if it were broken up 
>>> into different pages (each as a separate .rst file). 


On 12/4/2008 4:39 AM Gael Varoquaux apparently wrote:
> I don't agree. Long HTML pages are bad practice, every web designer will 
> tell you that (http://webstyleguide.com/page/length.html, 
> http://www.astrodigital.org/digital/shortvslongpages.html, 
> http://www.webpagesthatsuck.com/biggest-mistakes-in-web-design-1995-2015.html 
> - 10 ...). 
> The good rule should be: one subject by pages, pages a few screen long 
> maximum. 


I think this gets into areas of "true belief".
My view is that an adequately linked single
HTML document can be just as useful or more useful
than a broken up document.  Example: the NumPy
Example List is much more useful if we can search
nicely across all the examples, which requires a single
page document.

That said, there is no reason by broken up HTML document
requires a broken up reST source.  Just write each
section to a separate file, with appropriate headers.
I think the rst2html writer used to support that out
of the box, although I'm not positive.

Cheers,
Alan Isaac