Re: config.txt: go ahead!

-- David Goodger

On Feb 16, 2013 11:31 AM, "Guenter Milde" <milde@users.sf.net> wrote:
On 2013-02-16, David Goodger wrote:
> On Fri, Feb 15, 2013 at 7:06 AM, Guenter Milde <milde@users.sf.net> 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
Docutils-develop@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All" to reply to the list.