Re: [Docutils-users] broken rst cheatsheet?

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

On 2013-05-03, Michael Prisant wrote:

Dear Michael,

...

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

I have reservations to make such a "fragile" environment (which may
require manual inspection and fine-tuning) the default.

Also, in many cases floating figures are the better choice. Currently this
is possible to select via LaTeX code in the preamble or raw LaTeX:
http://docutils.sourceforge.net/docs/user/latex.html#figure-placement

The placement of figure floats might become configurable via class arguments
http://docutils.sourceforge.net/docs/dev/todo.html#configurable-placement-of-figure-and-table-floats

This could also include the spcial class argument "wrap" for wrapfig use:
http://docutils.sourceforge.net/docs/dev/todo.html#image-and-figure-directives

> This tweak just works:

(if not used at inappropriate places)

> reST

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

>   Glycine bondlengths from neutron scattering.

This figure does not set the :figwidth: option.
It is not clear, whether the default :figwidth: should be
the width of the included image or the width of the containing element.

With LaTeX, "figwidth" is currently ignored and the width of a figure is
always 100%.

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

I just commited a change to do this to the SVN.


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

However, there is noone else that can take the burden. Help is welcome.

> For example just figuring out how to extract metadata from reST turned
> out to be a big effort.

Docutils is a complex project, and with every complex project there are
tasks that are dead easy to do if you know how but it takes ages to find
out this...

That said, I agree with you that a better organized and maintained
documentation may help users and prospective developers to come to grips
with Docutils more easily. My idea is to use Sphinx to build the HTML
documentation - this should provide better navigation and a search feature.


Günter