Re: visually describing command syntax ?

[Stuart Burnfield <slb -at- westnet -dot- com -dot- au>]

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. 

Stuart 


----- 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. 


Suzanne 


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: 
http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imstools.cex.doc.ug/ref-add-afl.htm#ref-add-afl 

2. A command with very many options, in which some of the detail is split out into sub-diagrams: 
http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imstools.cex.doc.ug/ref-add-hws.htm#ref-add-hws 

The rules for the visual syntax are explained here: 
http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.dzic.doc/commonsyn.htm 

-- 
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.
http://www.doctohelp.com

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com