[DOC-SIG] Re: [PSA MEMBERS] [XML] Notes on the Tutorial's markup

[Fred L. Drake]

Paul Prescod writes:
 > I agree. Or perhaps DocBook, which is a DTD designed for software
 > documentation and used by O'Reilly and Associates for their books.
 > DocBook is nice because there are already tools to convert it to HTML
 > and LaTeX, and of course because it makes it really easy to turn around
 > and hand ORA an SGML file for printing.

  These are major benefits of docbook in my mind.

 > Now the next question is, XML or SGML. I am a long-time SGML user, but
...
 > I think that when push comes to shove, whoever has to type this stuff
 > should vote in favour of SGML. XML means a <EMPH>lot</EMPH> of extra

  I'm in favor of SGML for this; XML should not be difficult to
generate if needed, but SGML allows all the flexibility we might think 
we need in the future.  At this point, it doesn't look like there's a
lot of experience with *large* XML documents, though I'm sure I've
overlooked something somewhere, and there are a few.  The ability to
use </> is a major win in my book.
  I expect initial conversion of the Library Reference could be done
using Python, and then "fixed up" manually using an editor like XEmacs 
(or Emacs) and PSGML mode.
  Regarding processing, I'd have no problems using SP to do this; a
Python interface to the generic interface would not be difficult to
create, if a little tedious.  I'm willing to do this, but it would be
evenings / weekends, and only if it'll get used.

 > Your list of features is a good start. I think that we should make a
 > DocBook subset that includes just those features. As we want to do more
 > sophisticated things, we may let it grow towards full DocBook, and
 > perhaps also extend it in Python-specific ways "subclass it" (in a rough
 > SGML-warped sense).

  Paul, do you know of any good material *about* docbook for those not 
familiar with the DTD?  I've read the 2.4.1(?) reference manual (not
recently), but would really like to find something at a higher level
and for the current version.

 > The more difficult issue (conceptually) is what to do about
 > "docstrings". 
 > 
 >  * Will we make them structured or leave them unstructured? 
 >  * Structured in 
 > 	*SGML/XML?
 > 	* some-adhoc language that is more "pretty"? 
 > 	* using Python data structures?

  I'd like to see two things:  human parsable docstrings (*not* any
heavy markup), perhaps using a few conventions to distinguish things.
A number of people have tried to define conventions and write
documentation extractors, but I think it boils down to several things:

  - There's a real desire for some measure of structure when
    generating "book-like" documentation (the library reference), and
    people still want something like that to print.

  - There's a need for some quick-access documentation in the
    sources.

  - Nobody seems to agree on what should go into the docstrings,
    either in content or form.  (Content is usually less of an issue
    than form.)  What comes out is really irrelevant, since different
    tools can be written to get the "right stuff" as long as it went
    in to start with.

 > A related issue is whether we intend to have both a library reference
 > and structured docstrings? Or is the library reference just what you get
 > by concatenating the docstrings from the various modules? Are people
 > willing to make the source the documentation source too?

  I don't think that having both will be avoidable in the near term
(10 years) if we really want heavily structured data.


  -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
_______________