Thanks for this response. I posted to this thread asking the maintainers to
provide a simple example of defining a custom role and writing different
versions to html and latex. This was essentially requesting a "toy" version
of how a stock directive was coded: Intercept a custom directive in a
python reading of rst document tree and be able to publish from that
amended tree to html and latex.
This seems clear enough to me and in my view this question has come up
before though in other forms on the list. The rest of my response follows
in text and should be brief enough for even the extremely time challenged :)
On Tue, May 14, 2013 at 12:30 PM, David Goodger <goodger@...> wrote:
> On Tue, May 14, 2013 at 1:56 AM, Michael Prisant
> <michael.prisant@...> wrote:
> > Hi David,
> > Thanks for this reply and for writing docutils. I will try to respond to
> > your questions (to help you help me), But bear with a me bit -- I don't
> > think that I can directly comply with your comments other than to note
> > "yes I think that the rendered text and functionality" are different in
> > html and latex published versions so it really has to change depending on
> > the output format.
> In what way, exactly, do they have to differ? And please: *briefly*.
> Sorry, I don't have time to read long email messages like this one.
> The html has adds a bunch of form code; the latex version suppresses
printing various url links etc
> Can your desired output be constructed from primitives that are
> already supported in Docutils? If "yes", your job will be much easier.
> Try. If "no", you may have to derive custom Writers for your
> application (recommended), or go the "raw" directive route you've been
> using (not recommended). But maybe the answer is that Docutils isn't
> the right tool for the job.
No for the html output; yes for stuff which is later latex'd. Once again I
said this in my previous post.
> That's about all the advice I can give. I don't know
> bibtex/bibliography details, and I have no desire to learn them.
I don't ask for help with LaTeX/BiBTeX -- just with python
parsing/processing restructured text using your docutils software.
> tried to read your message but found it difficult to follow. I don't
> know what you're trying to accomplish. If you try again, use a
> different approach. Perhaps "show us, don't tell us" will work better.
I gave a simple version -- but you called it "unnaturally simple", and
asked for a more detailed explanation. So I di my best (and spent time)
trying to constructively engage the issues which you raised. (Even though I
thought that those issues had been clearly described at least twice before
in preceding posts.) If you read my previous note you will find (i) my reST
input with custom directive, (ii) the html produced from it which I pass
for rendering, and (iii) the reST which I produce for LaTeXing. 
> First in overview. I am trying to write a sort of annotated bibliography
> > wiki application using reST as the underlying markup language for the
> > pages.
> ISTM that you may be trying to load too much functionality onto
> Docutils/reST. If you have an interactive web app, Docutils is not the
> right tool for the job. Docutils can transform reST statically, but it
> does not support interactive/dynamic functionality. That's what a web
> framework is for.
See above or read my posting -- I think it is clear that that I am *not*
trying to load too much functionality onto Docutils/reST. I just wanted
help in understanding how to capture the string content my custom directive
by using the docutils tree instead of stock python string processing.
(Actually my "unnaturally simple example" didn't even require capturing the
string contents -- just emitting a different string to the html and the
latex wrtiers when the custom directive was encountered)
> You can still use reST for your text content, but don't try to get
> Docutils to support the database-backed dynamic web stuff.
It should be clear I am not trying to get you to do this.[4,5] Please read
my posting(s) or at least its(their) first paragraph(s).
Docutils is a big and important project -- chosen by Python to support its
documentation processing. It was arguably brilliantly conceived and coded
and is currently maintained by very gifted software engineers and python
programmers. Users come to it because they think it is better than the
That is why it merits reasonably readable and complete documentation.
And when the user mailing list identifies gaps in that documentation,
developer and maintainers should provide civil responses to their users.
The fact that this sort of docutils directive "hacking" question (albeit in
different forms) has come up repeatedly on this list and elsewhere on the
web should be persuasive enough argument for the developer and maintainers
that more documentation and examples beyond the source code are needed --
if only to save themselves time in responding. But ultimately that is their
 I already read your note to Allan Issac on this list in which you
expressed similar sentiments: That is why I didn't incorporate any
LaTeX/BiBTeX code in my postings.
 I appreciate that the note was long and you are busy. It may surprise
you that this is also true for your docutils users whom you ask to jump
through hoops and whose time is also burnt up when posting. All of us
participate -- post and respond -- on this list by choice. But please don't
blow off answering my questions by demanding endless clarifications and
then incorrectly claiming that I haven't provided what you asked for.
 How do I know this? I have implemented a working solution but it uses
stock python (clearly kludgey but < 100 lines) to parse the reST source
(all it does is capture the custom role contents which is really just a
string and replace it with another string which provides the expanded
content based on the list of keys).
 In no small measure because I have read your multiple previous posting
on this list responding to other users saying you won't go in that
direction of providing any database/citation/bibtex support in docutils.
But also note 
 In fact Guenter and Englebert have already provided the reST citation
directive with potential bibtex functionality when reST is translated into
LaTeX See the use-bibtex option in rst2latex (in the current distribution
of python-docutils) and rst2pdf.py -- authored by Guenter and on the web --
and corresponding code. But at least in this posting thread I haven't been
using this route nor asking about it.
 For example "The Docutils Hacker's Guide" has been left incomplete for
years. Completing this would take work for the developers but might be "the
stitch in time that saves nine" It certainly IMHO would cut down on
aggravation in the docutils-user list. Again your time, your project, your
 It should be obvious that users are actually project supporters and not
developer/maintainer adversaries. They don't deserve to be essentially told
to get lost -- eg Maybe "Docutils isn't the right tool for the job" -- if
the code author/maintainer doesn't like/understand their questions or the
issues being raised.
-- David Goodger
> > In my view it provided a richer markup set than markdown and more
> > natural and pythonic code base for extension. Unwinding my actual code
> is a
> > little bit difficult because it is interwined with the python web
> > "BottlePy" that I am using and its native simple template. But I will
> > to provide more explanation to better help you help me.
> > It seems to me what I want to do is "publish" html and latex from the
> > reST input source and by using the doctree nodes Actually the modality
> > producing the source to be published by the latex writer is along the
> > that I think that you suggested ie producing transformed reST for further
> > processing But the translation to html is somewhat different because I
> > want to produce an interactive web page.
> > Now in detail. I have been trying to insert annotated bibliographies
> > my reST documents using a custom "bibentries" directive.
> > A more real example piece of my typical reST source would look like this:
> > .. bibentries::
> > Bad85 This is a note for a single paper; the markup end delimiter
> > is two semicolons allowing a single semicolon in the note;;
> > PB94;;
> > Dwy04;;
> > The custom role directive wraps a list of entries. A given document might
> > have 4-5 of these lists. The entries are delimited by two ";;" and can
> be on
> > the same or separate lines. Each entry has two subfields separated by a
> > space: the first subfield is a citation key which identifies the
> > for my bibtex databases and the second is a note to be attached to the
> > paper.
> > Once this is gathered I can much it on my own -- the directive snippet
> > I proved to be an exceptionally easy way of scooping up the bib entry
> > from the reST document.
> > I then produce somewhat more complex html: the entries become a list. The
> > rendered page provides some form interaction options for the user. This
> > requires a translation to "fatten" the reST source. Here is a snippet of
> > html that I produce via the "raw" approach using the custom directive
> > in a very similar fashion to my note. This seems to run counter to the
> > advice
> > <ol>
> > <li>
> > <!-- -->
> > <input type="checkbox" name="entries" value="Articles/Bad85"
> > class="chkAll"/>
> > <!-- -->
> > [Articles/<a href = "/Bibs/Articles/Bad85">Bad85</a>:
> > <a href = "http://pubs.acs.org/doi/abs/10.1021/ar00109a003">url</a>
> > <a href = "/data/Pdfs/Articles/Bad85.pdf">pdf</a>]
> > Bader.
> > Atoms in molecules.
> > In <i>Accounts of Chemical Research</i>
> > <b>18</b> (1): p. 9-15, 1985
> > <blockquote class="abstract">
> > Approximate quantum mechanical state functions have recently been
> > obtained for the norbornyl cation. These calculations have yielded the
> > energy of its equilibrium geometry and the relative energies of
> > neighboring geometries. It is the purpose of this account to
> > illustrate that more chemical information than simply energies and
> > their associated geometries can be obtained directly from a state
> > function. A state function contains the necessary information to both
> > define the atoms in a molecule and determine their average properties.
> > It also enables one to assign a structure, that is, determine the
> > network of bonds linking the atoms in a molecule and determine whether
> > or not the structure is table. The state function further determines
> > where electronic charge is locally concentrated and depleted. Quantum
> > mechanics can be used to relate these properties to local energy
> > contributions, thereby providing an understanding of the geometry and
> > reactivity of a molecule. (Summary prepared by MGP 120530)
> > </blockquote>
> > <p>Note: This is a note for a single paper; the markup end delimiter is
> > semicolons allowing a single semicolon in the note</p>
> > </li>
> > This part worked fine for me. But now I want to translate the page to
> > both for pdf printing and possible collaborative documents. I like the
> > the doctree scoops up the custom directive contents. And in this case I
> > just retranslate my original reST source to a new reST document with the
> > bibliographic information for latexing -- actually easier. But I don't
> > understand the right "Docutilic" idiom for coding this using the parsed
> > doctree and then "publishing" from the same reST source to either html or
> > latex as needed.
> > So right now I am just munching on the original reST source to extract
> > bibentries stuff, use it to create my annotated bibliography list, and
> > write it a reST document for latexing. (This part is also working) Here
> is a
> > snippet of my retranslated resT which can be published to latex with the
> > latex2e writer (and processed to pdf):
> > #.
> > [Articles/Bad85:
> > url
> > pdf]
> > Bader.
> > Atoms in molecules.
> > In *Accounts of Chemical Research*
> > **18**
> > (1):
> > p. 9-15,
> > 1985
> > Approximate quantum mechanical state functions have recently
> > been obtained for the norbornyl cation. These calculations
> > have yielded the energy of its equilibrium geometry and the
> > relative energies of neighboring geometries. It is the
> > purpose of this account to illustrate that more chemical
> > information than simply energies and their associated
> > geometries can be obtained directly from a state function. A
> > state function contains the necessary information to both
> > define the atoms in a molecule and determine their average
> > properties. It also enables one to assign a structure, that
> > is, determine the network of bonds linking the atoms in a
> > molecule and determine whether or not the structure is table.
> > The state function further determines where electronic charge
> > is locally concentrated and depleted. Quantum mechanics can
> > be used to relate these properties to local energy
> > contributions, thereby providing an understanding of the
> > geometry and reactivity of a molecule. (Summary prepared by
> > MGP 120530)
> > Note: This is a note for a single paper; the markup end delimiter is
> > semicolons allowing a single semicolon in the note
> > Once again thanks to you, the maintainers, and the list for following
> > through on reading my somewhat extended pposts. Docutils is a big
> project of
> > immense and of self-evident value to the Python community and beyond. I
> > understand that you and your colleagues are volunteering your valuable to
> > time to support this project.
> > Michael
> > On Tue, May 14, 2013 at 12:29 AM, David Goodger <goodger@...>
> >> On Mon, May 13, 2013 at 8:13 PM, Michael Prisant
> >> <michael.prisant@...> wrote:
> >> > Yes this is a dumb example but I think it is enough to get started.
> >> > can
> >> > this question be made more simple or specific?
> >> You can start by giving us a minimal but *real* example of what you
> >> want as output. I think you're over-complicating the issue by trying
> >> to simplify it in an unnatural way.
> >> Unnatural, because the it's the job of the Writer classes to translate
> >> Docutils document trees (doctrees) into their final formats. Don't try
> >> to do the job of Writers from within your directive, that's the wrong
> >> approach. You should be trying to write correct doctree nodes from
> >> your code.
> >> Apart from the differences in markup/tagging/codes, do you really need
> >> different output from the two writers? IOW, does the content itself
> >> (the rendered text & functionality) have to change depending on the
> >> output format?
> >> Don't worry about the HTML or LaTeX output, except to illustrate what
> >> you want. Show us some real input, and some real desired output.
> >> > PS Hoping that this can be posted to list in under 5 days!
> >> Are you talking about your message, or the reply? If your message, it
> >> could be that the first time you posted, you weren't a member, and
> >> somebody (me) had to approve the post first, and I was otherwise busy.
> >> Sometimes it takes me a while to get to list moderation.
> >> If you're talking about the reply, well, sorry, but sometimes it takes
> >> a while for people to carve time out of their busy lives.
> >> --
> >> David Goodger <http://python.net/~goodger>
> > --
> > Michael G. Prisant
Michael G. Prisant