OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: 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?

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]