<div dir="ltr">I agree with Lana. If the semantic markup yields unique output that generic markup cannot match, then we should use it. However, when it doesn't... such as :file:`filename` which renders the same as ``filename`` in our theme... choosing minimal markup reduces bulk.</div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Oct 14, 2015 at 4:53 PM, Lana Brindley <span dir="ltr"><<a href="mailto:openstack@lanabrindley.com" target="_blank">openstack@lanabrindley.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">-----BEGIN PGP SIGNED MESSAGE-----<br>
Hash: SHA256<br>
<span class=""><br>
On 14/10/15 23:25, Anne Gentle wrote:<br>
> On Wed, Oct 14, 2015 at 8:00 AM, Olga Gusarenko <<a href="mailto:ogusarenko@mirantis.com">ogusarenko@mirantis.com</a>><br>
> wrote:<br>
><br>
>> Hi all,<br>
>><br>
>> Sorry for jumping in behind time, but I have some<br>
>> question/suggestions/thoughts.<br>
>><br>
>> I am working on the RST section of the Contributor Guide and included the<br>
>> semantic markups subsection as a part of it:<br>
>><br>
</span>>> -<br>
<span class="">>> <a href="https://review.openstack.org/#/c/232966/5/doc/contributor-guide/source/rst-conv/inline-markups.rst" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/232966/5/doc/contributor-guide/source/rst-conv/inline-markups.rst</a><br>
>><br>
>> It lists some semantic roles available in Sphinx:<br>
>><br>
</span>>> - program (for a software application)<br>
>> - code<br>
>> - command<br>
>> - file<br>
>> - term<br>
>> - guilabel<br>
>> - kbd (for a Keyboard key combination)<br>
>> - menuselection (for a menu sequence)<br>
>> - option<br>
>> - samp (for a variable part of a code fragment)<br>
<span class="">>><br>
>> As far as I am concerned, we cannot replace, for example, the command role<br>
>> with double backticks as they look differently when built: commands are<br>
>> displayed in bold face while the double backticks stand for a monospaced<br>
>> piece of text. The same applies to almost any of the roles listed above.<br>
>><br>
>> So, we need either to change this syntax throughout all the RST<br>
>> documentation and never use semantic markup at all; or configure Sphinx (if<br>
>> possible) to apply the same style to all of them when built, as this will<br>
>> definitely not add readability to our documentation if the pieces of text<br>
>> with the same semantic meaning are built differently on the same page.<br>
>><br>
>><br>
> I think that for translators, the list at<br>
> <a href="https://wiki.openstack.org/wiki/I18nTeam/rst-markups" rel="noreferrer" target="_blank">https://wiki.openstack.org/wiki/I18nTeam/rst-markups</a> needs to be followed<br>
> because the translators have been using those conventions for what to<br>
> translate and what to leave in the original language.<br>
><br>
<br>
</span>Only remove semantic markup where the output doesn't need to be something different. So, for monospaced font, you'll still need the semantic markup. Also, if I recall, we're not going to retroactively remove (or decline patches over) semantic markup. It's there to use if people choose to.<br>
<br>
Definitely make sure we're not stepping on translators' toes, too.<br>
<span class=""><br>
L<br>
<br>
- --<br>
Lana Brindley<br>
Technical Writer<br>
Rackspace Cloud Builders Australia<br>
<a href="http://lanabrindley.com" rel="noreferrer" target="_blank">http://lanabrindley.com</a><br>
-----BEGIN PGP SIGNATURE-----<br>
Version: GnuPG v2<br>
Comment: Using GnuPG with Thunderbird - <a href="http://www.enigmail.net/" rel="noreferrer" target="_blank">http://www.enigmail.net/</a><br>
<br>
</span>iQEcBAEBCAAGBQJWHtzwAAoJELppzVb4+KUyBMkH/3PRoJ4v6p/yY/nACohITM0M<br>
2d8l5OsULQfZ6oVCfmw26n5KmwmG1unmoKNnQ75JfrLAoHHNF+9MD6E7Fl8Cl1F0<br>
GTgyFzztnu44577olDydCZ2jT1oaNy7gnZ1wPzgoWaShS9PysNLMdD6sFWtZUuZD<br>
VGz9sARzPoYZA7XQtL1LC9I9p18LjS12p6rv05z04LN3UVRpJ9gZmQpIblqEVo2k<br>
YeDOJmUezccYhF742vy61Y69TUBNp76phCWkKXZv21W3U3d89qzH5XKTHvP4LZci<br>
4Y4en0QbAlcLr31Wud6q4l7OCRhG8H8GGD0GWR+x71J5brmwT7kN0aziDv/AUsg=<br>
=RtYx<br>
-----END PGP SIGNATURE-----<br>
<div class="HOEnZb"><div class="h5"><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>
</div></div></blockquote></div><br></div>