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 1:56 AM, Michael PrisantIn what way, exactly, do they have to differ? And please: *briefly*.
> 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 that
> "yes I think that the rendered text and functionality" are different in the
> html and latex published versions so it really has to change depending on
> the output format.
Sorry, I don't have time to read long email messages like this one.
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.
That's about all the advice I can give. I don't know
bibtex/bibliography details, and I have no desire to learn them.
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.
> First in overview. I am trying to write a sort of annotated bibliographyISTM that you may be trying to load too much functionality onto
> wiki application using reST as the underlying markup language for the wiki
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.
You can still use reST for your text content, but don't try to get
Docutils to support the database-backed dynamic web stuff.
-- 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 framework
> "BottlePy" that I am using and its native simple template. But I will try
> 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 same
> reST input source and by using the doctree nodes Actually the modality of
> producing the source to be published by the latex writer is along the lines
> that I think that you suggested ie producing transformed reST for further
> processing But the translation to html is somewhat different because I am
> want to produce an interactive web page.
> Now in detail. I have been trying to insert annotated bibliographies within
> 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;;
> 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 reference
> for my bibtex databases and the second is a note to be attached to the
> Once this is gathered I can much it on my own -- the directive snippet that
> I proved to be an exceptionally easy way of scooping up the bib entry data
> 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 coded
> in a very similar fashion to my note. This seems to run counter to the
> <!-- -->
> <input type="checkbox" name="entries" value="Articles/Bad85"
> <!-- -->
> [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>]
> 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)
> <p>Note: This is a note for a single paper; the markup end delimiter is two
> semicolons allowing a single semicolon in the note</p>
> This part worked fine for me. But now I want to translate the page to latex
> both for pdf printing and possible collaborative documents. I like the way
> 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 the
> bibentries stuff, use it to create my annotated bibliography list, and then
> 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):
> Atoms in molecules.
> In *Accounts of Chemical Research*
> p. 9-15,
> 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 two
> 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.
> On Tue, May 14, 2013 at 12:29 AM, David Goodger <firstname.lastname@example.org> wrote:
>> On Mon, May 13, 2013 at 8:13 PM, Michael Prisant
>> <email@example.com> wrote:
>> > Yes this is a dumb example but I think it is enough to get started. How
>> > 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