<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_1431646131562_71273">I'm quite comfortable going forward with no standards for labels at this point. At some time in the future,</div><div id="yui_3_16_0_1_1431646131562_73157" dir="ltr">we may need standards but we can figure it out then. I just wanted to be sure I wasn't violating any established</div><div id="yui_3_16_0_1_1431646131562_71454" dir="ltr">rules.</div><div id="yui_3_16_0_1_1431646131562_71271" dir="ltr"><br></div><div id="yui_3_16_0_1_1431646131562_71272" dir="ltr">Out of all this discussion, I would propose a single change to the following section:</div><div id="yui_3_16_0_1_1431646131562_71788" dir="ltr"><br></div><h2 id="yui_3_16_0_1_1431646131562_71789" style="" class=""><span style="" class="" id="Source_file_names">Source file names</span></h2>
<div id="yui_3_16_0_1_1431646131562_71790" style="" class="" dir="ltr">For XML file names, we have used prefixes like bk_, ch_, section_,
and app_ at the beginning of the file name to indicate the type of file
it is in the hierarchy of the build. However, in migrating to RST/Sphinx
we are using the xml:id for the file name and moving towards a
page-based, topical approach to file naming. <span id="yui_3_16_0_1_1431646131562_72500" style="background-color: rgb(253, 239, 43);"><font id="yui_3_16_0_1_1431646131562_71920">Continue to use underbar as
the space delimiter. <br></font></span></div><div id="yui_3_16_0_1_1431646131562_71270"><span id="yui_3_16_0_1_1431646131562_72502" style="background-color: rgb(253, 239, 43);"></span></div><div id="yui_3_16_0_1_1431646131562_72503" dir="ltr">I would like to replace the highlighted sentence with "RST files should use a hyphen as the space delimiter and have the .rst extension."</div><div id="yui_3_16_0_1_1431646131562_77041" dir="ltr"><br></div><div id="yui_3_16_0_1_1431646131562_77214" dir="ltr">That solves my current issues.</div><div id="yui_3_16_0_1_1431646131562_77215" dir="ltr"><br></div><div id="yui_3_16_0_1_1431646131562_77216" dir="ltr">It might be nice to expand this section, however, to explain things like the source subdirectory, the index.rst file, the toctree: stuff within the source files, and so forth.''</div><div id="yui_3_16_0_1_1431646131562_77384" dir="ltr">I can work on some of that if you think it is useful.<br></div><div id="yui_3_16_0_1_1431646131562_77381" dir="ltr"><br></div><div id="yui_3_16_0_1_1431646131562_77382" dir="ltr">meg<br> </div><blockquote id="yui_3_16_0_1_1431646131562_70940" 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_1431646131562_70939" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 12px;"> <div id="yui_3_16_0_1_1431646131562_70938" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1431646131562_70937" dir="ltr"> <hr id="yui_3_16_0_1_1431646131562_71918" size="1"> <font id="yui_3_16_0_1_1431646131562_71791" face="Arial" size="2"> <b><span style="font-weight:bold;">From:</span></b> Andreas Jaeger <aj@suse.com><br> <b><span style="font-weight: bold;">To:</span></b> Meg McRoberts <dreidellhasa@yahoo.com>; Anne Gentle <annegentle@justwriteclick.com> <br><b id="yui_3_16_0_1_1431646131562_72303"><span id="yui_3_16_0_1_1431646131562_72302" style="font-weight: bold;">Cc:</span></b> "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> <br> <b><span style="font-weight: bold;">Sent:</span></b> Thursday, May 14, 2015 11:19 PM<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_1431646131562_71792" class="y_msg_container"><br>On 05/15/2015 01:05 AM, Meg McRoberts wrote:<br clear="none">> So it's okay to use hyphens rather than underscores in file names? The<br clear="none">> last line of "Source File Names" in<br clear="none">> <a id="yui_3_16_0_1_1431646131562_71916" shape="rect" href="https://wiki.openstack.org/wiki/Documentation/Structure" target="_blank">https://wiki.openstack.org/wiki/Documentation/Structure</a><br clear="none">> says "Continue to use underbar as the space delimiter." May I modify<br clear="none">> the spec? And then I will rename the<br clear="none">> ha-guide files before they get merged.<br clear="none"><br clear="none">Please write down again what you propose and then let's change the file...<br clear="none"><br clear="none">><br clear="none">> I guess it is just me who thought that each file should have a<br clear="none">> label/anchor for the top-level heading. Andreas said that<br clear="none">> we can use "doc" to reference these docs instead. My problem is that I<br clear="none">> have never been able to figure out what<br clear="none">> to use as the file name for :doc: -- the Sphinx documentation doesn't<br clear="none">> make sense to me.<br clear="none"><br clear="none">The openstack-manuals RST files like the user-guide use :doc: already, <br clear="none">have a look a the repo.<br clear="none"><br clear="none">> Is there a reason we are using the term "anchor" instead of the term<br clear="none">> "label" that the Sphinx/RST docs use?<br clear="none">><br clear="none">> And do we need conventions for the content of labels/anchors? The<br clear="none">> ha-guide is in its own repo so I don't anticipate<br clear="none">> any problems but it might be good to have some sort of convention since<br clear="none">> a label/anchor must be unique for the entire<br clear="none">> set -- I can see the potential for conflicts on terms like install,<br clear="none">> troubleshoot, et cetera...<br clear="none"><br clear="none">Our conventions apply to all repos to make reviewing and appearance <br clear="none">consistent.<br clear="none"><br clear="none">Labels are unique within a single manual, so that should be fine in general.<br clear="none"><br clear="none">I don't know whether we need a convention on format of it. Feel free to <br clear="none">propose something,<br clear="none"><br clear="none">Andreas<br clear="none"><br clear="none">><br clear="none">> meg<br clear="none">><br clear="none">> ------------------------------------------------------------------------<br clear="none">> *From:* Anne Gentle <<a shape="rect" ymailto="mailto:annegentle@justwriteclick.com" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br clear="none">> *To:* Andreas Jaeger <<a shape="rect" ymailto="mailto:aj@suse.com" href="mailto:aj@suse.com">aj@suse.com</a>><br clear="none">> *Cc:* Meg McRoberts <<a shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a>>;<br clear="none">> "<a shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>"<br clear="none">> <<a shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br clear="none">> *Sent:* Thursday, May 14, 2015 5:58 AM<br clear="none">> *Subject:* Re: [OpenStack-docs] Anchor tag conventions<br clear="none">><br clear="none">><br clear="none">><br clear="none">> On Thu, May 14, 2015 at 12:30 AM, Andreas Jaeger <<a shape="rect" ymailto="mailto:aj@suse.com" href="mailto:aj@suse.com">aj@suse.com</a><br clear="none">> <mailto:<a shape="rect" ymailto="mailto:aj@suse.com" href="mailto:aj@suse.com">aj@suse.com</a>>> wrote:<br clear="none">><br clear="none">> On 05/13/2015 11:50 PM, Meg McRoberts wrote:<br clear="none">><br clear="none">> Hi all,<br clear="none">> I am creating files for the ha-guide content and have a<br clear="none">> question about<br clear="none">> what the OpenStack docs call<br clear="none">> "embedded anchor pointers" and the Sphinx docs call labels.<br clear="none">> 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<br clear="none">> 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<br clear="none">> extension) for the<br clear="none">> labels, except that the Structure<br clear="none">> standard specifies using underbar as the space delimiter,<br clear="none">> 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<br clear="none">> 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<br clear="none">> 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">><br clear="none">><br clear="none">> For file names, yes hyphens.<br clear="none">><br clear="none">> Unless you are linking to a heading lower down in the file, I don't<br clear="none">> believe the label is required. I wonder why those are being added?<br clear="none">><br clear="none">><br clear="none">> You can reference files by name, can't you?<br clear="none">><br clear="none">><br clear="none">> The anchor convention is for linking within a longer file. But maybe<br clear="none">> the labels offer something? I'd rather always reference whole files<br clear="none">> by name.<br clear="none">><br clear="none">><br clear="none">> Andreas<br clear="none">> --<br clear="none">> Andreas Jaeger aj@{suse.com <<a shape="rect" href="http://suse.com/" target="_blank">http://suse.com/</a>>,opensuse.org<br clear="none">> <<a shape="rect" href="http://opensuse.org/" target="_blank">http://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<br clear="none">> Norton,<br clear="none">> HRB 21284 (AG Nürnberg)<br clear="none">> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C<br clear="none">> C272 A126<br clear="none">><br clear="none">><br clear="none">><br clear="none">> _______________________________________________<br clear="none">> OpenStack-docs mailing list<br clear="none">> <a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a>><br clear="none">> <a shape="rect" 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 clear="none">><br clear="none">><br clear="none">><br clear="none">><br clear="none">> --<br clear="none">> Anne Gentle<br clear="none">> <a shape="rect" ymailto="mailto:annegentle@justwriteclick.com" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a> <mailto:<a shape="rect" ymailto="mailto:annegentle@justwriteclick.com" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><div class="qtdSeparateBR"><br><br></div><div class="yqt4553058842" id="yqtfd79055"><br clear="none">><br clear="none">><br clear="none"><br clear="none"><br clear="none">-- <br clear="none"> Andreas Jaeger aj@{suse.com,opensuse.org} 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<br clear="none"><br clear="none"></div><br><br></div> </div> </div> </blockquote> </div></body></html>