Open Stack

On 29 July 2015 at 16:26, Andreas Jaeger <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 operationCreate 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.

Cheers,

Brian



>
>>
>> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150730/a6fa6e86/attachment-0001.html>