openstack-doc-core team mailing list archive

[David Cramer <david.cramer@xxxxxxxxxxxxx>]

Yes, DocBook is different from html in this respect. You have to have a <para> (or some other block element) inside of a <listitem> (I.e. You can't put text directly in there). Starting with 1.0.11 of the clouddocs plugin, the doc is validated against the schema before building and that would cause it to fail with a validation error. http://www.docbook.org/tdg5/en/html/listitem.html

David

From: Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx<mailto:lorin@xxxxxxxxxxxxxxxxxx>>
Date: Sun, 1 Apr 2012 15:46:04 -0400
To: Anne Gentle <anne@xxxxxxxxxxxxx<mailto:anne@xxxxxxxxxxxxx>>
Cc: <openstack-doc-core@xxxxxxxxxxxxxxxxxxx<mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx>>
Subject: Re: [Openstack-doc-core] Convention for documenting a sequence of events

Ah, I missed that in the Conventions page.

That does bring up a docbook markup question I had. Are we supposed to use <para> tags inside of <listitem> tags? I've seen others do that in the docs, but I haven't been doing it, and it seems to build fine either way.

Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com<https://www.nimbisservices.com/>





On Mar 30, 2012, at 6:32 PM, Anne Gentle wrote:

I see it as "Ordered procedure to follow" in the
http://wiki.openstack.org/Documentation/Conventions page, with:

<orderedlist>
      <listitem></listitem>
</orderedlist>

There's still cleanup to do there, too. But yes, I agree in general
with this approach, and don't see a need to use <task> markup, though
welcome input on this.

Thanks,
Anne

On Fri, Mar 30, 2012 at 2:49 PM, Lorin Hochstein
<lorin@xxxxxxxxxxxxxxxxxx<mailto:lorin@xxxxxxxxxxxxxxxxxx>> wrote:
Hi doc'ers:

Many of the documented tasks require a sequence of steps, i.e.

First, do this… Next, do that… Afterwards, do blah, etc….

Can we come up with a convention for how to document this? Personally, I
like explicitly numbering the steps rather than using "first", "second" in
prose form.

1. Do this

2. Do that

3. Do the other thing

I don't have a specific proposal about the Docbook markup tags to use. if I
was doing it in Markdown, I would do something like:

### 1. Foo

You do "foo" by typing the following command

### 2. Bar

You do "bar" by typing the following command



Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com<http://www.nimbisservices.com>






--
Mailing list: https://launchpad.net/~openstack-doc-core
Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx<mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help   : https://help.launchpad.net/ListHelp


-- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@xxxxxxxxxxxxxxxxxxx<mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx> Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp