<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_1431673870335_147821" dir="ltr">Thanks, all! I just replaced that sentence in the <a id="yui_3_16_0_1_1431673870335_147622" href="https://wiki.openstack.org/wiki/Documentation/Structure#Source_file_names">https://wiki.openstack.org/wiki/Documentation/Structure#Source_file_names</a></div><div dir="ltr" id="yui_3_16_0_1_1431673870335_147823"><span id="yui_3_16_0_1_1431673870335_148005">file. And I'm going to rename the files in the ha-guide skeleton before anything gets merged.</span></div><div id="yui_3_16_0_1_1431673870335_148006" dir="ltr"><br><span id="yui_3_16_0_1_1431673870335_148005"></span></div><div dir="ltr"><span id="yui_3_16_0_1_1431673870335_148005">meg</span></div><br> <blockquote id="yui_3_16_0_1_1431673870335_147436" 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_1431673870335_147435" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 12px;"> <div id="yui_3_16_0_1_1431673870335_147434" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1431673870335_147433" dir="ltr"> <hr size="1"> <font id="yui_3_16_0_1_1431673870335_147432" 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> Meg McRoberts <dreidellhasa@yahoo.com> <br><b><span style="font-weight: bold;">Cc:</span></b> Andreas Jaeger <aj@suse.com>; "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> <br> <b><span style="font-weight: bold;">Sent:</span></b> Friday, May 15, 2015 5:44 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_1431673870335_148013" class="y_msg_container"><br><div id="yiv2959556097"><div id="yui_3_16_0_1_1431673870335_148012"><div id="yui_3_16_0_1_1431673870335_148011" dir="ltr"><br clear="none"><div id="yui_3_16_0_1_1431673870335_148010" class="yiv2959556097gmail_extra"><br clear="none"><div id="yui_3_16_0_1_1431673870335_148009" class="yiv2959556097gmail_quote">On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts <span dir="ltr"><<a rel="nofollow" shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" target="_blank" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a>></span> wrote:<br clear="none"><blockquote id="yui_3_16_0_1_1431673870335_148020" class="yiv2959556097gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div id="yui_3_16_0_1_1431673870335_148019"><div id="yui_3_16_0_1_1431673870335_148018" 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 clear="none"></div><div dir="ltr">Out of all this discussion, I would propose a single change to the following section:</div><div dir="ltr"><br clear="none"></div><h2><span>Source file names</span></h2>
<div id="yui_3_16_0_1_1431673870335_148017" 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_1431673870335_148016" style="background-color:rgb(253,239,43);"><font id="yui_3_16_0_1_1431673870335_148015">Continue to use underbar as
the space delimiter. <br clear="none"></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 id="yui_3_16_0_1_1431673870335_148022" dir="ltr"><br clear="none"></div><div dir="ltr">That solves my current issues.</div><div dir="ltr"><br clear="none"></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 clear="none"></div></div></div></blockquote><div><br clear="none"></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 clear="none"></div><div>Thanks!</div><div>Anne</div><div> </div><blockquote class="yiv2959556097gmail_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 clear="none"></div><div dir="ltr">meg<br clear="none"> </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 rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a>><br clear="none"> <b><span style="font-weight:bold;">To:</span></b> Meg McRoberts <<a rel="nofollow" shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" target="_blank" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a>>; Anne Gentle <<a rel="nofollow" shape="rect" ymailto="mailto:annegentle@justwriteclick.com" target="_blank" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>> <br clear="none"><b><span style="font-weight:bold;">Cc:</span></b> "<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>" <<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"> <b><span style="font-weight:bold;">Sent:</span></b> Thursday, May 14, 2015 11:19 PM<br clear="none"> <b><span style="font-weight:bold;">Subject:</span></b> Re: [OpenStack-docs] Anchor tag conventions<br clear="none"> </font> </div><div><div class="yiv2959556097h5"> <div><br clear="none">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 rel="nofollow" shape="rect" target="_blank" href="https://wiki.openstack.org/wiki/Documentation/Structure">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 rel="nofollow" shape="rect" ymailto="mailto:annegentle@justwriteclick.com" target="_blank" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br clear="none">> *To:* Andreas Jaeger <<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a>><br clear="none">> *Cc:* Meg McRoberts <<a rel="nofollow" shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" target="_blank" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a>>;<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" 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">> *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 rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" 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@{<a rel="nofollow" shape="rect" target="_blank" href="http://suse.com/">suse.com</a> <<a rel="nofollow" shape="rect" target="_blank" href="http://suse.com/">http://suse.com/</a>>,<a rel="nofollow" shape="rect" target="_blank" href="http://opensuse.org/">opensuse.org</a><br clear="none">> <<a rel="nofollow" shape="rect" target="_blank" href="http://opensuse.org/">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 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">> <mailto:<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">><br clear="none">><br clear="none">><br clear="none">><br clear="none">> --<br clear="none">> 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> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:annegentle@justwriteclick.com" target="_blank" href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><div class="qtdSeparateBR"><br><br></div><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd88261"><div><br clear="none"><br clear="none"></div><div><br clear="none">><br clear="none">><br clear="none"><br clear="none"><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<br clear="none"><br clear="none"></div><br clear="none"><br clear="none"></div></div><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd66784"> </div></div></div></div><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd42697"> </div></div><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd22109"> </div></blockquote><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd37270"> </div></div></div></blockquote></div><div class="yiv2959556097yqt4217515328" id="yiv2959556097yqtfd14329"><br clear="none"><br clear="all"><div><br clear="none"></div>-- <br clear="none"><div class="yiv2959556097gmail_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></div></div></div></div><br><br></div> </div> </div> </blockquote> </div></body></html>