I like syntax diagrams. On Fri, Jun 5, 2020 at 4:46 PM Charles Mills <charl...@mcn.org> wrote: > > The documentation is written to aid human beings. It is not a hard-core > exercise in logic. > > In writing doc I am often struck by a contrast to coding. In coding, if you > had to do the same three-line sequence at ten places in your code the right > thing would be to factor it out into a subroutine and invoke it ten times. In > writing doc OTOH the reader might be better served by your repeating the same > three sentences ten times rather than ten times saying "See the note at the > top of page 17" (which is roughly the documentation analog of a subroutine > call). > > It's a judgment call as to what will best help the reader. Sometimes > following logic rigorously is what best serves the reader. Probably better to > use a link to the JCL reference rather than doing a halfway job of explaining > DD statements in a COBOL manual. But as @Tony says, EXECIO is a particular > landmine for inexperienced Rexx coders. It is not wrong to make their lives > easier. > > And no, "therefore every technically similar feature should get the same > note" is not a valid corollary. > > Charles > > > -----Original Message----- > From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On > Behalf Of Paul Gilmartin > Sent: Friday, June 5, 2020 9:15 AM > To: IBM-MAIN@LISTSERV.UA.EDU > Subject: Re: Gratuitous EXECIO Documentation > > On Fri, 5 Jun 2020 12:01:18 -0400, Tony Thigpen wrote: > > >In my experience, over 30 years of using REXX on first VM, then VSE and > >now z/OS, I can't tell you how many times I have had to help people with > >the EXECIO syntax as it relates to "what is a keyword" and "what is a > >variable". I would put it at the top of the "common programming errors > >in REXX" list. > > > >I have seen the following error SOOOO many times: > >... "STEM" line. > >Which should be: > >... "STEM LINE." > > > >I would not consider this "gratuitous" documentation. > > > I'm outvoted. I shall submit one RCF for each command description > that does not contain such a caution asking that one be added. > > (I haven't checked. Perhaps they already exist.) > > -- gil > > ---------------------------------------------------------------------- > For IBM-MAIN subscribe / signoff / archive access instructions, > send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN > > ---------------------------------------------------------------------- > For IBM-MAIN subscribe / signoff / archive access instructions, > send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
-- Mike A Schwab, Springfield IL USA Where do Forest Rangers go to get away from it all? ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
