From: Dmitry S. <mi...@gm...> - 2013-02-09 09:48:05
Attachments:
signature.asc
|
Hi, It would be good if Docutils supported something similar to Markdown named references[1]. Two main things this feature will allow is: * Referencing the same URI multiple times with different text every time; * Translating the links (for example, in Ubuntu Packaging Guide we are using Sphinx with l10n module and currently we have to not translate links at all or use inline links which is not very usable). Proposed syntax: Here is a `link with named reference<REF>`_. Here is `another one<REF>`_. Or we can `use a number<1>`_ here. Here is also a link_ and `another link<link>`_ referencing the first one. .. _REF: http://www.python.org/ .. _1: http://www.example.com/ .. _link: http://docutils.sourceforge.net/ When a link reference is not defined, it will work as a normal reStructuredText link (i.e. point to a local file). Comments welcomed (please CC me!). I may propose a patch if this is approved. [1]: Example of Markdown syntax: Here is [a link with named reference][REF]. Here is [another one][REF]. [REF]: http://www.example.com/ -- Dmitry Shachnev |
From: David G. <go...@py...> - 2013-02-10 02:44:39
|
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]. Two main things this feature will allow is: > > * Referencing the same URI multiple times with different text > every time; > * Translating the links (for example, in Ubuntu Packaging Guide we > are using Sphinx with l10n module and currently we have to not > translate links at all or use inline links which is not very > usable). I'm open to the idea. I think I've wanted similar functionality a few times myself. > Proposed syntax: > > Here is a `link with named reference<REF>`_. Here is `another > one<REF>`_. Or we can `use a number<1>`_ here. > > Here is also a link_ and `another link<link>`_ referencing the > first one. > > .. _REF: http://www.python.org/ > .. _1: http://www.example.com/ > .. _link: http://docutils.sourceforge.net/ > > When a link reference is not defined, it will work as a normal > reStructuredText link (i.e. point to a local file). (Minor nit: be careful, you're missing spaces before the "<" markers above.) This proposal has promise. I cannot take it as-is, because it makes the difference between an indirect reference and a relative URL ambiguous. Reference names in reST can look just like a path or a file: """ See the somefile.txt_ section. ... later on ... somefile.txt ============ Get the file `right here <somefile.txt>`_. """ With your proposal, the above would be ambiguous. Does the second reference refer to the section, or to a relative URL? I hate ambiguity. The above is unambiguous under the current syntax (but lacks the functionality you want, of course). 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 Using your example: """ Here is a `link with named reference <REF_>`_. Here is `another one <REF_>`_. Or we can `use a number <1_>`_ here. Here is also a link_ and `another link <link_>`_ referencing the first one. .. _REF: http://www.python.org/ .. _1: http://www.example.com/ .. _link: http://docutils.sourceforge.net/ """ Expanding my earlier example a bit: """ 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. For phrase references, back-quotes would neither be necessary nor recognized. """ `Here's an example that refers to a <multi-word section title_>`_, say. """ If the author wants to embed a URL that ends with an underscore, they'd do it by escaping the underscore, `like this <http://example.org/path\_>`_. Does anyone see a problem with this syntax? Or can anyone propose a better syntax? > Comments welcomed (please CC me!). I may propose a patch if this is > approved. That would be great, thanks. Please include tests and documentation patches, if at all possible. The more complete a patch you provide, the more likely the patch will be accepted. > [1]: Example of Markdown syntax: > > Here is [a link with named reference][REF]. Here is [another one][REF]. > > [REF]: http://www.example.com/ -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-10 06:11:38
|
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]. ... > I'm open to the idea. I think I've wanted similar functionality a few > times myself. ... >> Proposed syntax: >> Here is a `link with named reference<REF>`_. Here is `another >> one<REF>`_. Or we can `use a number<1>`_ here. ... > This proposal has promise. I cannot take it as-is, because it makes > the difference between an indirect reference and a relative URL > ambiguous. Reference names in reST can look just like a path or a > file: > """ > See the somefile.txt_ section. > ... later on ... > somefile.txt >============ > Get the file `right here <somefile.txt>`_. > """ > With your proposal, the above would be ambiguous. Does the second > reference refer to the section, or to a relative URL? I hate > ambiguity. The above is unambiguous under the current syntax (but > lacks the functionality you want, of course). We could remove the ambiguity by defining that the internal link always takes precedence. To override this or give an explicitely unambiguous URL, the user could include a scheme:: Get the file `right here <file:somefile.txt>`_. or :: Get the file `right here <ftp:somefile.txt>`_. or :: Get the file `right here <http:somefile.txt>`_. > 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 > Using your example: > """ > Here is a `link with named reference <REF_>`_. Here is `another > one <REF_>`_. Or we can `use a number <1_>`_ here. > Here is also a link_ and `another link <link_>`_ referencing the > first one. > .. _REF: http://www.python.org/ > .. _1: http://www.example.com/ > .. _link: http://docutils.sourceforge.net/ > """ > Expanding my earlier example a bit: > """ > 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. > For phrase references, back-quotes would neither be necessary nor recognized. > """ > `Here's an example that refers to a <multi-word section title_>`_, say. > """ > If the author wants to embed a URL that ends with an underscore, > they'd do it by escaping the underscore, `like this ><http://example.org/path\_>`_. > 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. Here is also a link_ and `another link <#link>`_ referencing the first one. .. _REF: http://www.python.org/ .. _1: http://www.example.com/ .. _link: http://docutils.sourceforge.net/ """ See the `somefile section <#somefile.txt>`_. ... later on ... somefile.txt =========== Get the file `right here <somefile.txt>`_. .. _REF: http://www.python.org/ .. _1: http://www.example.com/ .. _link: http://docutils.sourceforge.net/ As always in reST, the hash sign can be escaped like ```\#```. Günter |
From: David G. <go...@py...> - 2013-02-10 22:45:49
|
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]. > > ... > >> I'm open to the idea. I think I've wanted similar functionality a few >> times myself. > > ... > >>> Proposed syntax: > >>> Here is a `link with named reference<REF>`_. Here is `another >>> one<REF>`_. Or we can `use a number<1>`_ here. > > ... > >> This proposal has promise. I cannot take it as-is, because it makes >> the difference between an indirect reference and a relative URL >> ambiguous. Reference names in reST can look just like a path or a >> file: > >> """ >> See the somefile.txt_ section. > >> ... later on ... > >> somefile.txt >>============ > >> Get the file `right here <somefile.txt>`_. >> """ > >> With your proposal, the above would be ambiguous. Does the second >> reference refer to the section, or to a relative URL? I hate >> ambiguity. The above is unambiguous under the current syntax (but >> lacks the functionality you want, of course). > > We could remove the ambiguity by defining that the internal link always > takes precedence. But that would mean that some documents that are currently correct would, after a Docutils upgrade, suddenly become incorrect. Semantics would change. That's bad. > To override this or give an explicitely unambiguous URL, > the user could include a scheme:: > > Get the file `right here <file:somefile.txt>`_. > > or :: > > Get the file `right here <ftp:somefile.txt>`_. > > or :: > > Get the file `right here <http:somefile.txt>`_. That's a kludge. I'd rather not add such a burden to the currently-correct mechanism. >> 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 > >> Using your example: > >> """ >> Here is a `link with named reference <REF_>`_. Here is `another >> one <REF_>`_. Or we can `use a number <1_>`_ here. > >> Here is also a link_ and `another link <link_>`_ referencing the >> first one. > >> .. _REF: http://www.python.org/ >> .. _1: http://www.example.com/ >> .. _link: http://docutils.sourceforge.net/ >> """ > >> Expanding my earlier example a bit: > >> """ >> 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. > >> For phrase references, back-quotes would neither be necessary nor recognized. > >> """ >> `Here's an example that refers to a <multi-word section title_>`_, say. >> """ > >> If the author wants to embed a URL that ends with an underscore, >> they'd do it by escaping the underscore, `like this >><http://example.org/path\_>`_. > >> 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>. "[#name]" is converted to "[1]" (or some number). The correspondence between "#" and "number" is important. 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. -- David Goodger <http://python.net/~goodger> |
From: Dmitry S. <mi...@gm...> - 2013-02-10 07:48:02
|
Hi David, On Sun, Feb 10, 2013 at 6:43 AM, David Goodger <go...@py...> wrote: > I'm open to the idea. I think I've wanted similar functionality a few > times myself. I'm glad you liked it :) > 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]_. Why not s/ends with/starts with/? There is less chance that the URL starts with _, and this will match the actual reference (.. _REF: http://www.python.org/). >> Comments welcomed (please CC me!). I may propose a patch if this is >> approved. > > That would be great, thanks. Please include tests and documentation > patches, if at all possible. The more complete a patch you provide, > the more likely the patch will be accepted. OK, I'll look at it now. -- Dmitry Shachnev |
From: David G. <go...@py...> - 2013-02-10 22:30:56
|
On Sun, Feb 10, 2013 at 1:47 AM, Dmitry Shachnev <mi...@gm...> wrote: > Hi David, > > On Sun, Feb 10, 2013 at 6:43 AM, David Goodger <go...@py...> wrote: >> I'm open to the idea. I think I've wanted similar functionality a few >> times myself. > > I'm glad you liked it :) > >> 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]_. > > Why not s/ends with/starts with/? There is less chance that the URL > starts with _, and this will match the actual reference > (.. _REF: http://www.python.org/). Because ".. _REF:" defines a target. "REF_" marks a reference. What we are doing with this syntax is creating an indirect *reference*. This new syntax basically short circuits the indirect hyperlink target mechanism. The following examples are equivalent: """ Here is a `link with named reference <REF_>`_. .. _REF: http://www.python.org/ """ """ Here is a `link with named reference`_. .. _link with named reference: REF_ .. _REF: http://www.python.org/ """ All we are doing is moving the first target definition, the indirect one, into the inline reference itself. -- David Goodger <http://python.net/~goodger> |
From: Dmitry S. <mi...@gm...> - 2013-02-14 17:40:14
|
I've tried to look at parsers/rst/states.py on weekend, and found out that there is no function to get the reference target *while parsing*, so looks like the change needs to be implemented in (all) the writers. Right? (My only prior experience with docutils code was the config/test part, so maybe I don't know well how it works). I'll be able to take a deeper look this weekend, in the meanwhile I would appreciate any advice on how this should be implemented. -- Dmitry Shachnev On Mon, Feb 11, 2013 at 2:30 AM, David Goodger <go...@py...> wrote: > On Sun, Feb 10, 2013 at 1:47 AM, Dmitry Shachnev <mi...@gm...> wrote: >> Hi David, >> >> On Sun, Feb 10, 2013 at 6:43 AM, David Goodger <go...@py...> wrote: >>> I'm open to the idea. I think I've wanted similar functionality a few >>> times myself. >> >> I'm glad you liked it :) >> >>> 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]_. >> >> Why not s/ends with/starts with/? There is less chance that the URL >> starts with _, and this will match the actual reference >> (.. _REF: http://www.python.org/). > > Because ".. _REF:" defines a target. "REF_" marks a reference. What we > are doing with this syntax is creating an indirect *reference*. > > This new syntax basically short circuits the indirect hyperlink target > mechanism. The following examples are equivalent: > > """ > Here is a `link with named reference <REF_>`_. > > .. _REF: http://www.python.org/ > """ > > """ > Here is a `link with named reference`_. > > .. _link with named reference: REF_ > .. _REF: http://www.python.org/ > """ > > All we are doing is moving the first target definition, the indirect > one, into the inline reference itself. > > -- > David Goodger <http://python.net/~goodger> |
From: Dmitry S. <mi...@gm...> - 2013-02-17 10:32:06
Attachments:
named_references_v0.diff
|
OK, here is a draft patch. It will increase the time as it does some more iterations over self.document.traverse(), but I couldn't find any better approach. On Sun, 10/02/2013 16:30 -0600, David Goodger wrote: > """ > Here is a `link with named reference <REF_>`_. > > .. _REF: http://www.python.org/ > """ > > """ > Here is a `link with named reference`_. > > .. _link with named reference: REF_ > .. _REF: http://www.python.org/ > """ These two examples now work as expected. -- Dmitry Shachnev |
From: Martin B. <m....@gm...> - 2013-02-11 08:34:09
|
[David Goodger] wrote & schrieb: >""" >Here is a `link with named reference <REF_>`_. > >.. _REF: http://www.python.org/ >""" > >""" >Here is a `link with named reference`_. > >.. _link with named reference: REF_ >.. _REF: http://www.python.org/ >""" +1 Looks like a very good solution. It's a very useful feature. Have a good week ... Martin PS: BTW: We are making progress: http://docs.typo3.org It's all about switching old and partly outdated documentation from OpenOffice to ReST - including the (non-?) documentation habits of a whole community ... I'll drop a line about that somewhen later. -- Certified TYPO3 Integrator | TYPO3 Documentation Team Member http://mbless.de |
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 |
From: David G. <go...@py...> - 2013-02-11 15:47:49
|
On Mon, Feb 11, 2013 at 9:30 AM, Guenter Milde <mi...@us...> wrote: > 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. Of course. The non-alphanumeric characters in 7-bit ASCII all have multiple meanings. I was simply explaining why *I* chose "#" for auto-numbered-footnotes, what the connotation is for Docutils. The "#" in HTML URL fragments is completely unrelated. The ambiguity you mention has nothing to do with the issue at hand. (Be careful, I specifically stated North America. I'm Canadian. ;-) >> 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. I'm still open to better ideas... -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-13 09:34:49
|
On 2013-02-11, David Goodger wrote: > On Mon, Feb 11, 2013 at 9:30 AM, Guenter Milde <mi...@us...> wrote: >> 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]. ... >>>>> Does anyone see a problem with this syntax? Or can anyone propose a >>>>> better syntax? I proposed the alternative `internal link <#anchor>`_ but with the wrong explanation. Actually, my proposed syntax is already documented: .. _citation: A hyperlink reference may directly embed a target URI inline, within angle brackets ("<...>") as follows:: See the `Python home page <http://www.python.org>`_ for info. -- `reStructuredText Markup Specification`__ __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#embedded-uris In the example of a file in the current directory given in the original post, the "scheme" specifier is omitted. In the same way, the "file" part can be omitted for anchors in the current document like in this `internal link <#citation>`_ with embedded URI. This even works in the reference implementation: Docutil's HTML writer. I suggest to extend the support to other writers instead of introducing a new special case for internal links. Günter |
From: David G. <go...@py...> - 2013-02-13 15:10:30
|
On Wed, Feb 13, 2013 at 3:34 AM, Guenter Milde <mi...@us...> wrote: > On 2013-02-11, David Goodger wrote: >> On Mon, Feb 11, 2013 at 9:30 AM, Guenter Milde <mi...@us...> wrote: >>> 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]. > > ... > >>>>>> Does anyone see a problem with this syntax? Or can anyone propose a >>>>>> better syntax? > > I proposed the alternative `internal link <#anchor>`_ but with the wrong > explanation. > > Actually, my proposed syntax is already documented: > > .. _citation: > > A hyperlink reference may directly embed a target URI inline, within > angle brackets ("<...>") as follows:: > > See the `Python home page <http://www.python.org>`_ for info. > > -- `reStructuredText Markup Specification`__ > > __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#embedded-uris Sorry, I don't see how this supports your case at all. Please explain further. > In the example of a file in the current directory given in the original > post, the "scheme" specifier is omitted. In the same way, the "file" part > can be omitted for anchors in the current document like in this > `internal link <#citation>`_ with embedded URI. > > This even works in the reference implementation: Docutil's HTML writer. That's very HTML-specific though. If there's a section called, "Section One", you'd need to use a hyperlink like `this <#section-one>`_. Note the name mangling (spaces become hyphens, down-casing). Again, we'd have the problem that `ref <#fragment>`_ currently does one thing, but it would do something *subtly* different under the proposal. > I suggest to extend the support to other writers instead of introducing a > new special case for internal links. -1, unless I misunderstood the argument (if so, please rephrase, with examples). The #-as-fragment-syntax thing is too HTML-specific. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-14 12:23:19
|
On 2013-02-13, David Goodger wrote: > On Wed, Feb 13, 2013 at 3:34 AM, Guenter Milde <mi...@us...> wrote: >> On 2013-02-11, David Goodger wrote: >>> On Mon, Feb 11, 2013 at 9:30 AM, Guenter Milde <mi...@us...> wrote: >>>> 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: ... >> .. _citation: >> A hyperlink reference may directly embed a target URI inline, within >> angle brackets ("<...>") as follows:: >> See the `Python home page <http://www.python.org>`_ for info. >> -- `reStructuredText Markup Specification`__ >> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#embedded-uris > Sorry, I don't see how this supports your case at all. Please explain > further. The `reStructuredText Markup Specification` specifies that within the angle brackets may stand a URI. URI syntax is defined by the W3C. It is independent of HTML. The current definition, `RFC 3986 <http://tools.ietf.org/html/rfc3986#page-24>`_ specifies: 4.2. Relative Reference A relative reference takes advantage of the hierarchical syntax (Section 1.2.3) to express a URI reference relative to the name space of another hierarchical URI. relative-ref = relative-part [ "?" query ] [ "#" fragment ] relative-part = "//" authority path-abempty / path-absolute / path-noscheme / path-empty The URI referred to by a relative reference, also known as the target URI, is obtained by applying the reference resolution algorithm of Section 5. ... 4.4. Same-Document Reference When a URI reference refers to a URI that is, aside from its fragment component (if any), identical to the base URI (Section 5.1), that reference is called a "same-document" reference. The most frequent examples of same-document references are relative references that are empty or include only the number sign ("#") separator followed by a fragment identifier. I read this as: * A URI pointing to a fragment of a document consists of the document URI followed by the number sign ("#") separator followed by a fragment identifier: document fragment URI = document URI + '#' + fragment identifier * a relative URI that only consists of '#' + fragment identifier points to the identified fragment of the current document. * The syntax of the `fragment identifier` itself is not defined by the URI definition (but there are limits regarding allowed characters). >> This even works in the reference implementation: Docutil's HTML writer. > That's very HTML-specific though. If there's a section called, > "Section One", you'd need to use a hyperlink like `this ><#section-one>`_. Note the name mangling (spaces become hyphens, > down-casing). > Again, we'd have the problem that `ref <#fragment>`_ currently does > one thing, but it would do something *subtly* different under the > proposal. >> I suggest to extend the support to other writers instead of introducing a >> new special case for internal links. > -1, unless I misunderstood the argument (if so, please rephrase, with > examples). The #-as-fragment-syntax thing is too HTML-specific. I see two alternatives: a) keep using URIs Embedded URIs ````````````` A hyperlink reference may directly embed a target URI inline, within angle brackets ("<...>") as follows:: See the `Python home page <http://www.python.org>`_ for info. This is exactly equivalent to:: See the `Python home page`_ for info. .. _Python home page: http://www.python.org If the embedded URI points to an internal target (i.e. starts with a number sign``#``), a target link with a matching `reference name`_ must exist somewhere else in the document:: Example Section =============== This `link <#example section>`_ embeds a URI pointing to section `example section`_. b) allow embedded "link blocks" instead of just URIs: Embedded Link Blocks ```````````````````` A hyperlink reference may directly embed a `link block` (target URI or internal hyperlink target) inline, within angle brackets ("<...>") as follows:: See the `Python home page <http://www.python.org>`_ for info. This `link <`Python home page`_>`__ is an alias to the link above. This is exactly equivalent to:: Example Section =============== See the `Python home page`_ for info. This link__ is an alias to the link above. .. _Python home page: http://www.python.org __ `Python home page`_ Actually, while spelling out the specifications I developed a preference for b) because I think it is the more clear concept. Günter |
From: David G. <go...@py...> - 2013-02-15 01:12:27
|
Thanks for the elaboration. On Thu, Feb 14, 2013 at 6:22 AM, Guenter Milde <mi...@us...> wrote: > I see two alternatives: > > a) keep using URIs > > Embedded URIs > ````````````` > > A hyperlink reference may directly embed a target URI inline, within > angle brackets ("<...>") as follows:: > > See the `Python home page <http://www.python.org>`_ for info. > > This is exactly equivalent to:: > > See the `Python home page`_ for info. > > .. _Python home page: http://www.python.org > > If the embedded URI points to an internal target (i.e. starts with a > number sign``#``), a target link with a matching `reference name`_ > must exist somewhere else in the document:: > > Example Section > =============== > > This `link <#example section>`_ embeds a URI pointing to section > `example section`_. The problem I have with this is that it conflates URI #fragments with reST `reference names`_. So if you have a `link <#reference>`_, the parser would have to check for "reference" in the known reference names for that document, use it (resolve to a URI, for HTML) if found, or just use a URI #fragment if not found. That seems like too much ambiguous magic to me. Most tech-savvy people know about URI #fragment syntax. We'd be confusing them with this. And my issue with # being for footnotes stands. > b) allow embedded "link blocks" instead of just URIs: > > Embedded Link Blocks > ```````````````````` > > A hyperlink reference may directly embed a `link block` (target URI or > internal hyperlink target) inline, I wouldn't phrase it that way. I'd use the title "Embedded URIs or References" (no need to make up a category for two variants, and "block" has the body element connotation). They're not hyperlink targets, they're hyperlink references. The distinction is important. > within angle brackets ("<...>") as > follows:: > > See the `Python home page <http://www.python.org>`_ for info. > > This `link <`Python home page`_>`__ is an alias to the link above. Exactly, except that: 1) "`link <`Python home page`_>`__" is really hard to parse, because of nested pairs of backquotes. 2) The "<>" angle brackets do a fine job of delimiting phrase references. So there's no need for the extra set of backquotes. Which reduces the example above to: This `link <Python home page_>`__ is an alias to the link above. Which is the syntax I'm championing. The trailing underscore already means "hyperlink reference" in reST, and we're embedding it inside another (named or anonymous) hyperlink reference for the sake of allowing indirect references. > This is exactly equivalent to:: > > Example Section > =============== > > See the `Python home page`_ for info. > > This link__ is an alias to the link above. > > .. _Python home page: http://www.python.org > __ `Python home page`_ > > > Actually, while spelling out the specifications I developed a preference for > b) because I think it is the more clear concept. So what is your preferred syntax now? -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-14 23:19:09
|
On 2013-02-14, Dmitry Shachnev wrote: > I've tried to look at parsers/rst/states.py on weekend, and found out > that there is no function to get the reference target *while parsing*, > so looks like the change needs to be implemented in (all) the writers. > Right? (My only prior experience with docutils code was the > config/test part, so maybe I don't know well how it works). > I'll be able to take a deeper look this weekend, in the meanwhile I > would appreciate any advice on how this should be implemented. Have a look at the transforms, especially docutils/docutils/transforms/references.py The concept of transforms is explained in the developer docs. Günter |
From: Guenter M. <mi...@us...> - 2013-02-15 13:07:16
|
On 2013-02-15, David Goodger wrote: > On Thu, Feb 14, 2013 at 6:22 AM, Guenter Milde <mi...@us...> wrote: > So what is your preferred syntax now? Embedded URIs and alias references Günter -A hyperlink reference may directly embed a target URI inline, within -angle brackets ("<...>") Exec: svn 'diff' 'restructuredtext.txt' 2>&1 Dir: /home/milde/Code/Python/docutils-svn/docutils/docs/ref/rst/ Index: restructuredtext.txt =================================================================== --- restructuredtext.txt (Revision 7602) +++ restructuredtext.txt (Arbeitskopie) @@ -1862,7 +1862,8 @@ .. _link: underscore\_ It is possible (although not generally recommended) to include URIs - directly within hyperlink references. See `Embedded URIs`_ below. + directly within hyperlink references. See `Embedded URIs and alias + references`_ below. 3. _`Indirect hyperlink targets` have a hyperlink reference in their link blocks. In the following example, target "one" indirectly @@ -1891,6 +1892,9 @@ .. _split: `A Hyperlink`_ + It is possible to include an alias directly within hyperlink + references. See `Embedded URIs and alias references`_ below. + If the reference name contains any colons, either: - the phrase must be enclosed in backquotes:: @@ -2649,24 +2653,30 @@ hyperlinks. -Embedded URIs -````````````` +Embedded URIs and alias references +`````````````````````````````````` -A hyperlink reference may directly embed a target URI inline, within -angle brackets ("<...>") as follows:: +A hyperlink reference may directly embed a target URI or an internal +hyperlink reference within angle brackets ("<...>") as follows:: See the `Python home page <http://www.python.org>`_ for info. + This `link <Python home page_>`_ is an alias to the link above. + This is exactly equivalent to:: See the `Python home page`_ for info. + This link_ is an alias to the link above. + .. _Python home page: http://www.python.org + .. _link: `Python home page`_ The bracketed URI must be preceded by whitespace and be the last text -before the end string. With a single trailing underscore, the -reference is named and the same target URI may be referred to again. +before the end string. +With a single trailing underscore, the reference is named and the same +target URI may be referred to again. With two trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again. These are "one-off" hyperlinks. For example:: @@ -2682,7 +2692,15 @@ __ http://www.rfc-editor.org/rfc/rfc2396.txt __ http://www.rfc-editor.org/rfc/rfc2732.txt -If reference text happens to end with angle-bracketed text that is +If a target URI happens to end with an underscore, this needs to be +backslash-escaped to avoid beeing parsed as hyperlink reference. For +example :: + + Use the `source <parrots.txt\_>`__. + +creates an anonymous reference to the file ``parrots.txt_``. + +If the reference text happens to end with angle-bracketed text that is *not* a URI, the open-angle-bracket needs to be backslash-escaped. For example, here is a reference to a title describing a tag:: |
From: David G. <go...@py...> - 2013-02-16 05:31:43
|
On Fri, Feb 15, 2013 at 7:06 AM, Guenter Milde <mi...@us...> wrote: > On 2013-02-15, David Goodger wrote: >> So what is your preferred syntax now? > > Embedded URIs and alias references OK, but until it's implemented we should still be open to ideas for better syntax. Regarding the patch below, some issues noted. Or I can do the edits once it's in the repo. I'll be doing some editing anyhow, because I think there are some other areas that could also use updating for this feature. > -A hyperlink reference may directly embed a target URI inline, within > -angle brackets ("<...>") > Exec: svn 'diff' 'restructuredtext.txt' 2>&1 > Dir: /home/milde/Code/Python/docutils-svn/docutils/docs/ref/rst/ > > Index: restructuredtext.txt > =================================================================== > --- restructuredtext.txt (Revision 7602) > +++ restructuredtext.txt (Arbeitskopie) > @@ -1862,7 +1862,8 @@ > .. _link: underscore\_ > > It is possible (although not generally recommended) to include URIs > - directly within hyperlink references. See `Embedded URIs`_ below. > + directly within hyperlink references. See `Embedded URIs and alias > + references`_ below. I'd call it "Embedded URIs and Aliases" (also, please capitalize all section titles and references to them). > 3. _`Indirect hyperlink targets` have a hyperlink reference in their > link blocks. In the following example, target "one" indirectly > @@ -1891,6 +1892,9 @@ > .. _split: `A > Hyperlink`_ > > + It is possible to include an alias directly within hyperlink > + references. See `Embedded URIs and alias references`_ below. > + > If the reference name contains any colons, either: > > - the phrase must be enclosed in backquotes:: > @@ -2649,24 +2653,30 @@ > hyperlinks. > > > -Embedded URIs > -````````````` > +Embedded URIs and alias references > +`````````````````````````````````` > > -A hyperlink reference may directly embed a target URI inline, within > -angle brackets ("<...>") as follows:: > +A hyperlink reference may directly embed a target URI or an internal > +hyperlink reference within angle brackets ("<...>") as follows:: Remove "internal" above. The reference in this case is to an external target. We only use the term "internal" for targets, not references, and there's no difference in syntax at the reference end. > See the `Python home page <http://www.python.org>`_ for info. > > + This `link <Python home page_>`_ is an alias to the link above. > + > This is exactly equivalent to:: > > See the `Python home page`_ for info. > > + This link_ is an alias to the link above. > + > .. _Python home page: http://www.python.org > + .. _link: `Python home page`_ > > The bracketed URI must be preceded by whitespace and be the last text > -before the end string. With a single trailing underscore, the > -reference is named and the same target URI may be referred to again. > +before the end string. > > +With a single trailing underscore, the reference is named and the same > +target URI may be referred to again. > With two trailing underscores, the reference and target are both > anonymous, and the target cannot be referred to again. These are > "one-off" hyperlinks. For example:: > @@ -2682,7 +2692,15 @@ > __ http://www.rfc-editor.org/rfc/rfc2396.txt > __ http://www.rfc-editor.org/rfc/rfc2732.txt > > -If reference text happens to end with angle-bracketed text that is > +If a target URI happens to end with an underscore, this needs to be > +backslash-escaped to avoid beeing parsed as hyperlink reference. For being (remove "e") > +example :: > + > + Use the `source <parrots.txt\_>`__. > + > +creates an anonymous reference to the file ``parrots.txt_``. > + > +If the reference text happens to end with angle-bracketed text that is > *not* a URI, + or a hyperlink reference > the open-angle-bracket needs to be backslash-escaped. > For example, here is a reference to a title describing a tag:: -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-16 17:31:45
|
On 2013-02-16, David Goodger wrote: > On Fri, Feb 15, 2013 at 7:06 AM, Guenter Milde <mi...@us...> wrote: >> On 2013-02-15, David Goodger wrote: >> Embedded URIs and Aliases > OK, but until it's implemented we should still be open to ideas for > better syntax. Fine. > Regarding the patch below, some issues noted. Or I can do the edits > once it's in the repo. I'll be doing some editing anyhow, because I > think there are some other areas that could also use updating for this > feature. Thanks for your corrections, I merged them into my revision. I would not like to push the changes to the repository before the implementation is at least worked on. Below is the revised patch. BTW: I would like to revise the configuration docs (config.txt) converting the "definition lists" of config settings to sub-sections. This way, we can use auto-generated hyperlink targets. However, the main advantage is the list of options appearing in the ToC. Do you agree to this change? Thanks, Günter >> -A hyperlink reference may directly embed a target URI inline, within >> -angle brackets ("<...>") >> Exec: svn 'diff' 'restructuredtext.txt' 2>&1 >> Dir: /home/milde/Code/Python/docutils-svn/docutils/docs/ref/rst/ >> Index: restructuredtext.txt >> =================================================================== >> --- restructuredtext.txt (Revision 7602) >> +++ restructuredtext.txt (Arbeitskopie) >> @@ -1862,7 +1862,8 @@ >> .. _link: underscore\_ >> It is possible (although not generally recommended) to include URIs >> - directly within hyperlink references. See `Embedded URIs`_ below. >> + directly within hyperlink references. See `Embedded URIs and alias >> + references`_ below. > I'd call it "Embedded URIs and Aliases" (also, please capitalize all > section titles and references to them). >> 3. _`Indirect hyperlink targets` have a hyperlink reference in their >> link blocks. In the following example, target "one" indirectly >> @@ -1891,6 +1892,9 @@ >> .. _split: `A >> Hyperlink`_ >> + It is possible to include an alias directly within hyperlink >> + references. See `Embedded URIs and alias references`_ below. >> + >> If the reference name contains any colons, either: >> - the phrase must be enclosed in backquotes:: >> @@ -2649,24 +2653,30 @@ >> hyperlinks. >> -Embedded URIs >> -````````````` >> +Embedded URIs and alias references >> +`````````````````````````````````` >> -A hyperlink reference may directly embed a target URI inline, within >> -angle brackets ("<...>") as follows:: >> +A hyperlink reference may directly embed a target URI or an internal >> +hyperlink reference within angle brackets ("<...>") as follows:: > Remove "internal" above. The reference in this case is to an external > target. We only use the term "internal" for targets, not references, > and there's no difference in syntax at the reference end. >> See the `Python home page <http://www.python.org>`_ for info. >> + This `link <Python home page_>`_ is an alias to the link above. >> + >> This is exactly equivalent to:: >> See the `Python home page`_ for info. >> + This link_ is an alias to the link above. >> + >> .. _Python home page: http://www.python.org >> + .. _link: `Python home page`_ >> The bracketed URI must be preceded by whitespace and be the last text >> -before the end string. With a single trailing underscore, the >> -reference is named and the same target URI may be referred to again. >> +before the end string. >> +With a single trailing underscore, the reference is named and the same >> +target URI may be referred to again. >> With two trailing underscores, the reference and target are both >> anonymous, and the target cannot be referred to again. These are >> "one-off" hyperlinks. For example:: >> @@ -2682,7 +2692,15 @@ >> __ http://www.rfc-editor.org/rfc/rfc2396.txt >> __ http://www.rfc-editor.org/rfc/rfc2732.txt >> -If reference text happens to end with angle-bracketed text that is >> +If a target URI happens to end with an underscore, this needs to be >> +backslash-escaped to avoid beeing parsed as hyperlink reference. For > being (remove "e") >> +example :: >> + >> + Use the `source <parrots.txt\_>`__. >> + >> +creates an anonymous reference to the file ``parrots.txt_``. >> + >> +If the reference text happens to end with angle-bracketed text that is >> *not* a URI, > + or a hyperlink reference >> the open-angle-bracket needs to be backslash-escaped. >> For example, here is a reference to a title describing a tag:: |
From: David G. <go...@py...> - 2013-02-16 18:07:39
|
Re: config.txt: go ahead! -- David Goodger On Feb 16, 2013 11:31 AM, "Guenter Milde" <mi...@us...> wrote: > On 2013-02-16, David Goodger wrote: > > On Fri, Feb 15, 2013 at 7:06 AM, Guenter Milde <mi...@us...> > wrote: > >> On 2013-02-15, David Goodger wrote: > > >> Embedded URIs and Aliases > > > OK, but until it's implemented we should still be open to ideas for > > better syntax. > > Fine. > > > Regarding the patch below, some issues noted. Or I can do the edits > > once it's in the repo. I'll be doing some editing anyhow, because I > > think there are some other areas that could also use updating for this > > feature. > > Thanks for your corrections, I merged them into my revision. > I would not like to push the changes to the repository before the > implementation is at least worked on. > > Below is the revised patch. > > BTW: I would like to revise the configuration docs (config.txt) converting > the "definition lists" of config settings to sub-sections. > This way, we can use auto-generated hyperlink targets. > However, the main advantage is the list of options appearing in the > ToC. > > Do you agree to this change? > > > > Thanks, > > Günter > > > >> -A hyperlink reference may directly embed a target URI inline, within > >> -angle brackets ("<...>") > >> Exec: svn 'diff' 'restructuredtext.txt' 2>&1 > >> Dir: /home/milde/Code/Python/docutils-svn/docutils/docs/ref/rst/ > > >> Index: restructuredtext.txt > >> =================================================================== > >> --- restructuredtext.txt (Revision 7602) > >> +++ restructuredtext.txt (Arbeitskopie) > >> @@ -1862,7 +1862,8 @@ > >> .. _link: underscore\_ > > >> It is possible (although not generally recommended) to include URIs > >> - directly within hyperlink references. See `Embedded URIs`_ below. > >> + directly within hyperlink references. See `Embedded URIs and alias > >> + references`_ below. > > > I'd call it "Embedded URIs and Aliases" (also, please capitalize all > > section titles and references to them). > > >> 3. _`Indirect hyperlink targets` have a hyperlink reference in their > >> link blocks. In the following example, target "one" indirectly > >> @@ -1891,6 +1892,9 @@ > >> .. _split: `A > >> Hyperlink`_ > > >> + It is possible to include an alias directly within hyperlink > >> + references. See `Embedded URIs and alias references`_ below. > >> + > >> If the reference name contains any colons, either: > > >> - the phrase must be enclosed in backquotes:: > >> @@ -2649,24 +2653,30 @@ > >> hyperlinks. > > > >> -Embedded URIs > >> -````````````` > >> +Embedded URIs and alias references > >> +`````````````````````````````````` > > >> -A hyperlink reference may directly embed a target URI inline, within > >> -angle brackets ("<...>") as follows:: > >> +A hyperlink reference may directly embed a target URI or an internal > >> +hyperlink reference within angle brackets ("<...>") as follows:: > > > Remove "internal" above. The reference in this case is to an external > > target. We only use the term "internal" for targets, not references, > > and there's no difference in syntax at the reference end. > > >> See the `Python home page <http://www.python.org>`_ for info. > > >> + This `link <Python home page_>`_ is an alias to the link above. > >> + > >> This is exactly equivalent to:: > > >> See the `Python home page`_ for info. > > >> + This link_ is an alias to the link above. > >> + > >> .. _Python home page: http://www.python.org > >> + .. _link: `Python home page`_ > > >> The bracketed URI must be preceded by whitespace and be the last text > >> -before the end string. With a single trailing underscore, the > >> -reference is named and the same target URI may be referred to again. > >> +before the end string. > > >> +With a single trailing underscore, the reference is named and the same > >> +target URI may be referred to again. > >> With two trailing underscores, the reference and target are both > >> anonymous, and the target cannot be referred to again. These are > >> "one-off" hyperlinks. For example:: > >> @@ -2682,7 +2692,15 @@ > >> __ http://www.rfc-editor.org/rfc/rfc2396.txt > >> __ http://www.rfc-editor.org/rfc/rfc2732.txt > > >> -If reference text happens to end with angle-bracketed text that is > >> +If a target URI happens to end with an underscore, this needs to be > >> +backslash-escaped to avoid beeing parsed as hyperlink reference. For > > > being (remove "e") > > >> +example :: > >> + > >> + Use the `source <parrots.txt\_>`__. > >> + > >> +creates an anonymous reference to the file ``parrots.txt_``. > >> + > >> +If the reference text happens to end with angle-bracketed text that is > >> *not* a URI, > > > + or a hyperlink reference > > >> the open-angle-bracket needs to be backslash-escaped. > >> For example, here is a reference to a title describing a tag:: > > > > > ------------------------------------------------------------------------------ > The Go Parallel Website, sponsored by Intel - in partnership with Geeknet, > is your hub for all things parallel software development, from weekly > thought > leadership blogs to news, videos, case studies, tutorials, tech docs, > whitepapers, evaluation guides, and opinion stories. Check out the most > recent posts - join the conversation now. > http://goparallel.sourceforge.net/ > _______________________________________________ > Docutils-develop mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-develop > > Please use "Reply All" to reply to the list. > |
From: Guenter M. <mi...@us...> - 2013-02-18 21:30:33
|
On 2013-02-17, Dmitry Shachnev wrote: > OK, here is a draft patch. It will increase the time as it does some > more iterations over self.document.traverse(), but I couldn't find any > better approach. Thanks, Dmitry for the patch. I took it as base for the challenge: if indirect hyperlink targets work with the current number of traversals, why not embedded aliases and after long experimentation and test came up with a solution: self.document.note_refname(reference) adds the reference to a list of "to-be-resolved" ones. I also added test cases for some common cases and this way found out that the escaping in `file with low line <foo.txt\_>`_ required a change to the regular expression. I just submitted my version to the SVN, so please test. Improvements welcome. @David: The documentation patch is now up, too. Open to your edits. Günter |
From: Dmitry S. <mi...@gm...> - 2013-02-20 05:35:15
|
Guenter Milde <milde <at> users.sf.net> writes: > > I just submitted my version to the SVN, so please test. > Improvements welcome. > > @David: The documentation patch is now up, too. Open to your edits. > > Günter So you managed to do that without touching the transforms code? Thanks a lot, looks fine to me! -- Dmitry Shachnev |