[Python-Dev] The docs, reloaded (original) (raw)

Martin Blais blais at furius.ca
Tue May 22 16:37:58 CEST 2007

On 5/22/07, Armin Ronacher <armin.ronacher at active-4.com> wrote:

> > > > * reST markup isn't much simpler than LaTeX. > > * reST doesn't support nested markup, which is used in the current > documentation.

For a lightweight markup language that is human readable (which rst certainly is) the syntax is surprisingly powerful. You can nest any block tag and I'm not sure how often you have to nest roles and stuff like that. The goal of the new docs is a less complex syntax and currently nothing beats reStructuredText in terms of readability and possibilities.

About possibilities: I'm sorry but that is simply not true. LaTeX provides the full power of macro expansion, while ReST is a fixed (almost, roles are an exception) syntax which has its own set of problems and ambiguities. It is far from perfect, and definitely does not have the flexibility that LaTeX provides. Some of the syntax cannot be nested (try to combine ** with literals).

rst is simpler than latex:

That, and the ability to already parse it from Python and more easily convert to other formats (one of LaTeX's weaknesses), are the only benefits that I can see to switching away from LaTeX. I have to admit I'm afraid we would be moving to a lesser technology, and the driver for that seems to be people's reluctance to work with the more powerful, more complex tool. Not saying it is invalid (it's about people, in the end), but I still don't see what's the big problem with LaTeX.

More information about the Python-Dev mailing list