Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 14/10/15 23:25, Anne Gentle wrote:
> On Wed, Oct 14, 2015 at 8:00 AM, Olga Gusarenko <ogusarenko at mirantis.com>
> wrote:
> 
>> Hi all,
>>
>> Sorry for jumping in behind time, but I have some
>> question/suggestions/thoughts.
>>
>> I am working on the RST section of the Contributor Guide and included the
>> semantic markups subsection as a part of it:
>>
>>    -
>>    https://review.openstack.org/#/c/232966/5/doc/contributor-guide/source/rst-conv/inline-markups.rst
>>
>> It lists some semantic roles available in Sphinx:
>>
>>    - program (for a software application)
>>    - code
>>    - command
>>    - file
>>    - term
>>    - guilabel
>>    - kbd (for a Keyboard key combination)
>>    - menuselection (for a menu sequence)
>>    - option
>>    - samp (for a variable part of a code fragment)
>>
>> 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.
>>
>> 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.
>>
>>
> I think that for translators, the list at
> https://wiki.openstack.org/wiki/I18nTeam/rst-markups needs to be followed
> because the translators have been using those conventions for what to
> translate and what to leave in the original language.
> 

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.

Definitely make sure we're not stepping on translators' toes, too. 

L

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJWHtzwAAoJELppzVb4+KUyBMkH/3PRoJ4v6p/yY/nACohITM0M
2d8l5OsULQfZ6oVCfmw26n5KmwmG1unmoKNnQ75JfrLAoHHNF+9MD6E7Fl8Cl1F0
GTgyFzztnu44577olDydCZ2jT1oaNy7gnZ1wPzgoWaShS9PysNLMdD6sFWtZUuZD
VGz9sARzPoYZA7XQtL1LC9I9p18LjS12p6rv05z04LN3UVRpJ9gZmQpIblqEVo2k
YeDOJmUezccYhF742vy61Y69TUBNp76phCWkKXZv21W3U3d89qzH5XKTHvP4LZci
4Y4en0QbAlcLr31Wud6q4l7OCRhG8H8GGD0GWR+x71J5brmwT7kN0aziDv/AUsg=
=RtYx
-----END PGP SIGNATURE-----