openstack-doc-core team mailing list archive

[David Cramer <david.cramer@xxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

So currently the output would look exactly like an orderedlist. I'm
not sure if "List of Procedures" is turned on currently, but that
could be enabled to provide a list of procedures that have titles
(like the list of tables and list of figures). At my previous job, we
made heavy use of procedures (lots of sys admin docs), so the list of
procedures came in handy. It could also facilitate automation in the
xrefs, so if you xref to a step from outside the procedure, it
includes the title of the procedure.

I guess my feeling is that if it's the same effort to add the
semantics, go ahead and add them even if you're not using them yet.
It's easier to do that than to add the semantics back in later. If
some constructs involve a lot of work and you aren't and don't foresee
using it, then skipping the richer markup is justified.

David

On 04/02/2012 02:53 PM, Lorin Hochstein wrote:
> David:
> 
> Do you have any examples of DocBook-formatted output that uses 
> <procedure> entities so I can see what it looks like?
> 
> Take care,
> 
> Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis
> Services, Inc. www.nimbisservices.com
> <https://www.nimbisservices.com/>
> 
> 
> 
> 
> On Apr 2, 2012, at 3:30 PM, David Cramer wrote:
> 
> I have to stay I'm still a fan of using <procedure> for lists of 
> steps. The semantics can come in handy and in DocBook, procedure
> isn't so constrained like it is in DITA, so you don't have to put
> on a straight jacket to use it.
> 
> I'm also a fan of titles on procedures (and generating a "List of 
> Procedures"), but I understand there are some cases where you need
> to skip the title.
> 
> David
> 
> On 04/02/2012 01:15 PM, Lorin Hochstein wrote:
>>>> I added some text in 
>>>> http://wiki.openstack.org/Documentation/Conventions 
>>>> <http://wiki.openstack.org/Documentation/Conventions#preview>
>>>> to capture the outcome ofthis email thread.
>>>> 
>>>> Take care,
>>>> 
>>>> Lorin -- Lorin Hochstein Lead Architect - Cloud Services
>>>> Nimbis Services, Inc. www.nimbisservices.com
>>>> <http://www.nimbisservices.com> 
>>>> <https://www.nimbisservices.com/>
>>>> 
>>>> 
>>>> 
>>>> On Mar 31, 2012, at 4:44 PM, Razique Mahroua wrote:
>>>> 
>>>>> Hi, in fact there are still some features nova cli doesn't
>>>>> have - for instance euca-get-console-output. I started a
>>>>> big transition euca -> nova cli few months ago, but I
>>>>> surely would have missed some. Feel free to fill a bug when
>>>>> you catch euca commands.
>>>>> 
>>>>> On Sat, 31 Mar 2012 00:25:13 +0200, Anne Gentle 
>>>>> <anne@xxxxxxxxxxxxx <mailto:anne@xxxxxxxxxxxxx> 
>>>>> <mailto:anne@xxxxxxxxxxxxx>> wrote:
>>>>> 
>>>>>> I agree with this approach - one topic on how to get 
>>>>>> credentials to work with euca2ools, and another that
>>>>>> describes the differences should suffice. It'll save us a
>>>>>> lot of maintenance in the long term. Some pain in the
>>>>>> cleanup but for good gains, I believe.
>>>>>> 
>>>>>> Thanks Lorin for bringing it up and proposing a
>>>>>> solution.
>>>>>> 
>>>>>> Anne
>>>>>> 
>>>>>> On Fri, Mar 30, 2012 at 3:27 PM, Lorin Hochstein 
>>>>>> <lorin@xxxxxxxxxxxxxxxxxx
>>>>>> <mailto:lorin@xxxxxxxxxxxxxxxxxx> 
>>>>>> <mailto:lorin@xxxxxxxxxxxxxxxxxx>> wrote:
>>>>>>> Do we still need to document euca2ools commands in the
>>>>>>> docs if there's an equivalent nova command? The admin
>>>>>>> docs look inconsistent right now, sometimes documenting
>>>>>>> the euca2ool equivalent, and sometimes not.
>>>>>>> 
>>>>>>> I'd be happier if we just removed all euca2ools
>>>>>>> equivalent commands, and only document euca2ool-related
>>>>>>> stuff like: - How do I get credentials to work with
>>>>>>> euca2ools? - What are the differences between how
>>>>>>> Amazon's EC2 endpoint behaves and how an OpenStack
>>>>>>> endpoint behaves when accessing via EC2.
>>>>>>> 
>>>>>>> 
>>>>>>> Take care,
>>>>>>> 
>>>>>>> Lorin -- Lorin Hochstein Lead Architect - Cloud
>>>>>>> Services Nimbis Services, Inc. www.nimbisservices.com 
>>>>>>> <http://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> 
>>>>>>> <mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx>
>>>>>>> Unsubscribe : https://launchpad.net/~openstack-doc-core
>>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>> 
>>>> 
>>>> 
>>>> 
> 
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJPegfnAAoJEMHeSXG7afUhHHsH/i9qam4F3fTTATatveMNhEpI
Q80P9pkIMpHuoM3JQCOzlV+Sx3CLQ4DvuEVXQ7+f2y8sa9ad8qKRPRINKK8hDH9d
l/9AQ0m+wKQGk2Gw14dr4DGRKXlQh3jv36hIRIO/vjpmfkc6ZHZZyTJCB+QyPMUL
ji3HqBl5c1IEttmGQQnI3tQlHsfPSRNc1ZrDSvuehZ9bWcY0PkNuXUbCBIrd43ib
xjy16pQZB36mVqRRSCJ1cxTv2Bq1ilvl5RxJ9tn1dJVQIHneflmRKoUer/H0sk4w
6eAoSPNH1ljGHQefXF6niNPJj5wE5jbvXNdg1W0XyCBjRlAB39SBhjy1sreA3/A=
=tc9w
-----END PGP SIGNATURE-----