Re: [Docutils-users] Generating LaTeX for Documenting Python

[Fred L. D. Jr. <fd...@ac...>]

Dave Kuhlman writes:
 > I've made a little progress towards generating LaTeX for
 > "Documenting Python".

Wonderful!  I'm definately interested in this, especially as I find
myself using reStructuredText more frequently and for longer pieces of
content.

 > Rather than stuff everyone's mailbox with a document that some
 > might not be interested in, I've put something in the way of
 > specification here:
 > 
 >     http://www.rexx.com/~dkuhlman/docpy.html
 >     http://www.rexx.com/~dkuhlman/docpy.html#docpy

This looks promising so far.

 > In this "specification" (which is derived from
 > docutils/docs/rst/quickref.html) note the following:
 > 
 >   1. A "Documenting Python" section that describes command-line
 >     parameters and the heading section generated.
 > 
 >   2. Many of the tables now have an additional column that shows
 >     what would be generated by the new DocUtils writer
 >     documenting_python.py.

For ``inline literal``, I'd suggest \code{inline literal} instead of
\samp{inline literal}; I think almost every use I've made of ``...``
I'd have used \code{...} for.  \samp is not used nearly as often, and
there really isn't a clear reason to use one over the other in most
cases.

It looks like there are a number of valuable reStructuredText
structures that have no corresponding structure in the "Documenting
Python" format.  I think this is something that may justify extending
the format in some places; option lists seem most immediately useful.

 > I've also gotten some work done on the writer.  There are still
 > missing features and it needs plenty of refinement.  But, it does
 > generate a document that can be sent through the "Documenting
 > Python" system.  It's basically a prototype.  It will give me
 > something into which I can work your suggestions.
 > 
 > I hope to post a first version of the writer, along with sample
 > files, in a few days.

I hope this will be available in the docutils CVS.

 > Comments will be welcomed and appreciated.

I'm glad of this, since I'm sure to generate a few!  ;-)  Thanks for
the thought and effort you're putting into this.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation