Re: [Docutils-users] custom directive: publish html and latex2e differently

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

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.
 
Günter