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

Andreas Jaeger aj at suse.com
Sun Nov 9 20:01:51 UTC 2014


On 11/09/2014 08:57 PM, Anne Gentle wrote:
> 
> 
> On Sun, Nov 9, 2014 at 1:56 PM, Anne Gentle <anne at openstack.org
> <mailto:anne at openstack.org>> wrote:
> 
> 
> 
>     On Sun, Nov 9, 2014 at 9:16 AM, Andreas Jaeger <aj at suse.com
>     <mailto: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


Exactly - and I want to add this kind of information to our markup
conventions page, see my other email,

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



More information about the OpenStack-Infra mailing list