Open Stack

On 2015-07-29 02:33, Brian Moss wrote:
> Hi all,
>
> During the RST conversions, I've come across a few different ways of
> representing procedure titles.  There is no guidance currently in the
> conventions doc.
>
> <procedure><title>To do a thing</title></procedure>

This is semantic markup

> is usually converted to either:
>
> **To do a thing**

This is visual markup.

> or
>
> To do a thing
> -------------

This is semantic markup.

We prefer semantic over visual markup in general and that's why I gave a 
-1. Also, I did not recognize directly that this is a procedure, so 
using just bold confuses.

For me, it's not clear why a procedure should be bold on it's own and 
not be a title.

Andreas

>
>
> It would be great if we could select one option and add it to the
> convention doc. I personally tend towards **Title**, as I feel the
> result is similar to the Docbook procedure title and making a procedure
> title into a header can affect a TOC in undesirable ways. Moreover, the
> limited nesting levels for headings may lead to problems.
>
> Ultimately I don't mind too much which way we go, but it would be good
> to have guidance on the matter.
>
> Cheers,
>
> Brian
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>


-- 
  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, Dilip Upmanyu, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126