<html><body><div style="color:#000; background-color:#fff; font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:12px"><div id="yui_3_16_0_1_1431644039688_3391" dir="ltr">So it's okay to use hyphens rather than underscores in file names? The last line of "Source File Names" in</div><div id="yui_3_16_0_1_1431644039688_3389" dir="ltr"><a id="yui_3_16_0_1_1431644039688_3388" href="https://wiki.openstack.org/wiki/Documentation/Structure">https://wiki.openstack.org/wiki/Documentation/Structure</a><br> says "Continue to use underbar as the space delimiter." May I modify the spec? And then I will rename the</div><div dir="ltr">ha-guide files before they get merged. <br></div><div id="yui_3_16_0_1_1431644039688_3545" dir="ltr"><br></div><div id="yui_3_16_0_1_1431644039688_3544" dir="ltr">I guess it is just me who thought that each file should have a label/anchor for the top-level heading. Andreas said that</div><div id="yui_3_16_0_1_1431644039688_3691" dir="ltr">we can use "doc" to reference these docs instead. My problem is that I have never been able to figure out what</div><div id="yui_3_16_0_1_1431644039688_3695" dir="ltr">to use as the file name for :doc: -- the Sphinx documentation doesn't make sense to me.</div><div id="yui_3_16_0_1_1431644039688_3800" dir="ltr"><br></div><div id="yui_3_16_0_1_1431644039688_3871" dir="ltr">Is there a reason we are using the term "anchor" instead of the term "label" that the Sphinx/RST docs use? <br></div><div dir="ltr"><br></div><div dir="ltr">And do we need conventions for the content of labels/anchors? The ha-guide is in its own repo so I don't anticipate</div><div dir="ltr">any problems but it might be good to have some sort of convention since a label/anchor must be unique for the entire</div><div dir="ltr">set -- I can see the potential for conflicts on terms like install, troubleshoot, et cetera...</div><div dir="ltr"><br></div><div dir="ltr">meg<br></div><div id="yui_3_16_0_1_1431644039688_3285"><span></span></div><br> <blockquote id="yui_3_16_0_1_1431644039688_3452" style="border-left: 2px solid rgb(16, 16, 255); margin-left: 5px; margin-top: 5px; padding-left: 5px;"> <div id="yui_3_16_0_1_1431644039688_3451" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 12px;"> <div id="yui_3_16_0_1_1431644039688_3450" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1431644039688_3449" dir="ltr"> <hr size="1"> <font id="yui_3_16_0_1_1431644039688_3483" face="Arial" size="2"> <b><span style="font-weight:bold;">From:</span></b> Anne Gentle <annegentle@justwriteclick.com><br> <b><span style="font-weight: bold;">To:</span></b> Andreas Jaeger <aj@suse.com> <br><b><span style="font-weight: bold;">Cc:</span></b> Meg McRoberts <dreidellhasa@yahoo.com>; "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> <br> <b><span style="font-weight: bold;">Sent:</span></b> Thursday, May 14, 2015 5:58 AM<br> <b><span style="font-weight: bold;">Subject:</span></b> Re: [OpenStack-docs] Anchor tag conventions<br> </font> </div> <div id="yui_3_16_0_1_1431644039688_3763" class="y_msg_container"><br><div id="yiv3453782665"><div id="yui_3_16_0_1_1431644039688_3762"><div id="yui_3_16_0_1_1431644039688_3761" dir="ltr"><br clear="none"><div id="yui_3_16_0_1_1431644039688_3760" class="yiv3453782665gmail_extra"><br clear="none"><div id="yui_3_16_0_1_1431644039688_3759" class="yiv3453782665gmail_quote">On Thu, May 14, 2015 at 12:30 AM, Andreas Jaeger <span dir="ltr"><<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a>></span> wrote:<br clear="none"><blockquote id="yui_3_16_0_1_1431644039688_3766" class="yiv3453782665gmail_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 clear="none">
<blockquote id="yui_3_16_0_1_1431644039688_3765" class="yiv3453782665gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
Hi all,<br clear="none">
I am creating files for the ha-guide content and have a question about<br clear="none">
what the OpenStack docs call<br clear="none">
"embedded anchor pointers" and the Sphinx docs call labels. Basically,<br clear="none">
this is the string that you use<br clear="none">
in a :ref: construct to link to a section. It is coded just above the<br clear="none">
section title. For example:<br clear="none">
<br clear="none">
.. _anchor-for-ha-intro:<br clear="none">
<br clear="none">
============================================<br clear="none">
Introduction to Highly Available OpenStack environments<br clear="none">
============================================<br clear="none">
<br clear="none">
It makes sense to use the file name (minus the .rst extension) for the<br clear="none">
labels, except that the Structure<br clear="none">
standard specifies using underbar as the space delimiter, and underbars<br clear="none">
in these labels can confuse<br clear="none">
Sphinx.<br clear="none">
<br clear="none">
I would suggest one of the following:<br clear="none">
<br clear="none">
- Use hyphen rather than underscore for RST source file names, then use<br clear="none">
that name as the top-level label<br clear="none">
for that section, so the filename would be intro-ha.rst rather than<br clear="none">
intro_ha.rst (preferred)<br clear="none">
- Replace the underbars in file names with hyphens for labels.<br clear="none">
<br clear="none">
What does everyone else think?<br clear="none"></blockquote></blockquote><div><br clear="none"></div><div>For file names, yes hyphens.</div><div><br clear="none"></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 id="yui_3_16_0_1_1431644039688_3768"> </div><blockquote id="yui_3_16_0_1_1431644039688_3767" class="yiv3453782665gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><blockquote class="yiv3453782665gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
</blockquote>
<br clear="none">
You can reference files by name, can't you?<span class="yiv3453782665HOEnZb"><font color="#888888"><br clear="none">
<br clear="none"></font></span></blockquote><div><br clear="none"></div><div id="yui_3_16_0_1_1431644039688_3764">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 class="qtdSeparateBR"><br><br></div><div class="yiv3453782665yqt4651990338" id="yiv3453782665yqtfd26875"><div> </div></div><blockquote id="yui_3_16_0_1_1431644039688_3758" class="yiv3453782665gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><span id="yui_3_16_0_1_1431644039688_3757" class="yiv3453782665HOEnZb"><font id="yui_3_16_0_1_1431644039688_3756" color="#888888"><div class="yiv3453782665yqt4651990338" id="yiv3453782665yqtfd83681">
Andreas<br clear="none">
-- <br clear="none">
Andreas Jaeger aj@{<a rel="nofollow" shape="rect" target="_blank" href="http://suse.com/">suse.com</a>,<a rel="nofollow" shape="rect" target="_blank" href="http://opensuse.org/">opensuse.org</a>} Twitter/Identica: jaegerandi<br clear="none">
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br clear="none">
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br clear="none">
HRB 21284 (AG Nürnberg)<br clear="none">
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126</div><br clear="none">
<br clear="none">
<br clear="none">
_______________________________________________<br clear="none">
OpenStack-docs mailing list<br clear="none">
<a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">
<a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">
</font></span></blockquote></div><br clear="none"><br clear="all"><div><br clear="none"></div>-- <br clear="none"><div class="yiv3453782665gmail_signature">Anne Gentle<br clear="none"><a rel="nofollow" shape="rect" ymailto="mailto:annegentle@justwriteclick.com" target="_blank" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a></div><div class="yiv3453782665yqt4651990338" id="yiv3453782665yqtfd82513">
</div></div></div></div></div><br><br></div> </div> </div> </blockquote> </div></body></html>