[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