I agree with John: ASCII-art rail diagrams can be a visual disaster, but often no worse than the typesetter-only massive (and massively nested) braces, brackets, commas, and ellipses of the IBM documentation style they replaced.
And he's also right about the flexibility of rail diagrams when it comes to complex syntax with nested "required options" and other dependent relationships. I also agree with David that while presentation might not be everything, it should be the first thing. Immediate clarity should be the goal, with explicit accuracy available should the user need to drill down to that level. I've seen examples of most of the other documentation styles mentioned and none of them jump out at me as sufficiently superior to what we have to justify the wholesale conversion of the ooRexx documentation yet. As for automating the documentation update process, I recall a utility some time ago that took a set of BNF specifications (or was it yacc?) and would output the syntax diagrams. Probably not applicable in this case, but 'twould be nice if the diagrams were autogenerated from the source. It would also provide another component of the test suite. -Chip- On 8/25/08 12:15 John R bodoh said: > 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 > > ------------------------------------------------------------------------- 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
