<div dir="ltr">Looks great to me and I myself need a lookup page for these sometimes. Thanks David too for clarifying <literal>'s usage. <div><br></div><div>Anne</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">

On Sun, Sep 29, 2013 at 2:50 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

Reviewing manuals, I've noticed that we use for options, parameters and<br>
commands different kind of markup in an inconsistent way.<br>
<br>
It looks to me that we used <literal> initially for everything but newer<br>
text introduces sometimes:<br>
* parameter: Often for command line parameters<br>
* option:<br>
* application: Used for some commands<br>
* commands: Use for command line tools<br>
* systemitem: Used with attribute class="service" for OpenStack services<br>
like nova-api<br>
<br>
Our Conventions wiki page is not describing what to use when - and the<br>
docbook description is vague as well.<br>
<br>
I'd like to see our Conventions page updated as guidance - and suggest<br>
to not force changing our current usage of <literal>.<br>
<br>
Could you help me descripting when to use what?<br>
<br>
Here's a first brief shot for discussion:<br>
<br>
<literal> is the generic markup item for some literal value. If<br>
appropriate, use the less generic <parameter>, <option>, <application><br>
<command> or <systemitem> markup.<br>
<br>
<systemitem class="service"> is used to describe the OpenStack services.<br>
Example: <systemitem class="service">nova-api</systemitem><br>
<br>
<application> is used to describe software packages.<br>
Example: <application>RabbitMQ</application><br>
<br>
<command> is used to describe software commands.<br>
<br>
<parameter> is used to describe parameters to software commands.<br>
Example: <parameter>-l</paramater> of <command>ls</command><br>
<br>
<option> is used to describe options in the configuration files<br>
Example: <option>backend</option> in file <filename>nova.conf</filename><br>
<br>
What's your understanding? Did I miss anything?<br>
<span class="HOEnZb"><font color="#888888"><br>
Andreas<br>
--<br>
 Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)<br>
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div>