Menu
▾
▴
Re: [Docutils-users] broken rst cheatsheet?
|
From: Michael P. <mic...@gm...> - 2013-05-03 18:51:04
|
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
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
<mi...@us...> 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.
>
> 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
>
>
>
> ------------------------------------------------------------------------------
> 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.
> http://p.sf.net/sfu/appdyn_d2d_ap2
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
--
Michael G. Prisant, Ph. D.
Department of Biochemistry, Duke University, Durham, NC 27710
Email: Mic...@gm... and
pr...@bi...<Mic...@gm...>
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
<Mic...@gm...>
|
