Open Stack

Thanks everyone for the discussion and help!
I have updated the Inline markup sub-section accordingly. Please review if
you are concerned:

   - https://review.openstack.org/#/c/232966/


Best,
Olga

On Thu, Oct 15, 2015 at 3:41 AM, Matt Kassawara <mkassawara at gmail.com>
wrote:

> 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
>>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Best regards,
Olga

Technical Writer
skype: gusarenko.olga
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151015/50af8348/attachment.html>