Re: [Docutils-users] broken rst cheatsheet?

[Guenter M. <mi...@us...>]

On 2013-05-02, Michael Prisant wrote:

> I had hoped that my suggestion of defining a "subset" of reST markup via a
> form of a cheetsheet -- especially with regard to the problematic table
> translation -- which could be translated to both html and latex would
> minimize the maintainer's work as it involved defining what was supported
> and testing translation rather than coding.  The subset need not be
> complete but rather "certifiable"

There are limits inherent in every output format that cannot be overcome
with reasonable effort.

Given the number of supported output formats, it is not simple to define
such a subset. Which combination of xml, pseudoxml, html, s5, latex,
xetex, odt, and manpage should be listed? If we include popular 3rd-party
extensions, this becomes even more complex.

Instead, the documentation for the writers lists limitations, so the
developer would need to read, e.g.,
http://docutils.sourceforge.net/docs/user/latex.html#problems
if output to HTML and PDF via LaTeX is desired.

> This would be valuable for me and would help me provide instructions to
> users of my wiki as what could be used and printed.

> As to other features I personally would request (i) optional inclusion of
> the latex wrapfigure environment when reST figure role includes the align
> parameter and 

This is a long standing issue on the TODO_ list. Unfortunately,
"wrapfigure" can lead to problems when used inside lists and other objects.
It usually requires a lot of hand-fiddeling to get everything right. This is
tedious in LaTeX and even more with an additional rst layer.

> (ii) optional supression of latex translation the docinfo metadata

What do you mean by this? Maybe you can already get this with a custom
template file http://docutils.sourceforge.net/docs/user/config.html#id41
or a class value and strip-elements-with-classes
http://docutils.sourceforge.net/docs/user/config.html#strip-elements-with-classes
?

.. _TODO: http://docutils.sourceforge.net/docs/dev/todo.html

> Clearly this issue of translation to latex and ultimately to pdf has
> attracted increasing attention in the docutils user community. I base this
> assertion (i) on the number of comments collected in the thread so far and
> (ii) google hits on the subject of reST to pdf translation.

Just like the "beamer" LaTeX package, the amount of discussion and help
requests is due to a mixture of facts:

a) general interest,
b) complexity of the task and number of pitfals,
c) competing interests of users with different use cases.

may be more...

> I think that as it has evolved (regardless of original conception) reST is
> being used as both a text format document in and of itself and as a markup
> specification which can be translated into multiple other formats
> especially html for web display and pdf for printing.

The Docutils home page http://docutils.sourceforge.net defines

  Docutils is an open-source text processing system for processing
  plaintext documentation into useful formats, such as HTML, LaTeX,
  man-pages, open-document or XML. It includes reStructuredText, the easy
  to read, easy to use, what-you-see-is-what-you-get plaintext markup
  language.

In addition to reStructuredText, Docutils also defines a `document model`
via a document tree http://docutils.sourceforge.net/docs/ref/doctree.html
and DTD http://docutils.sourceforge.net/docs/ref/docutils.dtd
and an API for prgrammatic use.

> I would submit as example the use of reST as the native source for
> sphinx and docutils as its apparent software kernel is the most
> prominent example.  This is a great success for reST though it puts a
> big burden on the maintainers.

Sphinx uses the Docutils API for parsing and HTML-writing (the Sphinx LaTeX
writer is a fork). It extends the reStructuredText core defined in
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
so that many source documents for Sphinx are incompatible with Docutils or
other rST systems.

Günter