[SciPy-dev] Accessible SciPy (ASP) project
pearu at scipy.org
Sun Oct 31 04:05:31 CST 2004
On Mon, 18 Oct 2004, Joe Harrington wrote:
> 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
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
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.
> The three areas for improvement can proceed in parallel. Since
> packaging issues affect the documentation, those should be resolved
> as soon as possible.
> For packaging, we need to:
> 1. determine whether the idea of replacing xplt and gplt with
> matplotlib in the docs is acceptable to the community,
Fine with me (as I am not currently using any of these tools yet).
> 2. determine whether IPython should go into the core,
I am using it on dayly basis, so +1 from me.
> 3. determine whether the "coexistence" approach for resolving the
> numeric/Numarray split is a good idea.
First, we need to get Numarray support to Scipy and then we can make
decicions on the above.
> Then, we need to roll and field-test the binary packages. The latter
> effort will require volunteers, so if you want your package or
> platform to be supported, please sign up.
> For documentation, we need to agree on a common source format, an open
> copyright, and some stylistic guidelines. Documents are needed in
> roughly the order listed above, though if someone is very inspired to
> start on a later one, he or she should proceed. Suggestions for
> additional documents are welcome, as are volunteers to write them.
> Goals for the web site are less clear than for packaging and
> documentation. Some mailing list brainstorming on content and format
> issues would be a good idea, starting with those above. Then, we need
> to identify page maintainers and get them access. Several individuals
> stepped forward at the BoF, and a web human interface designer has
> volunteered to help. Again, more volunteers are needed.
This is good that people offered help at the BoF, but not enough to get
real work done. I think now we should take the next step and ask specific
help in person.
More information about the Scipy-dev