RE: [dita] CLI bridges sw and pr domains

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

That foregoes reuse.

 

Our users have the expectation of seeing the command syntax in a task step. If they need more information about how to use the command or the significance of keywords and arguments (especially optional ones), they go to the reference doc, but they typically expect only to need a local reminder. Hence, the need of verbatim reuse.

 

For content maintenance, we want to be able to find every occurrence of a given "command name", hence the need for a "command name" outside as well as inside <syntaxdiagram>, and a further motivation for reuse. Likewise for linking, e.g. automatic creation of links to the reference document.

 

I proposed putting <synph> (or an element specialized from it) in front of <syntaxdiagram> and the following keywords and arguments & their groups into <syntaxdiagram>. It was objected that this breaks the intended semantics of <syntaxdiagram>, but it is the best compromise I have come up with so far. <synph> can go in <refsyn> as well as in many other places in all topic types.

 

<synph> does not admit the <group*> elements. This could cause a problem for this solution. Bear in mind the way that complex command families are broken out into 'as-documented' commands, each with a more or less complex 'command name'. In the nature of software development, a 'command name' can be interrupted by variables which must be part of syntax but are not rendered when the 'command name' is cited or referred to elsewhere. There is nothing to prevent a software developer from interrupting a 'command name' with a keyword-variable pair or other group, and these can be optional.

 

Ability to use <groupcomp> or <groupseq> over the range in which <synph> is valid would solve the problem.

 

Alternatively, we could just not use <syntaxdiagram>. I am reluctant to endorse the logical line of argument from there that this part of DITA was a mistake and should be deprecated. XML is about semantics with the details of format relegated to rendering, after all.

 

    /Bruce

---

From: Bob Thomas [mailto:bob.thomas@tagsmiths.com]
Sent: Tuesday, June 16, 2009 11:00 AM
To: dita
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

+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?

 

    /Bruce