Open Stack

On Wed, Jul 29, 2015 at 10:09 PM, Brian Moss <kallimachos at gmail.com> wrote:

> 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.
>
>
+1 to this approach. Thoughtful response, thanks!
Anne


> 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
>>
>>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150729/b4239b9c/attachment.html>