Open Stack

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.

So, change the output if needed but markup must remain.

Does that help answer your question?

Anne


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


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151014/472d740e/attachment-0001.html>