CLI bridges sw and pr domains

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

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