In the context of syntax diagram, the semantic goal is to delineate the rules for command usage.
In the context of task, the semantic goal is to direct the reader use a command for a specific purpose. Here, the nuances of command usage are unimportant and--except for varname--can be ignored. For example:
<cmd>Determine the size of the file by entering <cmdname>ls -l</cmdname> <varname>file-name</varname>.</cmd>
The fact that '-l' is an option for the 'ls' command is irrelevant to the reader in this context; therefore that markup can be omitted. Using <option> in this context would be similar to me asking a waiter for a glass of H2O instead of asking for a glass of water. If you accept the premise that semantics can vary somewhat among contexts, you may find that cmdname and varname are sufficient for documenting tasks in a CLI environment. I qualify this with 'may' because you could be dealing with something that is inherently complex and does not lend itself to this sort of simplication.
In the context of concept, I can make an argument similar to that for task. In my experience, cmdname is not used nearly as often in concept as it is in task; and, when it is, there is an excellent chance that the concept contains one or more embedded tasks.
+1 720 201 8260
From: Bruce Nevin (bnevin) <bnevin@cisco.com>
To: dita <dita@lists.oasis-open.org>
Sent: Tuesday, June 16, 2009 6:20:02 AM
Subject: [dita] CLI bridges sw and pr domains
The programming domain includes <syntaxdiagram>
and its children, such as <kwd> and <var> for documenting programming languages. The
software domain includes alternative elements such as <keyword> and
<varname> for documenting software products. A CLI is a software product
that looks like a programming language, bridging
the two domains.
The syntax of a CLI command documented in
<reference> using <syntaxdiagram> can be reused entirely or in part
in various children of <concept> and <task> (albeit not in
<cmd>).
In a complex CLI, the initial sequence of
<kwd> elements is documented as a "command name". For example, there are
too many show commands to document as a single command, so they
are documented as show x, show y,
show z, show a b, show p q r,
etc. These are referred to and linked elsewhere by these complex "command
names".
The difficulty is how to refer to such a "command
name" outside of <syntaxdiagram> by reusing those children of
<syntaxdiagram> that are comprised in it, e.g.
<kwd>show</kwd></sep><kwd>p</kwd></sep><kwd>q</kwd></sep><kwd>r</kwd>.
Since they are grouped together for all instances of
that "command name" the natural inclination is to put them in <groupcomp>
or <groupseq>, but those elements are valid only in <syntaxdiagram>
or one of its children.
Outside of <syntaxdiagram> the elements that
comprise the "command name" can be grouped in <synph>, but <synph>
is not valid in <syntaxdiagram> so the advantages of reuse are
lost.
There are other complications, but this is the heart of
the matter so I won't burden this note with more
detail.
Surely, this has arisen before. Is there a ready
solution? Or is there a need to add a grouping element to <syntaxdiagram>
that can be reused widely?
/Bruce