[SciPy-dev] Scipy help and documentation for end users

[Fernando Perez]

[ I'm relabeling this thread so it stands out, as I think this is a rather 
important topic, hopefully the discussion can continue here and it will be 
more obvious when browsing the archives.]

Robert Kern schrieb:
> Fernando Perez wrote:

>>I don't either, but I found this prechm.py, in python's CVS at Doc/tools:
>>
>>http://cvs.sourceforge.net/viewcvs.py/*checkout*/python/python/dist/src/Doc/tools/prechm.py?content-type=text%2Fplain&rev=1.20 
>>
>>
>>I haven't tested it, but from the docstring, it will take html files and 
>>wrap them into a .chm file.  We could give it a try, and if it works 
>>well enough, make a bundle of docs in this format.
> 
> 
> Not quite, AFAICT. It massages the existing HTML to what's necessary for 
> Microsoft's help authoring tools to work. Their Windows-only software is 
> still necessary to build the CHM file itself.

Bummer.  I didn't have time to run a test last night.

This page has a useful discussion of documentation generation under Linux:

http://www.jeanweber.com/howto/linux-help.htm

One option would be to use DocBook, which Lyx and OpenOffice both support. 
But DocBook has a reputation for complexity, I don't really know how justified 
or it truly is.

But back to the chm format as a possibility, perhaps not all is lost.  While 
there seems to be no native linux authoring tool, this thing:

http://www.soft411.com/company/AbeeTech/Abee-CHM-Maker-freeware.htm

is Windows freeware.  I suspect, being a win95-compatible small program, it 
will probably run just fine under Wine.  So perhaps this could be used to make 
the .chm files, which seems to be the sticking point.  We've seen there are 
good X window clients for this format, we just need to solve the authoring issue.

Anyway, whether it's docbook or chm, we certainly need a solid 
documentation/help system integrated into this to make python/scipy more 
approachable to new scientists.  These are just some suggestions, and I'm sure 
others know more about this than I do.

Best,

f