But that throws away the data
model for command structure. In particular, it doesn't admit any of the
<group*> elements. We use them to render e.g.
{ a | b
}
[ a |
b ]
as well as associating e.g.
keyword-argument pairs and other cohesive sequences, e.g.
command
a [ b c ]
d
It does have a richer content
model than <synph> but much of it is not particularly apt to this purpose.
(They have the same range of validity.)
/Bruce
From:
[mailto:]
Sent: Tuesday, June 16, 2009 8:26
AM
To: Bruce Nevin (bnevin);
Subject: RE: [dita] CLI bridges sw and pr
domains
We had the same issue with <syntaxdiagram> not
being valid as an ancestor of <cmdname>.
So we start all syntax diagrams with <codeph>
instead of <syntaxdiagram>.
Paul Masalsky
EMC
From: Bruce Nevin (bnevin)
[mailto:]
Sent: Tuesday, June 16, 2009 8:20
AM
To: dita
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
