Open Stack

+1. I'll update the conventions page.  

Sent from my iPhone

> On Sep 29, 2013, at 12:46 PM, "Nicholas Chase" <nchase at mirantis.com> wrote:
> 
> +1 from me on all of this.
> 
> ----  Nick
> 
>> On 9/29/2013 3:50 AM, Andreas Jaeger wrote:
>> Reviewing manuals, I've noticed that we use for options, parameters and
>> commands different kind of markup in an inconsistent way.
>> 
>> It looks to me that we used <literal> initially for everything but newer
>> text introduces sometimes:
>> * parameter: Often for command line parameters
>> * option:
>> * application: Used for some commands
>> * commands: Use for command line tools
>> * systemitem: Used with attribute class="service" for OpenStack services
>> like nova-api
>> 
>> Our Conventions wiki page is not describing what to use when - and the
>> docbook description is vague as well.
>> 
>> I'd like to see our Conventions page updated as guidance - and suggest
>> to not force changing our current usage of <literal>.
>> 
>> Could you help me descripting when to use what?
>> 
>> Here's a first brief shot for discussion:
>> 
>> <literal> is the generic markup item for some literal value. If
>> appropriate, use the less generic <parameter>, <option>, <application>
>> <command> or <systemitem> markup.
>> 
>> <systemitem class="service"> is used to describe the OpenStack services.
>> Example: <systemitem class="service">nova-api</systemitem>
>> 
>> <application> is used to describe software packages.
>> Example: <application>RabbitMQ</application>
>> 
>> <command> is used to describe software commands.
>> 
>> <parameter> is used to describe parameters to software commands.
>> Example: <parameter>-l</paramater> of <command>ls</command>
>> 
>> <option> is used to describe options in the configuration files
>> Example: <option>backend</option> in file <filename>nova.conf</filename>
>> 
>> What's your understanding? Did I miss anything?
>> 
>> Andreas
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs