Re: Re: Generating LaTeX for Python manual

[me]
>   * reST/docutils metadata doesn't map too well to the requirements
>     for Python module docs,

[Felix Wiemann]
> What do you mean with 'metadata'?  The bibliographic data at the top of
> a document?  Or the meta directive?

I was referring to the bibliographic data.  For a Python module, this
looks something like:

  \section{\module{optparse} ---
          Powerful parser for command line options.}

  \declaremodule{standard}{optparse}
  \moduleauthor{Greg Ward}{gward <at> python.net}
  \sectionauthor{Johannes Gijsbers}{jlgijsbers <at> users.sf.net}
  \sectionauthor{Greg Ward}{gward <at> python.net}

  \modulesynopsis{Powerful, flexible, extensible, easy-to-use command-line
                  parsing library.}

  \versionadded{2.3}

(from Doc/lib/liboptparse.tex in the current Python CVS).  So the
metadata values here are:

  * module name
  * module summary
  * module type (standard, builtin, ...)
  * module author(s) (name and email address)
  * documentation author(s) (name and email address)
  * module synopsis
  * Python version in which this module was added

But the bibliographic elements in the Docutils tree are

  address, author, authors, contact, copyright, date, field,
  organization, revision, status, version

Of these, only author/authors clearly map to metadata needed for a
Python module.  So I could do this in my reST doc:

  :ModuleName: optparse
  :Author: Greg Ward <gward <at> python.net>
  :VersionAdded: 2.3
  [...etc...]

but that would mean processing :Author: in the "docinfo" node, and
everything else in "field" nodes.  Blecch.  I suppose I could do this:

  :ModuleName: optparse
  :ModuleAuthor: Greg Ward <gward <at> python.net>
  :VersionAdded: 2.3
  [...etc...]

but that means I can't use the handy "docinfo" stuff, which really felt
much easier and more convenient than the general "field" model.

Ideas?

        Greg
--

-- 
Greg Ward <gward <at> python.net>                         http://www.gerg.ca/
Rules for Urban Cycling, #1:
Green means go; yellow means go like hell; red means proceed with caution.

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click