Re: [Docutils-users] ISBN URL?

[David G. <go...@py...>]

In my inbox I noticed that this went without any replies. Better
(very) late than never!?

On Fri, Jul 1, 2016 at 3:11 PM, Matej Cepl <mc...@ce...> wrote:
> Hi,
>
> I still cannot shake off a bad habit of reading pieces of dead
> wood, so I refer in my writing quite often to ISBNs. So, normally
> it looks like this:
>
>     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>     Phasellus at tellus sollicitudin, pellentesque orci a, ornare
>     risus. Vivamus et quam a felis aliquet sollicitudin quis ac
>     orci “`Four loves`_”.  Vestibulum pretium dui dolor, ac
>     ullamcorper sapien suscipit sed.
>
>     .. _`Four loves`:
>         https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301
>
> I would prefer to be able either to use the reference like
>
>     .. _`Four loves`:
>         isbn:0156329301
>
> and docutils would generate proper URL
...
> Do you know about something like this already made?

This is very similar to the RFC & PEP roles (e.g. :RFC:`2732` &
:PEP:`12`), although those show the numbers, and I infer that you
don't want to show the actual ISBN. See the code in
docutils/parsers/rst/roles.py

> or to go all the way to...:
>
>     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>     Phasellus at tellus sollicitudin, pellentesque orci a, ornare
>     risus. Vivamus et quam a felis aliquet sollicitudin quis ac
>     orci isbn::``“Four loves”``,``0156329301``.  Vestibulum
>     pretium dui dolor, ac ullamcorper sapien suscipit sed.
...
> (how to make docutils role with two parameters?)

This has not been done in core Docutils. I don't know if Sphinx has
implemented a scheme for multi-parameter roles, or not (anyone?).
Several syntax options are described here:
http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#parameterized-interpreted-text

Choosing one syntax option arbitrarily, for example, an ISBN role
could be implemented that takes this reST::

    :ISBN:`The Four Loves <0156329301>`

and results in HTML like::

    <a href="https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301">The
Four Loves</a>

One might want the ISBN itself and not the title, so::

    :ISBN:`0156329301`

could result in this HTML::

    <a href="https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301">ISBN
0156329301</a>

This could either be implemented as a single ISBN role with different
output depending on the input, or as two separate roles (e.g. ISBN for
the number without a title, and refisbn for the titled reference).

> If I am
> reading correctly the documentation_, does it mean that I have to
> write some Python?
...
> .. _documentation:
>     http://docutils.sourceforge.net/docs/howto/rst-roles.html

Yes.

> And if yes (I am a Python programmer, so it is
> not that big obstacle), could I somehow package it as
> a standalone Python package uploadable to PyPI?

Typically, I've seen such extensions be imported and registered from a
custom front-end tool. Docutils doesn't have a plug-in system.

On the other hand, if you implement this properly, there's no reason
it couldn't be added to core Docutils.

> Are there any
> such packages already available on PyPI? I cannot find any.

I don't know.

David Goodger
<http://python.net/~goodger>