[OpenStack-docs] Proposal: bold/italics in style guides

Anne Gentle anne at openstack.org
Sun Nov 9 19:57:37 UTC 2014


On Sun, Nov 9, 2014 at 1:56 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
> On Sun, Nov 9, 2014 at 9:16 AM, Andreas Jaeger <aj at suse.com> wrote:
>
>> On Friday, a few folks from infra team sat together and discussed the
>> style guide for the infra-manual (see
>> https://etherpad.openstack.org/p/kilo-infra-manual ) as a followup to
>> reviewing : https://review.openstack.org/#/c/107303/  and
>> https://review.openstack.org/#/c/107360/ . I took the action item to
>> cover the problems as an enhancement to our style guide.
>>
>> Looking up the IBM style guide, I didn't found any explicit mentioning
>> of this - so wrote up the following myself:
>>
>> ======================================================================
>> For documentation, we use semantic markup and let the toolchain format
>> the text in a consistent and appropriate way. Thus, every occurence of
>> a term, like a variable, should use the same markup.  The writing
>> should be clear and markup consistent and thus a reader should easily
>> know why a certain term is using a specific markup like boldface or
>> italics. Explicit use of bold or italics is in general wrong.
>>
>
> While it's currently considered wrong for our current toolchain, how do
> people using RST do mark up semantically?
>

Sorry, found it:
http://sphinx-doc.org/markup/inline.html#other-semantic-markup



>
>
>> ======================================================================
>>
>> Please tell me whether it's accurate and specific enough for this case,
>>
>> Andreas
>> --
>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>    GF:Jeff Hawn,Jennifer Guild,Felix Imendörffer,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
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141109/34cd52bc/attachment-0001.html>


More information about the OpenStack-docs mailing list