Ponderings on inlne documentation

GnuCOBOL
2014-08-28
2015-10-24
  • Brian Tiffin

    Brian Tiffin - 2014-08-28

    Would it be horrible if GNU Cobol supported a

    DOCUMENTATION
    ...
    END-DOCUMENTATION
    

    sequence, where the compiler just skipped over those lines and everything in between? Or should such a feature be relegated to a pre-processor? I'd appreciate the extension, and if anyone was worried about cross-compiler issues, the lines can be easily removed with

    sed '/DOCUMENTATION/,/END-DOCUMENTATION/d'
    

    Pondering out loud. (I was looking at POD and getting envious).

    Currently looking at

    perl -ne 'if (/^=doc$/../^=cut$/) {print unless /^=doc$/ or /^=cut$/}'
    

    to extract documentation sections, but it requires a pesky pre-processor pass, and multiple file names, and on and on.

    Cheers,
    Brian

    Later edit: out-of-thread-order

    DOH! Nevermind. It's all in cobc already.

    >>IF docpass DEFINED
    free text block, anything goes.
    >>ELSE
    ...all the code
    >>END-IF
    

    then

    cobc -x sourcefile.cob
    cobc -E -Ddocpass sourcefile.cob
    

    source.i will have the text blurbs, and a fair number of blank lines, but that should be ok. cat -s, super handy.

    compiles, holds text blurbs in plain english or favourite markup, COBODoc will do it's thing and pull any tagged comment lines, and well, yayy.

    Prefer text at the bottom?

    >>IF docpass NOT DEFINED
    ...
    end program sample.
    >>ELSE
    free text here, regardless of margin or comment
    >>END-IF
    

    Intermingle at will with extra >>IF blocks. Yayy. Right? Yayy? Errr. This could be rather hairpullingly catastrophic come a 3 am debug pass, but, the documentation will be all shiny.

    Later, later edit:
    One snag. Lines are preprocessed for FIXED to internal free form before the conditional compile directives. (For things like gluing together continuations), and this borks the column 7 special character test for the docpass text blocks. So,

    >>SOURCE FORMAT IS FREE
    

    before any docpass text blocks for inline documentation extraction to really work. FORMAT IS FREE doesn't need to poke around in column 7 before conditionals, for a win. Not 100%, but, inline text blocks seem like a reasonable thing to assume is available. It's close, I think.

    Please note: This edit was out-of-order, so what you read next starts out before the idea for this >>IF DEFINED thing

     
    Last edit: Brian Tiffin 2014-09-20
  • Simon Sobisch

    Simon Sobisch - 2014-08-28

    Sounds like something for a preprocessor. But it depends on what you want to do with it - just ignoring?
    You know: COBOL devs did use something like the following for decades.

          *> ---------- DOCUMENTATION START ----------
          *> Important stuff, at least 3 pages long ;-)
          *> ---------- DOCUMENTATION END ------------
    

    and I'm unsure why we should change this :-) Please explain your thoughts.

    Simon

     
    • Brian Tiffin

      Brian Tiffin - 2014-08-28

      Formatted documentation is a lot harder (harder is the wrong word, per-snickety) to write with a need for line comment characters.

      Again, just pondering. There are other ways, but I'm a fan of literate programming and the easier that is, the more it gets done.

      No rush, no worries.

      Cheers,
      Brian

       
      • Simon Sobisch

        Simon Sobisch - 2014-08-28

        It likely would be helpful if you post a sample how you think some inline documentation would look like. I still think I don't know what you mean :-)

        Simon

         
        • Brian Tiffin

          Brian Tiffin - 2014-08-28

          Something like

                 DOCUMENTATION
          This is free form documentation.
          And in this mode, it could be POD text, RST, Latex,
          Texinfo... completely ignored by the compiler until
          the next END-DOC... The idea is that all the doc
          segments get pulled out as a single entity so the
          documentation can be scattered about the source,
          where it is (hopefully) the most appropriate.
                 END-DOCUMENTATION
          
                *> ROBODoc API in-comment tags
                *> INPUT
                *>    nothing
                *> OUTPUT
                *>    a greeting
                *> SOURCE 
                 program-id. hello.
                 procedure division.    
                 display "Hello" end-display.
                 end program hello.
          
                 DOCUMENTATION
          And some more
          ...
                 END-DOCUMENTATION
          

          and that would pass through

          cobc -x sample.cob
          

          without need for preprocessing. End of file would assume END-DOCUMENTATION for any trailing docs. ROBODoc would still produce nice API level documentation, but the DOCUMENTATION blocks would allow for usage guides, etc.

          I made the sample with short lines, and with no markup, more for the benefit of the forge in this case. In reality, these segments (I'm trying to not use the word section, even though it is the better word) would be full of ReStructuredText or Markdown and Texi or Chinese fonts etc...

          Again, this is only a nice to have. I don't fear 'not to spec', as removing all those segments would be a simple one line sed expression for anyone porting the code to a less friendly compiler, but having the feature would ease adding inline documentation (meant for further processing by Sphinx, or pod2man, ... or humans) tremendously.

          And along with what Michael pointed out,

          DOCUMENTATION small or long one line snippet END-DOCUMENTATION
          

          would work as well.

          Cheers,
          Brian

           
          Last edit: Brian Tiffin 2014-08-28
          • Vincent (Bryan) Coen

            This I disagree on, and for more than one reason:

            1. It is not in the standard nor in an areas that is 'Implementer Defined'
            2. Any documentation detail must be in plain English or any other user
              national language, e.g., not Tex, Latex or similar.
            3. The start / end doc... etc can only override directly *> type
              comments but no professional programmer writes the programs/systems docs
              within programs. They are used for creating notes for programmers
              including the author regarding specific elements throughout the
              program.to detail multi lines of code.
            4. The place for program or system documentation is in respectively:
              A. System Specifications.
              B. System design Specifications..
              C. Program (design) Specifications for each program.

            Why do you also need to include such in a program that does not have the same power of say LibreOffice Writer?

            Vince

             
            Last edit: Simon Sobisch 2014-08-29
            • Brian Tiffin

              Brian Tiffin - 2014-08-29

              Points taken, Vincent.

              But I think Donald Knuth would disagree with your point 3 (as do I). ;-)

              I'm a huge fan of literate programming, and do inline guides (as well as auto generated API documentation all the time (or as often as feasible). It's how I guide developers at work. We have autogenerated docs for most of our programs.

              COBOL hasn't had the facilities defined yet, doesn't mean the future can't be brighter. Edit: That statement is kinda untrue. Compiler directives can be used to good effect in this area already. Already brighter.

              On point one. For anyone that doesn't like inline docs, or has to port to a different compiler

              sed -i '/DOCUMENTATION/,/END-DOCUMENTATION/d' a.cob
              

              and the file is, from then on, documentation free.

              As a for instance on the power of inline; take a look at some of the world class Perl applications, the Zoidberg shell for one. Inline usage material is an awesome thing, in my humble opinion. https://metacpan.org/source/JBERGER/Zoidberg-0.981/lib/Zoidberg/Shell.pm

              Python was designed with Docstrings as a core piece of every object. Programs, functions, anything, can have triple double-quote docstrings.

              And then there is the whole Knuth tangle/web side of things.

              But, we can get by with comment level documentation ala ocdoc. That style does slow down the typing and thought flow a little.

              http://opencobol.add1tocobol.com/gnucobol/#what-is-ocdoc and the output at http://opencobol.add1tocobol.com/ocdoc.html

              One reason for literate programming is 'in your face'. While editing code, if the usage material is inline, it is far more likely to be kept in synch.

              These are personal opinions Vincent, from a COBOL fan currently more involved with the documentation side of the fence than the application side.

              Cheers,
              Brian

               
              Last edit: Brian Tiffin 2014-09-20
              • Simon Sobisch

                Simon Sobisch - 2014-08-29

                Let's end discussion here for now, as the OCDOC way (parse everything you like from COBOL inline comments [with plain English, if possible]) is what we all can agree on and is both standard conforming and cross-compiler compatible. Depending on the editor (settings) it doesn't have to slow down typing as the block endings and start of next line can be added automatically.

                I think if you document as much as possible of your samples with OCDOC (or a change ROBODoc or whatever) it can really help to get a wider acceptance/use of it.

                Simon

                 
                • Brian Tiffin

                  Brian Tiffin - 2014-08-29

                  Grrr, ... ok. :-)

                  Actually, ROBODoc should play quite nicely with ocdoc, and vice versa.

                  Cheers,
                  Brian

                   
  • Michael Anderson

    I don't understand the problem?

    Why won't the following work:

    *> documentation <*
    *> end-documentation <*

    Sounds like a good idea?
    And of course lets not forget about the free format.

    Edit: put in some backslashes, so the asterisks come through

     
    Last edit: Brian Tiffin 2014-08-29
    • Brian Tiffin

      Brian Tiffin - 2014-08-28

      Free format was definitely the idea Michael. :)

      I'm a fixed form source coder, but much prefer to write documentation in a free form mode, and adding ocdoc tags (or similar) to every line is a pita.

      Cheers,
      Brian

       
      • steve williams

        steve williams - 2014-08-29

        Brian,
        I agree it's a pita to add *> to documentation lines. I'm a big fan of Python triple quotes, but they create an object that can be referenced, which is out of court for COBOL.
        That said, I can see someone in the future using this documentation feature to defeat large sections of live code, like the people who put a goto at the beginning of a large paragraph. Makes debugging at 3 a.m. lots of fun.

        Steve Williams

         
        • Brian Tiffin

          Brian Tiffin - 2014-08-29

          :-)

           
  • Brian Tiffin

    Brian Tiffin - 2014-09-05

    Anyone reading along to here. Top posted a preexisting solution;

    >>IF docpass DEFINED
    
    free form text, passed over by the cobc preprocessor
    
    >>ELSE
    *> the code
    identification division.
    ...
    
    >>END-IF
    

    Cheers,
    Brian

    And Steve will be right, a nearly undetectable misuse of compiler directives will bork something, somewhere, sometime

     
  • Brian Tiffin

    Brian Tiffin - 2015-10-24

    Yeah, a year later, some problems have emerged. :-)

    Turns out as the literate documentaion got more complicated, a hole in the plan was found.

    Hole in the plan? More like a huge DUMB.

    >>IF docpass NOT DEFINED
    code
    >>ELSE
    docs
    >>END-IF
    

    Well, here's the thing. The COBOL preprocessor was still running while scanning through the docs with cobc -Ddocpass -E. I'll let people realize how dumb that is before I explain...

    Yeah, that. :-)

    The latest piece of docs I went to generate included a

    prompt$ make docs
    cobc -Ddocpass -E gnucobol-rexx.cob
    gnucobol-rexx.cob: 694: Error: syntax error, unexpected ., expecting BY
    Makefile:18: recipe for target 'docs' failed
    make: *** [docs] Error 1
    

    Whoes'y whats now? Why would it try to compile inside that block ... whatsey whats?

    Oh,

    ...
    Add a limiting value to the top REPLACE phrase.  256 meg is defined in
    GnuCOBOL as the largest PIC size, even for BASED items.
    ...
    

    Scanner saw REPLACE, and started in on some more preprocessing. Doh. Data dependent holes are the best kinda holes. That led to a realization that everyone else is probably giggling about, and rolling eyes over, right about now...

    All preprocessor semantics were in play during the documentation extract. No lines can contain space delimited COPY, REPLACE (or INCLUDE an alias GnuCOBOL allows for COPY). Along with lines that start with $ or >> that would trigger a directive lookup. Or, you know, 108 different other edge cases that we rely on with the COBOL preprocessor, and a naive programmer never bumped into. Fate favours the fool.

    New rule. The make docs tectonics are actually much simpler. cobc doesn't need to be used to extract docs, it just needs to bypass the section during compiles. That all still works the charm, with one small wrinkle, embedded docs can't have lines that the scanner might mistake for compiler directives, as it lexically scans for the initial docpass >>END-IF or >>ELSE. So no documentation lines can start with $ or >>.

    A manageable wrinkle, and obvious, as cobc will complain during normal compiles.

    Much simpler, and far less randomly explodey.

    docs:
            sed ':loop;/rst-marker/{d};N;b loop' gnucobol-rexx.cob | sed '$$d' | rst2html >gnucobol-rexx.html
    

    Or, for better quality docs, skip the rst2html and simply redirect straight to a .rst file that Sphinx can use. By the by, getting rid of the >>END-IF last line is normally just $d, but make actually substitutes dollar variables, regardless of quoting, so the make rule needs to escape the sed command with a double dollar.

    Added a new rst-marker line, and Bob is back to being an uncle.

    Cheers

     
    Last edit: Brian Tiffin 2015-10-24

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks