Open Stack

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
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126