<html><head><meta http-equiv="Content-Type" content="text/html charset=iso-8859-1"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">Sorry for coming late to this conversation, I agree with Anne here.<div><br></div><div>L</div><div><br></div><div><br><div><div>On 15 May 2015, at 5:44 am, Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div dir="ltr" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><div class="gmail_extra"><br class="Apple-interchange-newline"><br><div class="gmail_quote">On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts<span class="Apple-converted-space"> </span><span dir="ltr"><<a href="mailto:dreidellhasa@yahoo.com" target="_blank">dreidellhasa@yahoo.com</a>></span><span class="Apple-converted-space"> </span>wrote:<br><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-color: rgb(204, 204, 204); border-left-style: solid; padding-left: 1ex;"><div style="background-color: rgb(255, 255, 255); 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 class="Apple-converted-space"> </span><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></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: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-color: rgb(204, 204, 204); border-left-style: solid; padding-left: 1ex;"><div style="background-color: rgb(255, 255, 255); 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-width: 2px; border-left-style: solid; border-left-color: 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><span class="Apple-converted-space"> </span>Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>><br><b><span style="font-weight: bold;">To:</span></b><span class="Apple-converted-space"> </span>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>><span class="Apple-converted-space"> </span><br><b><span style="font-weight: bold;">Cc:</span></b><span class="Apple-converted-space"> </span>"<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>><span class="Apple-converted-space"> </span><br><b><span style="font-weight: bold;">Sent:</span></b><span class="Apple-converted-space"> </span>Thursday, May 14, 2015 11:19 PM<br><b><span style="font-weight: bold;">Subject:</span></b><span class="Apple-converted-space"> </span>Re: [OpenStack-docs] Anchor tag conventions<br></font></div><div><div class="h5"><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">><span class="Apple-converted-space"> </span><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,<span class="Apple-converted-space"> </span><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<span class="Apple-converted-space"> </span><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<span class="Apple-converted-space"> </span><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">> <span class="Apple-converted-space"> </span><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">> <span class="Apple-converted-space"> </span><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">> <span class="Apple-converted-space"> </span><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">--<span class="Apple-converted-space"> </span><br clear="none"> <span class="Apple-converted-space"> </span>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"> <span class="Apple-converted-space"> </span>SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br clear="none"> <span class="Apple-converted-space"> </span>GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br clear="none"> <span class="Apple-converted-space"> </span>HRB 21284 (AG Nürnberg)<br clear="none"> <span class="Apple-converted-space"> </span>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></blockquote></div></blockquote></div><br><br clear="all"><div><br></div>--<span class="Apple-converted-space"> </span><br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div></div></div><span style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">_______________________________________________</span><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">OpenStack-docs mailing list</span><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><a href="mailto:OpenStack-docs@lists.openstack.org" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;">OpenStack-docs@lists.openstack.org</a><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></blockquote></div><br><div>
<div>Lana Brindley<div>Technical Writer</div><div>Rackspace Cloud Builders Australia</div></div><div><br></div><br class="Apple-interchange-newline">
</div>
<br></div></body></html>