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

Alan G Isaac aisaac@american....
Thu Dec 4 09:01:26 CST 2008

> On Thu, Dec 04, 2008 at 09:01:41AM -0500, Alan G Isaac wrote:
>> 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.

On 12/4/2008 9:11 AM Gael Varoquaux apparently wrote:
> I really don't understand this argument. It does not scale, and thats the
> reason why there is a search box with sphinx. What is the problem with
> the search box? It is not as good as google, but I find it works quite
> well, and certain as well as "Ctrl-F".

It has been so long since I have used `ctrl-F` in my
browser that I had to check if the functionality was
still the same as `/`.  It is, in FireFox at least.
As a user, I hit `/` (one keystroke) and start typing.
Search is incremental and immediate.  If I have typed
all I wish as a search term, I see the result immediately
in front of me **in context**.  If I want the next result,
I just hit ctrl-g, repeatedly if necessary, and each time
I see the result *truly* in context.

>> 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.
> I don't think so, and in addition we are using sphinx, not vanilla rst,
> so we need to use the sphinx tools. That said, once again, sphinx creates
> pdf that is single page, and can thus be searched. I think this is the
> answer to your request.

1. It should be trivial to modify the writer to write sections
to separate files.  Many projects offer both a fragmented HTML
document and a complete one, allowing users to follow their tastes.
2. I doubt anyone who actually uses Adobe's PDF search
is very happy with it: it is slow and provides too little
context.  (Better than it used to be, but still.) Plus,
not everyone viewing PDFs is using Reader or Acrobat.

Alan Isaac

More information about the Scipy-dev mailing list