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')

with the file bibleref_standalone.py looking like:

__docformat__ = 'reStructuredText'

import sys

from docutils import readers, nodes
from docutils.transforms import Transform
from docutils.readers import standalone

class Reader(standalone.Reader):
    def get_transforms(self):
        return super().get_transforms() + [BibleReferences]
def is_bible_ref(text):
    return text == 'john 3:16' # stub
def link_for_bible_ref(ref_text):
    return 'http://some.bible.site.com/'+ref_text+'.html' # stub

class BibleReferences(Transform):
    default_priority = 840
    def apply(self):
        for ref in self.document.traverse(nodes.reference):
            if ref.hasattr('refuri'):
            print(ref, file=sys.stderr)
            if ref.hasattr('refname') and is_bible_ref(ref['refname']):
                ref['refuri'] = link_for_bible_ref(ref['refname'])
                print(ref, file=sys.stderr)

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.


On 6 April 2013 14:40, Carl Cerecke <carl@free.org.nz> wrote:
I'm investigating reST as a primary source for a biblical-commentary modernisation project.

reST ticks most of the boxes - multiple output formats (targeting html and pdf initially), relative simplicity, an "include" capability, extensibility.

But one thing that is a potential roadblock is a convenient way to represent verse references: I want output formats to be able to link to an online bible-reference provider for verse references. So, for example, text can include a bible reference like John 3:16, which in the output that text is a hyperlink to an online verse provider. The catch is that I want the hyperlink to be specified during output generation time (different websites/bible version, perhaps). Other complications include specifying verse ranges (so a simple pre-generated enumeration of all verses won't work), and the text of the reference can be different from the reference itself (e.g. "we see in verse 16 that ...", where "verse 16" should be a reference to "John 3:16" (or verse 16 of whatever chapter and book are implied by the context).

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?