Open Stack

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.

On Wed, Oct 14, 2015 at 4:53 PM, Lana Brindley <openstack at lanabrindley.com>
wrote:

> -----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-----
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151014/22eebbec/attachment-0001.html>