[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] CLI bridges sw and pr domains
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 domainsWe 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 MasalskyEMC
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 domainsThe 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]