I prefer railroad track diagrams...when they're done right. When railroad tracks are done with dashes, pluses, and 'OR' characters they look horrible. However, when done with box characters (horizontal rules, Tees, vertical rules), they look great.
The example you show is not very sophisticated and is an example that makes the OVERLAY syntax look OK. However, an example that has a "choice" group with many choices would look horrible. I don't know how the railroad track diagram is generated but in DITA (and BookMaster), they use syntax markup language which makes it very easy to change the diagram. Thanks, Be Wise with iWiseT John Bodoh Senior Designer [EMAIL PROTECTED] 919-460-4721 The infraWise/IRC Group of Companies 204 Shannon Oaks Cary, North Carolina, USA NC 27518 www.infraWise.com > -----Original Message----- > From: Rick McGuire [mailto:[EMAIL PROTECTED] > Sent: Sunday, August 24, 2008 11:30 AM > To: Open Object Rexx Developer Mailing List > Subject: [Oorexx-devel] Railroad tracks in docs > > I've never been a big fan of railroad track diagrams for syntax > diagrams, but they were an IBM standard so they sort of got imposed on > the Object Rexx docs. Now that I've had to update a few of these, I'm > even less of a fan of these. I find them hard to read, hard to > update, and easy to get wrong. I much prefer the simpler syntax that > MFC used in TRL. For example, here's the railroad track diagram for > OVERLAY() > > >>-OVERLAY(new,target-------------------------------------------> > > >--+---------------------------------------+--)---------------->< > +-,--+---+--+-------------------------+-+ > +-n-+ +-,--+--------+--+------+-+ > +-length-+ +-,pad-+ > > vs. Mike's syntax in TRL: > > OVERLAY(new,target[,[n][,[length][,pad]]]) > > This is much easier to scan from left-to-right to see what arguments > are optional, and is also easier to update to add additional > arguments. Anybody else in favor of changing this? > > Rick > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the > world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Oorexx-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/oorexx-devel ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Oorexx-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
