[SciPy-dev] Accessible SciPy (ASP) project

eric jones eric at enthought.com
Sun Oct 31 21:56:13 CST 2004


Pearu Peterson wrote:

>
>
> On Mon, 18 Oct 2004, Joe Harrington wrote:
>
>> DOCUMENTATION
>>
> <snip>
>
>> It was noted at the BoF that Enthought has substantial documentation
>> in its Windows package in .chm format, and that there is now an X
>> reader for these files.  Those documents will be broken out for
>> non-Windows users and may form the bases for one or more of the
>> documents above, assuming cooperation from Enthought on permissions
>> and copyrights.
>>
>> Translations are always a good idea, but can only be obtained in a
>> community project through the work of competent volunteers.  The
>> quality of our documentation will be vastly improved by user testing
>> and comment, and by the participation of more than one person in the
>> creation of each document.  However, content determines form, so we
>> should not be shy about making first drafts available, provided that
>> we continue to work on them.
>>
>> We will need to agree on a set of standards for writing documents.
>> Certainly all docs should be available in PDF and HTML, and the source
>> should be modifiable by anyone on any platform.  The Windows .chm
>> format may also be a viable target if good tools exist to do it under
>> Linux and Mac as well as Windows.  The source form must be viable in
>> the long term and must not leave us in a bind if the text-processing
>> software ceases to be supported.  Structured Text and LaTeX have been
>> suggested.  MSWord and other proprietary forms are out.  The major
>> need for formulae in scientific documentation may push us to LaTeX,
>> perhaps with a standardized format, but this is open for discussion.
>
>
> I agree that MSWord is out, even OpenOffice or StarOffice would be out 
> for me.
>
> Python documentation project is moving from using LaTeX to ReST (note 
> that ReST is different form ST). ReST has LaTeX capabilities but only 
> for its LaTeX output. But in principle we can generate any desired 
> format from LaTeX.
>
> Personally, I would prefer ReST (as the future standard documentation 
> tool in Python) or LaTeX (as a very powerful documentation tool in 
> general both in past and future). I have put ReST before LaTeX (in 
> other cases it would be reversed) because ReST could be used in 
> documentation strings as well.
>
> I could use Lyx but I consider it as WYSIWYG-LaTeX which does not 
> impress me much when using Auctex Emacs mode in working with LaTeX 
> documents.
>
> As I have understood from earlier discussions that LaTeX may scare 
> people away from writing documentation for Scipy. But let me ask may 
> be a bit harsh question: are these people able to produce good quality 
> technical documentation for Scipy if they reject to learn LaTeX 
> basics? Afterall, LaTeX is not that difficult to use, especially when 
> we can provide documentation templates to get started easy, and there 
> are nice LaTeX frontends available for Windows as well.

Of the two options, ReST is much more preferable to me.  I, and many 
others, use Word as my primary documenting tool and dislike LaTeX very 
much.  Of the open options, I (and many others) would be most 
comfortable in OpenOffice.  However, I also think that ReST has many 
benefits (better diffs in a code repository, editable in any editor, 
etc.) that are compelling.  Imposing the LaTeX learning curve and 
infrastructure requirements on would-be contributors is too limiting in 
my opinion.  So, of the imperfect solutions, ReST seems the most 
palatable to the most people.

eric




More information about the Scipy-dev mailing list