[Doc-SIG] Python docs in reST

Fred L. Drake, Jr. fdrake at acm.org
Fri May 27 21:10:49 CEST 2005


On Friday 27 May 2005 12:37, Felix Wiemann wrote:
 > I just quickly wrote up a short LaTeX document to test that.  It's not
 > the Python doc format but just a normal LaTeX document, but I presume it
 > won't make much of a difference.

Don't make that assumption.  

 > ----------------------------------------------------------------------
 > \documentclass{article}
 > \begin{document}
 > \begin{verbatim}
 >
 > >>> print "foo\nbar"
 >
 > foo
 > bar
 >
 > \end{verbatim}

Good so far.

 > Consider the \texttt{foo$\backslash$nbar} string!

Consider the \code{foo\nbar} string!

 > \vspace{1em}\noindent\texttt{%
 > This is the \emph{first} line.\\
 > This is the \emph{second} line.}
 > \vspace{1em}

I'm not sure what the use-case is here, but there shouldn't be anything like 
this in the Python docs.  This should probably be an "alltt" environment like 
this:

\begin{alltt}
This is the \emph{first} line.
This is the \emph{second} line.
\end{alltt}

The line-block syntax in ReST is nice, but I don't know that there's much use 
for it in the Python documentation.  We do use alltt and verbatim 
environments a lot.

 > I'm not gonna try to render a table with its $\backslash$hlines here.
 > It's \emph{completely} unreadable, IMO.
 > \end{document}
 > ----------------------------------------------------------------------

Yes, tables don't do well in LaTeX.  I'm not so familiar with the ReST syntax 
either, but had a hard time with the few I've done in ReST (lines end up 
*way* too long; at least that's not a constraint in LaTeX, since I can put 
rows on separate lines).  Note that tables in Python documentation tend to be 
marked up very differently than in raw LaTeX.

 > * In reST I can insert tables as simple tables, grid tables (with
 >   support from Emacs!), list-tables and CSV-tables.  In LaTeX there is a
 >   "tabular" environment whose syntax I have to look up everytime I use
 >   it, and the table contents aren't nicely viewable in LaTeX (because
 >   they're interspersed with "&", "\\" and "\hline").

As noted above, the Python documentation style wraps the raw LaTeX table 
constructs.  There are reasons for this.  :-)

 > * There are some handy list-like constructs in reST, e.g. field lists or
 >   definition lists.  I just type

Indeed.  The nice list syntaxes in ReST are a definate benefit.

 >   In LaTeX I simply wouldn't know how to do this off the top of my head.
 >   It's possible of course, but it's just not simple and straightforward,
 >   and for somebody who doesn't have a LaTeX reference at hand it must be
 >   really difficult.

We don't need to do this directly in standard LaTeX markup; we introduce 
specialized list-based environments so they can be marked semantically, and 
processing can be applied as needed.


  -Fred

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


More information about the Doc-SIG mailing list