Open Stack

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.

Depending on what way to go, lets decide what should be included in the
Conventions:

   - List of all the possible variants, as we allow using them, with the
   note explicitly saying which markup is preferable.
   - The only possible variant for each piece of text with specific meaning.
   - Referring a user to the Sphinx documentation and let him alone
   decide...

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. *Is this much?* Especially since they are listed in the
Conventions with the explanation of their meanings and usage examples.

Thanks for your attention and thoughts on what to include in the
Contributor guide for now.

On Mon, Oct 12, 2015 at 1:19 PM, Andreas Jaeger <aj at suse.com> wrote:

> On 2015-10-12 11:50, Christian Berendt wrote:
>
>> On 10/12/2015 08:13 AM, Lana Brindley wrote:
>>
>>> 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.
>>>
>>
>> Thanks for the feedback regarding my proposed clean up patches. I have
>> not thought about the impact on the existing translations and I will
>> abandon changes which have an impact on translations and will only clean
>> up code-blocks, line numberings, and lists.
>>
>
> Thanks, Christian!
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>        HRB 21284 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
>
>
> _______________________________________________
> 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/20151014/34a693d1/attachment.html>