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: RE: [dita] CLI bridges sw and pr domains

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.)

From: masalsky_paul@emc.com [mailto:masalsky_paul@emc.com]
Sent: Tuesday, June 16, 2009 8:26 AM
To: Bruce Nevin (bnevin); dita@lists.oasis-open.org
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

From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
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?

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