Open Stack

On 2015-07-30 05:09, Brian Moss wrote:
> On 29 July 2015 at 16:26, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
>
>     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
>
>
> Yep, semantic is definitely better.  My concern is that we use the
> heading syntax as a structural element, equivalent to <section><title>.
> I think we overload the meaning if we also use it as an equivalent to
> <procedure><title>.  This renders the procedure as a section, which may
> not be the desired behaviour.  For example, compare the TOC of the XML
> and RST versions of Chapter 3. Add the Identity service:
>
> http://docs.openstack.org/kilo/install-guide/install/apt/content/ch_keystone.html
> http://docs-draft.openstack.org/74/206274/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c85ca3//publish-docs/draft/install-guide-rst-ubuntu/keystone.html
>
> As you can see, the RST version shows two procedures in the TOC as
> subsections because they have been titled using header syntax.
>
> XML
>
> Verify operation
> Create OpenStack client environment scripts
>
>
> RST
>
> Verify operation
> Create OpenStack client environment scripts
>   -  To create the scripts
>   -  To load client environment scripts
>
> Of lesser concern, procedures titled using header syntax will be at
> different header levels depending on their location. While decreasing
> title size makes visual sense for nesting subsections, I feel that
> procedure titles should look consistent throughout a document.
>
> I suppose what would make me most happy would be a heading style
> reserved for procedures that does not get pulled into the TOC and that
> renders consistently throughout a document.  For the time being though,
> perhaps we should just pick a single way of titling procedures
> (heading/bold/whatever) and add it to the conventions doc.
>
> At the moment my main concern is clearing out these conversion patches,
> so if I don't hear any further opinions I'll switch over to headers and
> we can discuss other options later.

I'll remove my -1 and let you figure out the best way, you're right we 
can fix this later as well,

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