Hi,

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@python.org> wrote:
On Tue, May 14, 2013 at 1:56 AM, Michael Prisant
<michael.prisant@gmail.com> 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 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.

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.[1] 
 
I
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.  [2]

> First in overview. I am trying to write a sort of annotated bibliography
> wiki application using reST as the underlying markup language for the wiki
> 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.[3]  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 alternatives.

That is why it merits reasonably readable and complete documentation.[6] And when the user mailing list identifies gaps in that documentation, developer and maintainers should provide civil responses to their users.[7] 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 choice.

Michael

[1] 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.

[2] 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.
 
[3] 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).

[4] 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 [5]

[5] 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.

[6] 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 choice.

[7] 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 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;;
>
>     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 reference
> 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 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
> 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 two
> 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 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):
>
> #.
>     [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 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.
>
> Michael
>
>
>
> On Tue, May 14, 2013 at 12:29 AM, David Goodger <goodger@python.org> wrote:
>>
>> On Mon, May 13, 2013 at 8:13 PM, Michael Prisant
>> <michael.prisant@gmail.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



--
Michael G. Prisant