Re: visually describing command syntax ?

Subject: Re: visually describing command syntax ?
From: Stuart Burnfield <slb -at- westnet -dot- com -dot- au>
To: Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 18 Nov 2011 13:44:56 +0800 (WST)

Hi Suzanne -

Yes, it's a nice feature that you can specify a diagram using DITA markup, validate it, and then generate the output. I don't know if this is true of DITA in general or if the diagrams are a feature of IBM's in-house implementation. There are tools such as GraphViz for generating diagrams from a text file but I don't know of a standalone tool for generating exactly this sort of IBM diagram. Maybe DocBook XML has something similar?

It would certainly be a pain to maintain a bunch of complex diagrams in a drawing tool. I guess you could create a Visio stencil containing standard diagram fragments and just assemble diagrams as if from Lego blocks.


----- Original Message -----
From: "Suzanne Chiles" <suzchiles -at- gmail -dot- com>
To: "Stuart Burnfield" <slb -at- westnet -dot- com -dot- au>
Cc: "Techwr-l" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Friday, 18 November, 2011 11:39:47 AM GMT +08:00 Beijing / Chongqing / Hong Kong / Urumqi
Subject: Re: visually describing command syntax ?

Thanks for the more complete and accurate follow-up, Stuart. I was at the office and in too much of a hurry. DITA, of course, has elements that support and generate this output.


On Thu, Nov 17, 2011 at 5:17 PM, Stuart Burnfield < slb -at- westnet -dot- com -dot- au > wrote:

Here are another couple of examples of the IBM visual syntax diagramming style.

1. A fairly simple command showing required, default, optional and repeatable parameters:

2. A command with very many options, in which some of the detail is split out into sub-diagrams:

The rules for the visual syntax are explained here:

Suzanne Chiles
suzchiles -at- gmail -dot- com


Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Previous by Author: Re: visually describing command syntax ?
Next by Author: Re: Flow Charts
Previous by Thread: Re: visually describing command syntax ?
Next by Thread: Re: visually describing command syntax ?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads