One way to approach this issue is to assume that the semantics are simpler in task and in concept than they are in syntax diagram.
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.
Bob Thomas
+1 720 201 8260
From: Bruce Nevin (bnevin) <>
To: dita <>
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
