Open Stack

+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
>