[Doc-SIG] XML Conversion Update

[Fred L. Drake, Jr.]

[Cleaning out my mailbox a bit...]

Jack Jansen writes:
 > While I agree with Sean (and others) that small DTDs are a lot better
 > suited to documenting Python modules there's various
 > standard-formatting things that you'd like to borrow from existing
 > DTDs (emphasis, references to other manuals/sections, footnotes, etc).
 > 
 > Is there a way that that could be done, without dragging in the whole
 > of the (apparently huge and hairy, from the reports here) docbook DTD?

  I looked at the idea of just using the names from DocBook when the
semantics are the same, and decided that was a red herring.  DocBook
is *very* verbose, and using XML is already heavy enough in the markup 
department.  Something simple, like:

    \emph{My} plan was to use \var{bogosity} with a value of \code{1}.

becomes (in XML):

    <emphasis>My</emphasis> plan was to use
    <varname>bogosity</varname> with a value of <literal>1</literal>.

or (in SGML):

    <emphasis>My</> plan was to use <varname>bogosity</> with a value
    of <literal>1</>.

  There are some (less important) issues of mapping \code, since it's
used for things which I'm not at sure map to the same thing, and
similar (but less importantly) for \samp.
  Any way around it, *ML markup is very heavy for the occaisional
contributor using vi or emacs (or any other editor that isn't highly
specialized).  Even asking the emacs user to install PSGML is probably 
too much, esp. since that's too much to learn if you don't edit SGML a 
*lot*.
  Which of course gives rise to discussions like the current
discussion of inline markup...


  -Fred

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