On 12 April 2013 21:26, Carl Cerecke <carl@free.org.nz> wrote:

On 8 April 2013 22:36, Guenter Milde†<milde@users.sf.net>†wrote:

On 2013-04-06, Carl Cerecke wrote:

> While waiting for someone more knowledgeable to reply, I had a bit of a
> look at the code. I can get pretty much what I want by modifying
> rst2latex.py to use a different reader:

> publish_cmdline(writer_name='latex', description=description,
> reader_name='bibleref_standalone')


> If I'm on the right track, it would be nice to know. If there's a better
> way, that would also be nice to know.

This is one possibility. Depending on what exact you want, you may also just
use an expanded front-end (bibleref2tex.py instead of rst2latex, say).

In the front-end, you may load and expand the reader/writer/transform as
required. There are examples in the sandbox repository.

I'm currently trying out Paver to manage the build process, and call publish_file to do the transformation.

> On 6 April 2013 14:40, Carl Cerecke <carl@free.org.nz> wrote:


>> So, in summary, something like this would be desirable for the source doc
>> in the three cases:

>> 1. Lorem ipsum `John 3:16`_ dolor
>> 2. Lorem ipsum `John 3:16-18`_ dolor
>> 3. Lorem ipsum `verse 16 <John 3:16>`_ dolor

>> where, during processing, the verse references can be resolved to
>> hyperlinks, and the appropriate output is generated.

>> I realise that I'll have to write some code to get this to work, and I'm
>> fine with that.

>> But, is this a sensible thing to do? Is there a better way?
>> Where would I start plugging this sort of functionality in to reST?

I think the "canonical rST-way" to do this would be a text role::

† In :verse:`John 3:16`, St. John writes ...

If you set the "default role", the syntax becomes concise::

† In `John 3:16`, St. John writes ...

For your task, a simple custom role would not suffice, as some more
processing logic is required. The "pep" and "rfc" roles are examples for
roles with a special linking behaviour, so you may copy and adapt much of
the sources.

This is interesting. I realise that hijacking references (they way I first sought to achieve what I want) is not ideal, though conceptually they are still references - they just have to be resolved by a program (rather than statically) at transform time.

But text roles--- using the proper extension mechanism--- look like a possibly cleaner solution, especially as a default role. In the case where the text of the reference is different from the reference itself (case 3 in my earlier email), I could use a character separator perhaps:

Lorem ipsum `verse 16|John 3:16` dolor

Thanks, GŁnter. I'll try that and see how it goes.

Just following up on my own email... I've implemented a custom role (:verse:), and made it the default. It uses a small parser to parse the verse reference(s) and adds reference nodes to the output. Text like

Lorem ipsum `John 3:1-3, 7, 4:16, Mark 5:1` dolor

gets output as 4 hyperlinks, each with the text appropriate to that reference (so the text '7', which is a verse reference to 'John 3:7', becomes a hyperlink for that verse reference).

Very convenient. Thanks for the idea!

(as an aside for parsing geeks: the verse definition 'language' isn't LR(1) - it requires two tokens of look-ahead, and also has an ambiguity to resolve. Ended up implementing it by hand using a small state machine - there's a few tricky bits in there)