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