<div dir="ltr"><div><div>Hi all,<br><br></div>Sorry for jumping in behind time, but I have some question/suggestions/thoughts.<br><br></div>I am working on the RST section of the Contributor Guide and included the semantic markups subsection as a part of it:<br><ul><li><a href="https://review.openstack.org/#/c/232966/5/doc/contributor-guide/source/rst-conv/inline-markups.rst">https://review.openstack.org/#/c/232966/5/doc/contributor-guide/source/rst-conv/inline-markups.rst</a></li></ul><p>It lists some semantic roles available in Sphinx:</p><ul><li>program (for a software application)<br></li><li>code</li><li>command</li><li>file</li><li>term</li><li>guilabel</li><li><span class=""></span><span class="">kbd (for a </span><span class=""><span class="">Keyboard</span><span class=""> key combination</span>)</span></li><li><span class=""></span><span class="">menuselection (for a menu sequence)</span></li><li><span class="">option</span></li><li><span class="">samp (for a variable part of a code fragment)</span></li></ul><p>As far as I am concerned, we cannot replace, for example, the command role with double backticks as they look differently when built: commands are displayed in bold face while the double backticks stand for a monospaced piece of text. The same applies to almost any of the roles listed above.</p><p>So, we need either to change this syntax throughout all the RST documentation and never use semantic markup at all; or configure Sphinx (if possible) to apply the same style to all of them when built, as this will definitely not add readability to our documentation if the pieces of text with the same semantic meaning are built differently on the same page.</p><p>Depending on what way to go, lets decide what should be included in the Conventions:<br></p><ul><li>List of all the possible variants, as we allow using them, with the note explicitly saying which markup is preferable.</li><li>The only possible variant for each piece of text with specific meaning.<br></li><li>Referring a user to the Sphinx documentation and let him alone decide...</li></ul><p>My point of view is that we do not deprecate semantic markup. They make our documentation more readable. There are less than a dozen of them to remember. <i>Is this much?</i> Especially since they are listed in the Conventions with the explanation of their meanings and usage examples.</p><p>Thanks for your attention and thoughts on what to include in the Contributor guide for now.<br></p></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Oct 12, 2015 at 1:19 PM, 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 class="">On 2015-10-12 11:50, Christian Berendt wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On 10/12/2015 08:13 AM, Lana Brindley wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Yeah, that's a good point. I don't think we need to retroactively go through and 'fix' all these. Just change it going forward.<br>
</blockquote>
<br>
Thanks for the feedback regarding my proposed clean up patches. I have<br>
not thought about the impact on the existing translations and I will<br>
abandon changes which have an impact on translations and will only clean<br>
up code-blocks, line numberings, and lists.<br>
</blockquote>
<br></span>
Thanks, Christian!<span class="im HOEnZb"><br>
<br>
Andreas<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, Graham Norton,<br>
HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
<br></span><div class="HOEnZb"><div class="h5">
_______________________________________________<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>
</div></div></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature"><div dir="ltr"><div><div>Best regards,<br></div>Olga<br><br></div>Technical Writer<br><div>skype: gusarenko.olga
</div><div><br></div></div></div>
</div>