Open Stack

Looks great to me and I myself need a lookup page for these sometimes.
Thanks David too for clarifying <literal>'s usage.

Anne


On Sun, Sep 29, 2013 at 2:50 AM, Andreas Jaeger <aj at suse.com> 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
> --
>  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
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130930/fcd52822/attachment.html>