[DOC-SIG] Library reference manual debate

[Fred L. Drake]

John,
  Since I haven't seen any responses to your note, or at least missed
that they were responding to, I'd like to address your points and
explain at least my position.  Of, course, it'll just be my opinion,
so no promises it's worth anything.  ;-)

John Skaller writes:
 > My opinion is that fixing a format is the best way to exclude
 > most potential submitters. But if a format has to be
 > picked, it had better be ordinary old HTML, so it can
 > be put up on a website and used immediately by everyone.

  This has two distinct aspect: submission format and dissemination
format.
  I think it's possible to support multiple submission formats, but
only if clearly repeatable conversions to the cononical format is
possible in an automated fashion.  I'm not convinced that this is
practical; how many formats have you seen that are well-aligned?

 > The tree and subtrees should be available compressed.
 > That can be done automatically by some newer ftp servers.
 > Not everyone is online all the time!

  This is a disseminiation issue; python.org already has multiple
formats of output, including an HTML package you can download &
install.

 > Where are we going to get programmers who can do this
 > work without the documentation for them to learn Python?

  Who doesn't have access to at least the free tutorial?  It's
available in several formats.

 > WHO is going to convert submitted LaTeX to HTML?
 > So, I write a doc using Guido's latex style.
 > How long until someone converts it and posts it
 > to the website?

  Are you asking that documents get added as they are submitted?  The
published documents all correspond to the version of Python with which 
they were submitted.  Are you asking that there be a documentation
section corresponding to the contrib section of the site?  That may be 
possible with a shared submission format, but only if the submitted
documents can be verified.  So far, SGML is the only format which
allows this.  It's the only one I'm aware of.
  Aside from the technical issue, there are other reasons not to
publish documents which have not been checked by a person.

 > To start off, why not accept documents in
 > _several_ formats. HTML, Postscript, dvi, and perhaps
 > a Guido-restricted LaTeX -- assuming Guido is
 > willing to do the conversion. No? Then we can't

  Obviously, Guido isn't too interested in doing conversions, and
shouldn't have to.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________