<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 29, 2015 at 10:09 PM, Brian Moss <span dir="ltr"><<a href="mailto:kallimachos@gmail.com" target="_blank">kallimachos@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><span class="">On 29 July 2015 at 16:26, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span>On 2015-07-29 02:33, Brian Moss wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi all,<br>
<br>
During the RST conversions, I've come across a few different ways of<br>
representing procedure titles. There is no guidance currently in the<br>
conventions doc.<br>
<br>
<procedure><title>To do a thing</title></procedure><br>
</blockquote>
<br></span>
This is semantic markup<span><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
is usually converted to either:<br>
<br>
**To do a thing**<br>
</blockquote>
<br></span>
This is visual markup.<span><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
or<br>
<br>
To do a thing<br>
-------------<br>
</blockquote>
<br></span>
This is semantic markup.<br>
<br>
We prefer semantic over visual markup in general and that's why I gave a -1. Also, I did not recognize directly that this is a procedure, so using just bold confuses.<br>
<br>
For me, it's not clear why a procedure should be bold on it's own and not be a title.<br>
<br>
Andreas<br></blockquote><div><br></div></span><div>Yep, semantic is definitely better. My concern is that we use the heading syntax as a structural element, equivalent to <section><title>. I think we overload the meaning if we also use it as an equivalent to <procedure><title>. This renders the procedure as a section, which may not be the desired behaviour. For example, compare the TOC of the XML and RST versions of Chapter 3. Add the Identity service:<br><br><a href="http://docs.openstack.org/kilo/install-guide/install/apt/content/ch_keystone.html" target="_blank">http://docs.openstack.org/kilo/install-guide/install/apt/content/ch_keystone.html</a><br><a href="http://docs-draft.openstack.org/74/206274/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c85ca3//publish-docs/draft/install-guide-rst-ubuntu/keystone.html" target="_blank">http://docs-draft.openstack.org/74/206274/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c85ca3//publish-docs/draft/install-guide-rst-ubuntu/keystone.html</a><br><br></div><div>As you can see, the RST version shows two procedures in the TOC as subsections because they have been titled using header syntax.<br><br></div><div>XML<br><dl><dt><span>Verify operation</span></dt><dt><span>Create OpenStack client environment scripts</span></dt></dl><br></div><div>RST<br><br></div><div>Verify operation<br>Create OpenStack client environment scripts<br> - To create the scripts<br> - To load client environment scripts
</div><div><br></div><div>Of lesser concern, procedures titled using header syntax will be at different header levels depending on their location. While decreasing title size makes visual sense for nesting subsections, I feel that procedure titles should look consistent throughout a document.<br><br></div><div>I suppose what would make me most happy would be a heading style reserved for procedures that does not get pulled into the TOC and that renders consistently throughout a document. For the time being though, perhaps we should just pick a single way of titling procedures (heading/bold/whatever) and add it to the conventions doc.<br><br>At the moment my main concern is clearing out these conversion patches, so if I don't hear any further opinions I'll switch over to headers and we can discuss other options later.<br><br></div></div></div></div></blockquote><div><br></div><div>+1 to this approach. Thoughtful response, 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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></div><div>Cheers,<br><br></div><div>Brian<br></div><span class=""><div><br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span>
<br>
<br>
It would be great if we could select one option and add it to the<br>
convention doc. I personally tend towards **Title**, as I feel the<br>
result is similar to the Docbook procedure title and making a procedure<br>
title into a header can affect a TOC in undesirable ways. Moreover, the<br>
limited nesting levels for headings may lead to problems.<br>
<br>
Ultimately I don't mind too much which way we go, but it would be good<br>
to have guidance on the matter.<br>
<br>
Cheers,<br>
<br>
Brian<br>
<br>
<br></span>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br><span><font color="#888888">
</font></span></blockquote><span><font color="#888888">
<br>
<br>
-- <br>
Andreas Jaeger aj@{<a href="http://suse.com" rel="noreferrer" target="_blank">suse.com</a>,<a href="http://opensuse.org" rel="noreferrer" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br>
HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
</font></span></blockquote></span></div><br></div></div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>