<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts <span dir="ltr"><<a href="mailto:dreidellhasa@yahoo.com" target="_blank">dreidellhasa@yahoo.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div style="color:#000;background-color:#fff;font-family:HelveticaNeue,Helvetica Neue,Helvetica,Arial,Lucida Grande,sans-serif;font-size:12px"><div>I'm quite comfortable going forward with no standards for labels at this point. At some time in the future,</div><div 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 dir="ltr">rules.</div><div dir="ltr"><br></div><div dir="ltr">Out of all this discussion, I would propose a single change to the following section:</div><div dir="ltr"><br></div><h2><span>Source file names</span></h2>
<div 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 style="background-color:rgb(253,239,43)"><font>Continue to use underbar as
the space delimiter. <br></font></span></div><div><span style="background-color:rgb(253,239,43)"></span></div><div 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 dir="ltr"><br></div><div dir="ltr">That solves my current issues.</div><div dir="ltr"><br></div><div 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 dir="ltr">I can work on some of that if you think it is useful.<br></div></div></div></blockquote><div><br></div><div>I'm a fan of both standards and hyphen, though it's totally possible I wrote the "underbar continuation rule" due to xml:id consistency. However, now that we see how the redirects are working, and that the xml:id isn't crucial, let's go with hyphen as a standard. </div><div><br></div><div>Thanks!</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div style="color:#000;background-color:#fff;font-family:HelveticaNeue,Helvetica Neue,Helvetica,Arial,Lucida Grande,sans-serif;font-size:12px"><div dir="ltr"></div><div dir="ltr"><br></div><div dir="ltr">meg<br> </div><blockquote style="border-left:2px solid rgb(16,16,255);margin-left:5px;margin-top:5px;padding-left:5px"> <div style="font-family:HelveticaNeue,Helvetica Neue,Helvetica,Arial,Lucida Grande,sans-serif;font-size:12px"> <div style="font-family:HelveticaNeue,Helvetica Neue,Helvetica,Arial,Lucida Grande,sans-serif;font-size:16px"> <div dir="ltr"> <hr size="1"> <font face="Arial" size="2"> <b><span style="font-weight:bold">From:</span></b> Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>><br> <b><span style="font-weight:bold">To:</span></b> Meg McRoberts <<a href="mailto:dreidellhasa@yahoo.com" target="_blank">dreidellhasa@yahoo.com</a>>; Anne Gentle <<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>> <br><b><span style="font-weight:bold">Cc:</span></b> "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>> <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><div class="h5"> <div><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 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" href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><br clear="none">> *To:* Andreas Jaeger <<a shape="rect" href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>><br clear="none">> *Cc:* Meg McRoberts <<a shape="rect" href="mailto:dreidellhasa@yahoo.com" target="_blank">dreidellhasa@yahoo.com</a>>;<br clear="none">> "<a shape="rect" href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>"<br clear="none">> <<a shape="rect" href="mailto:openstack-docs@lists.openstack.org" target="_blank">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" href="mailto:aj@suse.com" target="_blank">aj@suse.com</a><br clear="none">> <mailto:<a shape="rect" href="mailto:aj@suse.com" target="_blank">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@{<a href="http://suse.com" target="_blank">suse.com</a> <<a shape="rect" href="http://suse.com/" target="_blank">http://suse.com/</a>>,<a href="http://opensuse.org" target="_blank">opensuse.org</a><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" href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a shape="rect" href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">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" href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a> <mailto:<a shape="rect" href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><div><br><br></div><div><br clear="none">><br clear="none">><br clear="none"><br clear="none"><br clear="none">-- <br clear="none"> 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 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></div> </div> </blockquote> </div></div></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>