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

One way to approach this issue is to assume that the semantics are simpler in task and in concept than they are in syntax diagram.

In the context of syntax diagram, the semantic goal is to delineate the rules for command usage.

In the context of task, the semantic goal is to direct the reader use a command for a specific purpose. Here, the nuances of command usage are unimportant and--except for varname--can be ignored. For example:

<cmd>Determine the size of the file by entering <cmdname>ls -l</cmdname> <varname>file-name</varname>.</cmd>

The fact that '-l' is an option for the 'ls' command is irrelevant to the reader in this context; therefore that markup can be omitted. Using <option> in this context would be similar to me asking a waiter for a glass of H2O instead of asking for a glass of water. If you accept the premise that semantics can vary somewhat among contexts, you may find that cmdname and varname are sufficient for documenting tasks in a CLI environment. I qualify this with 'may' because you could be dealing with something that is inherently complex and does not lend itself to this sort of simplication.

In the context of concept, I can make an argument similar to that for task. In my experience, cmdname is not used nearly as often in concept as it is in task; and, when it is, there is an excellent chance that the concept contains one or more embedded tasks.
Bob Thomas
Tagsmiths, LLC
+1 720 201 8260

From: Bruce Nevin (bnevin) <bnevin@cisco.com>
To: dita <dita@lists.oasis-open.org>
Sent: Tuesday, June 16, 2009 6:20:02 AM
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]