[DOC-SIG] Library reference SGML plan

[M.-A. Lemburg]

Guido van Rossum wrote:
> 
> Many packages these days come with preformatted HTML as the only
> documentation, and it's mighty convenient.  I could do this, and
> create separate bundles for the PostScript and latex.  Unfortunately,
> it's not a space saver: e.g. the library manual HTML, tarred and
> gzipped, is about 840K, while the latex is less than 240K (also tarred
> and gzipped).  Take similar expansion factors for the other manual
> pages, and you may see the tarred, gzipped Python distribution grow
> from 5.4 Meg to 6.5 Meg -- after unzipping it will probably add 2 or 3
> Meg.

I wasn't thinking of space savings here... for first time contact
to Python I think HTML is the best way to get people interested.
Then make PDF available from the web site and they'll get really
happy :)

> Is this acceptable?

Yep.

> (On the other hand, it's easy enough for
> most people to download the HTML separately if they need it, and it
> *is* called a source distribution...)

It's for you to decide. As far as I'm concerned I never used the
Doc/-files in all the years -- couldn't get them to compile the
first time and after that never touched them again. Instead I
download your HTML distribution every time a new release is out.
[So for Joe Average like me, you'd have to add the two above
figures :]

Richard Folwell wrote:
> 
> Overall I prefer Postscript, but PDF has the big
> practical advantage that we can distribute a viewer with it, whereas many
> people are not in a position to view/print Postscript [2].  For online reading
> we install HTML, and this seems to be the best for the moment [3].

As Guido said: PDF is good for printing, in fact it is the easiest
way to get printed manuals in a portable way, since not everybody
can enjoy ghostscript or has access to a postscript printer --
the acrobat reader provides a nice document to printer interface
here. Depending on how you convert XYZ to PDF it also allows
fulltext searching, which comes in handy too...

For online viewing I very much prefer HTML. A micro HTTP-
server with searching capabilities written totally in
Python would be good idea here too. This could be specialized
to Pythondoc searching, e.g. use a generated index (I believe
with the highly structured format the lib ref is in, this shoudn't
be much of a problem). Anybody out there with experience in
this field ? The HTTP-server is already there...HintHintHint ;-)

Some other ideas[1]:
- the index could be used for an online help system: instead
  of looking at a docstring (most of which are still missing),
  you'd type help('str') and through the Netscape remote control
  interface the right manual page pops up... or maybe a Tk/Tcl
  manual browser... or just plain old text in a more-like
  browser
- install the docs in the same place, the libs live in; in a
  multi-user environment this saves headaches and aids in things
  like coding a help system
- add some kind of way in which extensions can hook into this
  system -- 'make install' (using Makefile.pre.in) could also
  install the docs for the extension; this is easy to do for
  HTML docs, since adding a few links to a special extension
  page is simple (you don't even need to recompile the docs
  for this to work -- only add the new entries to the index).

[1] Sorry, don't have the time to look any further into this :(

-- 
Marc-Andre Lemburg


_______________
DOC-SIG  - SIG for the Python Documentation Project

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