Hi Guenter,

Thanks for this extensive and thoughtful response.† It is true that I am new to the list (and docutils) -- thanks for your forbearance.

Some follow-ups on your response to my post:

1) Thanks for the tip regarding the hackable default.tex template. I translate at the command line as follows:

rst2latex \
--template=mydefault.tex \
--stylesheet=fullpage.sty \ --documentoptions=letter,12pt \
myfile.rst myfilte.tex

To eliminate the docinfo metadata from appearing in the beginning of my latex translated document I change the this line in default.tex:
to the following in mydefault.tex:

2) It is true that the LaTeX wrapfigure environment can be temperamental (I have heard it called the wrapped in agony environment) but it really is the (in my opinion) the better translation for the reST figure role.† This tweak just works:


.. figure:: Images/GlyJk72bonds.png
† :width: 60%
† :align: right
† :target: Images/GlyJk72bonds.png

† Glycine bondlengths from neutron scattering.


\caption{Glycine bondlengths from neutron scattering.}

As it is -- is there any way using the current tool set to put the align parameter in the LaTeX output as a comment so I could "sed" it on the backend into a wrapfigure?

3.† Thanks for your summary survey of reST docutils and its relationship to Sphinx -- this was helpful.† And it is always a good idea to RTFM.† But frankly there is a lot of it and some of it -- see for example "The Node Interface" in the Docutils Hackers Guide -- is just incomplete.† David Goodger has stated that he believes that the best documentation is in the code itself.† But once again frankly this places a big burden on those who want to use and extend this wonderful docutils platform for our own needs.† For example just figuring out how to extract metadata from reST turned out to be a big effort. (See appended function and note)


PS metadata extraction

This was my dirty hack based on but really simplifying some stuff I read at http://pydoc.net/Python/pelican/2.7.2/pelican.readers/

def get_metadata(document):
††† """Return the dict containing document metadata"""
††† output = {}
††† for docinfo in document.traverse(nodes.docinfo):
††††††† for element in docinfo.children:
††††††††††† if element.tagname == 'field': # custom fields (e.g. summary)
††††††††††††††† name_elem, body_elem = element.children
††††††††††††††† name = name_elem.astext().lower()
††††††††††††††† #value = render_node_to_html(document, body_elem)
††††††††††††††† value = body_elem.astext()
††††††††††† else: # standard fields (e.g. address)
††††††††††††††† name = element.tagname
††††††††††††††† value = element.astext()
††††††††††† #output[name] = _process_metadata(name, value)
††††††††††† output[name] = value
††† return output

On Fri, May 3, 2013 at 3:31 AM, Guenter Milde

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.,
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

.. _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
so that many source documents for Sphinx are incompatible with Docutils or
other rST systems.


Get 100% visibility into Java/.NET code with AppDynamics Lite
It's a free troubleshooting tool designed for production
Get down to code-level detail for bottlenecks, with <2% overhead.
Download for free and get started troubleshooting in minutes.
Docutils-users mailing list

Please use "Reply All" to reply to the list.

Michael G. Prisant, Ph. D.
Department of Biochemistry, Duke University, Durham, NC 27710

Email:† Michael.Prisant@gmail.com and prisant@biochem.duke.edu
Phone: Home (919) 382-0244 / Cell (919) 641-3638 / Fax (919) 282-1150
Voip:††† Voip.ms (919) 282-1152 / Google Voice (919) 410-6470
Skype: michael.prisant

Work: Department of Biochemistry, Nanaline H. Duke, Box 3711, DUMC, Durham, NC 27710
Home: 5611 Inverness Drive, Durham, NC 27712