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:
$body_pre_docinfo$docinfo$dedication$abstract$body to the following in mydefault.tex:$body_pre_docinfo$dedication$abstract\$body

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:

reST

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

Glycine bondlengths from neutron scattering.

LaTeX

\begin{wrapfigure}{r}{0.60\textwidth}
\centerline{%
\href{Images/GlyJk72bonds.png}{%
\includegraphics[width=0.600\linewidth]{Images/GlyJk72bonds.png}
}
}
\caption{Glycine bondlengths from neutron scattering.}
\end{wrapfigure}

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)

Michael

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/

"""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] = value
return output

On Fri, May 3, 2013 at 3:31 AM, Guenter Milde wrote:
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.

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

------------------------------------------------------------------------------
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.
http://p.sf.net/sfu/appdyn_d2d_ap2
_______________________________________________
Docutils-users mailing list
Docutils-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

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