RE: [dita] CLI bridges sw and pr domains

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:] 
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) 
  <>
To: 
  dita <>
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