Re: [Docutils-users] ISBN URL?

[Guenter M. <mi...@us...>]

On 2017-05-10, David Goodger wrote:
> 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:
...
>>     orci “`Four loves`_”.  Vestibulum pretium dui dolor, ac
...

>>     .. _`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?

RFC-3187__ defines the mechanism for mapping an ISBN to a URN.

__ http://www.faqs.org/rfcs/rfc3187.html

For example: "urn:ISBN:1-56592-149-6"

  Note that the hyphens in the ISBN are optional (and should be removed
  before comparing two ISBN URNs) and that the 'ISBN' URN namespace
  identifier is case-insensitive.

  -- http://www.ukoln.ac.uk/metadata/dcmi-ieee/identifiers/

In theory, RFC 2187 is implemented
(https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml),
i.e. the rst source::

   `The Four Loves <urn:isbn:0156329301>`__ (embedded)
   
   The Four Loves: urn:ISBN:0156329301      (stand alone)
   
   
   `The Four Loves`_                        ("classical")
   
   .. _the four loves: urn:ISBN:0156329301

results in valid HTML.

Unfortunately, this does not help in praxi, as
        
  Your browser would have to have a "resolver" installed for ISBN numbers
  that would find a URL for the resource. As far as I know, no browsers
  have taken a stab at implementing resolvers as called for by the RFC.
  –- Stephen Ostermiller Feb 24 at 8:57 
  
  http://stackoverflow.com/questions/4913343/what-is-the-difference-between-uri-url-and-urn



> 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.

...

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



Alternatively, Docutils could provide a "URN resolver" for ISBNs.

An transform would map ``refuri="urn:ISBN:0156329301"`` to an URL using a
configurable URL template similar to the ``rfc-base-url``.


Another alternative would be an "ISBN namespace" for rST hyperlink targets,
for constructs like ::

 .. _The Four Loves: ISBN:0156329301

or ::

 `The Four Loves <ISBN:0156329301>`_

and similar to relative URLs with alias like `` `<foobar.py>`_`` ::

  The Four Loves `<ISBN:0156329301>`_


This way, we can leverage the existing syntax that provides flexibility for
both, display or hiding of the actual number without the need to open the
can of parameterized roles.


Günter