<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, May 14, 2015 at 12:30 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 05/13/2015 11:50 PM, Meg McRoberts wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi all,<br>
I am creating files for the ha-guide content and have a question about<br>
what the OpenStack docs call<br>
"embedded anchor pointers" and the Sphinx docs call labels.  Basically,<br>
this is the string that you use<br>
in a :ref: construct to link to a section.  It is coded just above the<br>
section title.  For example:<br>
<br>
.. _anchor-for-ha-intro:<br>
<br>
============================================<br>
Introduction to Highly Available OpenStack environments<br>
============================================<br>
<br>
It makes sense to use the file name (minus the .rst extension) for the<br>
labels, except that the Structure<br>
standard specifies using underbar as the space delimiter, and underbars<br>
in these labels can confuse<br>
Sphinx.<br>
<br>
I would suggest one of the following:<br>
<br>
- Use hyphen rather than underscore for RST source file names, then use<br>
that name as the top-level label<br>
   for that section, so the filename would be intro-ha.rst rather than<br>
intro_ha.rst  (preferred)<br>
- Replace the underbars in file names with hyphens for labels.<br>
<br>
What does everyone else think?<br></blockquote></blockquote><div><br></div><div>For file names, yes hyphens.</div><div><br></div><div>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?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
</blockquote>
<br>
You can reference files by name, can't you?<span class="HOEnZb"><font color="#888888"><br>
<br></font></span></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="HOEnZb"><font color="#888888">
Andreas<br>
-- <br>
 Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
   GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br>
       HRB 21284 (AG Nürnberg)<br>
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126<br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>