[Doc-SIG] Documentation work plan

Fred L. Drake, Jr. fdrake@acm.org
Mon, 27 Mar 2000 17:07:15 -0500 (EST)

  This plan doesn't deal with source-embedded documentation; I'm
hoping that someone will write software to do the extraction.  If you
want it, please write the extractor and I can write the integration
into this plan.  ;)
  I sketched this out last night while tired, and filled it out a
little in a rush this morning.  I'm open for comments.

Python Documentation Attack Plan

  1.  "Long" HTML format

      This will be a package that contains an HTML version of the
      documentation formatted to be one HTML file per chapter.  This
      is primarily for the convenience of on-demand publishers
      interested in keeping their Python material up-to-date.
      Everyone is welcome to use this, however.

      This will be released this week.

  2.  Merge 1.5.2p2 patches into 1.6 development tree

      Time to review the CVS manual again!  This will be fairly
      tedious, since the 1.5.2p2 sources changed substantially more
      than I'd expected.  I'll work on this over the next few weeks
      one manual at a time.  Don't ask how many a "few" is -- I
      honestly don't know.

  3.a.  Update for 1.6

      Integrate the Unicode documentation, update the documentation
      for strings and the string module to reflect the addition of
      string methods.  Add documentation for more modules.  Complete
      the Python/C API manual.

    b.  Write DTD for SGML documentation

      Propose a specific DTD.  It will likely shift a little as the
      conversion is finallized and the first formatting is

  4.  Release for 1.6

      This will still be from the LaTeX sources, due to the
      accelerated release schedule for Python 1.6.

  5.a.  Wrap up conversion scripts

      Finalize the LaTeX-to-SGML conversion.

    b.  Develop SGML->HTML conversion

      Make the SGML useful.  This needs to be a very solid conversion
      since this is what most people use and be, at first, the only
      available formatting of the documents.

  6.a.  Transfer maintenance to SGML

      No more delays!

    b.  Release from SGML

      Put the HTML & SGML in people's hands without requiring CVS

  7.  Develop typeset formats from SGML

      We need at least one typeset version for old fogeys like me.
      Probably still PDF & PostScript in two paper sizes.

  8.  Release all formats from SGML

      Let them kill trees!


Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives