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