Open Stack

On Thu, May 14, 2015 at 12:30 AM, Andreas Jaeger <aj at suse.com> wrote:

> On 05/13/2015 11:50 PM, Meg McRoberts wrote:
>
>> Hi all,
>> I am creating files for the ha-guide content and have a question about
>> what the OpenStack docs call
>> "embedded anchor pointers" and the Sphinx docs call labels.  Basically,
>> this is the string that you use
>> in a :ref: construct to link to a section.  It is coded just above the
>> section title.  For example:
>>
>> .. _anchor-for-ha-intro:
>>
>> ============================================
>> Introduction to Highly Available OpenStack environments
>> ============================================
>>
>> It makes sense to use the file name (minus the .rst extension) for the
>> labels, except that the Structure
>> standard specifies using underbar as the space delimiter, and underbars
>> in these labels can confuse
>> Sphinx.
>>
>> I would suggest one of the following:
>>
>> - Use hyphen rather than underscore for RST source file names, then use
>> that name as the top-level label
>>    for that section, so the filename would be intro-ha.rst rather than
>> intro_ha.rst  (preferred)
>> - Replace the underbars in file names with hyphens for labels.
>>
>> What does everyone else think?
>>
>
For file names, yes hyphens.

Unless you are linking to a heading lower down in the file, I don't believe
the label is required. I wonder why those are being added?


>
> You can reference files by name, can't you?
>
>
The anchor convention is for linking within a longer file. But maybe the
labels offer something? I'd rather always reference whole files by name.


> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
>        HRB 21284 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150514/e74fc1ae/attachment.html>