Hi Guenter,

Thanks for this reply but I was looking for more specific advice with regard to coding rest custom directives (as opposed to using the "raw: approach) which are properly translated to both html and latex (like non-custom directives).† Admittedly, I tried to pare my actual python code snippet to a bare minimum more or else working example. (This eliminated my actual bibtex processing which is what actually necessitated python code as opposed to just using "raw".† So some confusion seems to stem from the example given which† doesn't do very much)†† On this basis I was hoping† that one of the experienced coders could offer an *explicit* but *simple* python example to the group based on the very *simple* code snippets that I provided.

The custom directive appears in the reST document:

.. bibentries::
††† BCC+87;;

Once again (with a few minor clarifications and corrections), when I code a custom directive which only "goes to the html writer" it works. But† I want to "publish"/translate this rest/text to both html and latex versions and I not able to figure out how this should be coded *after* searching and reading the documentation that I was able to find on the web. [1]

This is my python code for the custom directive for translation to only html:

class BibDirective(Directive):
††† has_content = True
††† def run(self):
††††††† self.assert_has_content()
††††††† text = '<pre> This is the html bibdirective </pre>'
††††††† return [nodes.raw('', text, format='html')]

directives.register_directive("bibentries", BibDirective)

it works fine.† But when I try to hack the same idiom to output to both html and latex with something like

class BibDirective(Directive):
††† has_content = True
††† def run(self):
††††††† self.assert_has_content()
††††††† text = '<pre> This is the html bibdirective </pre>'
††††††† return [nodes.raw('', text, format='html')]

class BibDirective(Directive):
††† has_content = True
††† def run(self):
††††††† self.assert_has_content()
††††††† text = '\begin{verbatim} This is the latex bibdirective \end{verbatim}'
††††††† return [nodes.raw('', text, format='latex')]

directives.register_directive("bibentries", BibDirective)

This really doesn't get anywhere.† So what is the correct idiom for this task? Explicit python code please.

The question here is really to help users who are attempting to code simple extensions to reST for their own specific uses as opposed to general development which would be folded into the software.† I want to translate a custom reST directive into just html and latex (as opposed to also translating into every possible output format) [2]


[1]† I based my snippet on code in the following blog entry:
This web reference was more helpful me than anything that I found in the "official" docutils pages because it gave an explicit and simple example of code.

[2]† I have actually already kluged an approach to this for my application: the html translation is dealt with using the custom directive code and the latex translation is dealt with by preprocessing the reST document into an intermediate reST source.† But this is really inelegant. And it is frankly frustrating to kludge case by case translations which seems could be done in a much more general and better way by the publish_doctree, publish_from_doctree approach.† In my view more specific simple examples would be very helpful to users (as well as completing the unfinished node documentation)

On Mon, May 13, 2013 at 3:58 AM, Guenter Milde <milde@users.sf.net> wrote:
On 2013-05-08, Michael Prisant wrote:

> Dear Group,

> Let's say I have a custom restructured text directive of the following form
> in the string "content":

> .. bibentries::

> † † BCC+87;;

> For the purpose of this question when I call

> print publish_string( source=content,
> writer_name='html',settings_overrides=overrides)

> I would like to emit something similar to the following in my html stream:

><pre> This is the html bibdirective </pre>

> and when I call:

> print publish_string(
> source=content,writer_name='latex2e',settings_overrides=overrides)

> to emit something similar to the following in my latex stream:

> /begin{verbatim} This is the latex bibdirective /end{endverbatim}

In a custom directive class, you can manipulate both, the input stream (i.e.
the part that is not yet parsed) and the document tree.

This means you could prepend reStructuredText that would result in the
desired html/latex/... output::

† .. raw:: html

† † †this is raw html

† .. raw:: latex

† † †this is raw latex

† .. raw:: man

† † †this is raw manpage writer content ...

and let the parser parse it (see the include directive for an example of
input stream manipulation by a directive).

However, I rather recommend to avoid "raw" if possible. If you can represent
the content of whatever the directive should produce as reStructuredText,
use this, instead of raw. Then you are free to either prepend the
reStructuredText source to the input stream or (better) the nodes that would
result from parsing this input direct to the document tree.

The advantage of this approach is better portability: the resulting document
tree can be processed by any writer.


Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and
their applications. This 200-page book is written by three acclaimed
leaders in the field. The early access version is available now.
Download your free book today! http://p.sf.net/sfu/neotech_d2d_may
Docutils-users mailing list

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

Michael G. Prisant