From: Guenter M. <mi...@us...> - 2013-02-11 15:30:39
|
On 2013-02-10, David Goodger wrote: > On Sun, Feb 10, 2013 at 12:11 AM, Guenter Milde <mi...@us...> wrote: >> On 2013-02-10, David Goodger wrote: >>> On Sat, Feb 9, 2013 at 3:44 AM, Dmitry Shachnev <mi...@gm...> wrote: >>>> It would be good if Docutils supported something similar to Markdown >>>> named references[1]. >> ... >>> To remove the ambiguity, we could extend the "Embedded URIs" syntax >>> [1]_ as follows. If the text between the <> angle brackets ends with >>> an unescaped "_", it is considered an "embedded indirect reference", >>> and is treated similarly to indirect hyperlink targets [2]_. >>> .. [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#embedded-uris >>> .. [2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#indirect-hyperlink-targets ... >>> """ >>> See the `somefile section <somefile.txt_>`_. >>> ... later on ... >>> somefile.txt >>>============ >>> Get the file `right here <somefile.txt>`_. >>> """ >>> Above, the first reference would be to the section, and the last >>> reference would still be to the file. ... >>> Does anyone see a problem with this syntax? Or can anyone propose a >>> better syntax? >> I'd prefer the syntax already established for named footnote references:: >> Footnotes with 'autonumber labels' - for instance, [#funny]_ and >> [#boring]_. >> .. [#boring] boring footnote >> .. [#funny] funny footnote >> which would look like: >> Here is a `link with named reference <#REF>`_. Here is `another >> one <#REF>`_. Or we can `use a number <#1>`_ here. > ... >> As always in reST, the hash sign can be escaped like ```\#```. > No, "#" doesn't apply. > I chose it for footnotes because "#" means > "number" (in North American culture, at least; I believe it may not be > the case in Europe and/or other parts of the world). Most people in > North America call "#" a "number sign". It is equivalent to "№". For > background, see <http://en.wikipedia.org/wiki/Number_sign>. However: In URIs a hashmark # introduces the optional fragment near the end of the URL. -- http://en.wikipedia.org/wiki/Fragment_identifier The HTML code for an anchor to the internal link "name" is ```<a class="reference internal" href="#name">name</a>``` So, the conotation is not as unambiguous even in America. > We use "_" to mark hyperlink references and targets: > The underscore can be thought of as a right-pointing > arrow. The trailing underscores point away from hyperlink references, > and the leading underscores point toward `hyperlink targets`_. > -- http://docutils.sf.net/docs/ref/rst/restructuredtext.html#hyperlink-references > I think the `embedded <reference_>`_ syntax, although a bit unsightly, > makes the most sense. That's our best option for now. I can't think of > anything better, but maybe someone else can. OK. Günter |