[Docutils-users] ISBN URL?

[Matej Cepl]

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, or to go all the way to
(how to make docutils role with two parameters?):

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.

Do you know about something like this already made? If I am
reading correctly the documentation_, does it mean that I have to
write some Python? 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? Are there any
such packages already available on PyPI? I cannot find any.

Thanks for any replies,

Matěj

.. _documentation:
http://docutils.sourceforge.net/docs/howto/rst-roles.html

[David Goodger]

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

Post by Matej Cepl
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
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.
https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301
I would prefer to be able either to use the reference like
isbn:0156329301
and docutils would generate proper URL

...

Post by Matej Cepl
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

Post by Matej Cepl
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.

...

Post by Matej Cepl
(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).

Post by Matej Cepl
If I am
reading correctly the documentation_, does it mean that I have to
write some Python?

...

Post by Matej Cepl
http://docutils.sourceforge.net/docs/howto/rst-roles.html

Yes.

Post by Matej Cepl
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.

Post by Matej Cepl
Are there any
such packages already available on PyPI? I cannot find any.

I don't know.

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

[Matěj Cepl]

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

I have made it into https://gitlab.com/mcepl/docutils/issues/1
on my repo and I will take a look one day (of course, merge
requests are welcome).

Post by David Goodger
Choosing one syntax option arbitrarily, for example, an ISBN
:ISBN:`The Four Loves <0156329301>`
<a href="https://en.w…ces?isbn=0156329301">The
Four Loves</a>

I think this is the one I would implement. Showing plain ISBN
numbers in the text is a bad idea IMHO and should be made
difficult. And perhaps the URL should be made configurable so we
and our users are not forever dependent on the English
Wikipedia.

Matěj

[David Goodger]

Post by Matěj Cepl

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

I have made it into https://gitlab.com/mcepl/docutils/issues/1
on my repo and I will take a look one day (of course, merge
requests are welcome).

Post by David Goodger
Choosing one syntax option arbitrarily, for example, an ISBN
:ISBN:`The Four Loves <0156329301>`
<a href="https://en.w…ces?isbn=0156329301">The
Four Loves</a>

I think this is the one I would implement. Showing plain ISBN
numbers in the text is a bad idea IMHO and should be made
difficult.

I disagree. I can envisage cases where one might want to write something like,

See `The Four Loves` by C. S. Lewis (:ISBN:`0156329301`).

Note: the result would *not* be just a plain ISBN number, but "ISBN" +
the number, in a link.

Flexibility is a good thing.

Post by Matěj Cepl
And perhaps the URL should be made configurable so we
and our users are not forever dependent on the English
Wikipedia.

Sure.

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

[Matěj Cepl]

Post by David Goodger
I disagree. I can envisage cases where one might want to write
something like,
See `The Four Loves` by C. S. Lewis (:ISBN:`0156329301`).
Note: the result would *not* be just a plain ISBN number, but "ISBN" +
the number, in a link.
Flexibility is a good thing.

I did not say that this could not be useful for some exceptional
cases (inside of the list of references), but the normal
situation should what I described.

Matěj
--
https://matej.ceplovi.cz/blog/, Jabber: ***@ceplovi.cz
GPG Finger: 3C76 A027 CA45 AD70 98B5 BC1D 7920 5802 880B C9D8

Of course I'm respectable. I'm old. Politicians, ugly buildings,
and whores all get respectable if they last long enough.
--John Huston in "Chinatown."


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to

[Guenter Milde]

Post by David Goodger

Post by Matej Cepl
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

...

Post by David Goodger

Post by Matej Cepl
orci “`Four loves`_”. Vestibulum pretium dui dolor, ac

...

Post by David Goodger

Post by Matej Cepl
https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301
I would prefer to be able either to use the reference like
isbn:0156329301
and docutils would generate proper URL

...

Post by Matej Cepl
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

Post by David Goodger
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.

...

Post by David Goodger
http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#parameterized-interpreted-text
Choosing one syntax option arbitrarily, for example, an ISBN role
:ISBN:`The Four Loves <0156329301>`
<a href="https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301">The
Four Loves</a>
:ISBN:`0156329301`
<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





------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to