[SciPy-dev] Scipy Tutorial (and updating it)
Alan G Isaac
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.
More information about the Scipy-dev