literac A Program That Enables Literate Commenting Doug McKenna Mathemaesthetics, Inc. Boulder, Colorado TUG — 2014
Literate Programming ◮ The phrase was introduced by Don Knuth 30 years ago ◮ Memo: “The WEB System of Structured Documentation”, Stanford Univ., 1983 ◮ An amalgam of Pascal and T EX, with its own added layer of markup commands ◮ Two post-processing tools— TANGLE and WEAVE —create separate Pascal code and T EX documentation files ◮ CWEB and tools created in 1991 by Knuth and Levi ◮ web2c , by Tom Rokicki, processes WEB code directly to C code ◮ T EX’s source code is still written in WEB , 30 years later
Problems that WEB solved ◮ Formal conversion and re-arrangement of pseudo-code constructs into code ◮ Enriched reading experience: fonts and T EX-quality typesetting ◮ Code and documentation more easily kept synchronized ◮ Automatic upward movement of code lines from the best expositional spot to a correct compilable spot ◮ No macro preprocessor in Pascal language ◮ Simple syntax for typesetting code | snippets | inside comments ◮ Treats a large program as a piece of literature worth reading (at least, if one writes well) ◮ Automated document features (table of contents, index, etc.)
Why do most programmers not use WEB (or CWEB )? ◮ Markup is terse, undiscoverable, not quite free-form ◮ Requires—rather than gently permits—the programmer to think in several languages at once ◮ The WEB / TANGLE / WEAVE bootstrap keeps users away ◮ Fosters the use of global variables; turns locals into “globals” ◮ Complicates and slows down the edit-compile-test cycle for working programmers (in the zone) ◮ Code is typeset as mathematical notation, not as code ◮ Solutions should be in the computer language and IDE editors ◮ Search the internet for “literate programming” and ”failure” for more
As a Programmer, I Want Literate Commenting with ◮ Sweet incremental simplicity, reasonable power, but no lock-in ◮ Documentation derived from source code, not vice-versa ◮ Documenting independent of edit-compile-test cycle ◮ Only a few, innocuous markup commands to remember ◮ Original source still readable/understandable after markup ◮ Code format/style inviolate (no pretty-printing; yes long lines) ◮ Defaults for immediate success or “good enough” solutions ◮ Decent higher-level error reporting and recovery ◮ No fighting against T EX/L A T EX ignorance/confusion ◮ Access to L A T EX’s power if I need it (and know what I’m doing) ◮ An inviting, literate, well-typeset exposition of my program ◮ A L A T EX file to modify further, if I want or need to
What is “literac”? ◮ literac is (currently) a command-line program, written in C ◮ Written to “codify” commenting conventions in large C library ◮ Comprises 6000 lines of code, 6000 of literate commenting ◮ Eats its own dog food to create manual and literate program ◮ Processes about 100,000 lines of C source code per second ◮ Supports multiple input files and options in one invocation ◮ Outputs one or more L A T EX files that can be immediately run ◮ Needs fancyvrb , dashrule , and other standard packages ◮ Does not rely on listings or similar packages ◮ Currently, only supports comments using /* . . . */ or //... ◮ Languages: C, C++, Objective-C, Go, Swift, and few others ◮ Handles obscure edge cases and (some) commenting idioms
Typeset Comments Don’t Need No Stinkin’ Delimiters ◮ Delimiters // and /*...*/ are for the benefit of compiler ◮ And they are for the benefit of source code author (initially) ◮ But they are (usually) unnecessary for a reader ◮ Delimiters are redundant in editors that do syntax coloring ◮ Delimiters in source code are thus syntactic noise ◮ They interfere with vertical eye scanning of left edge of code ◮ Typesetting is about visual hints on behalf of meaning ◮ So . . . literac gets rid of all delimiters, unless doing so would introduce ambiguity ◮ Comments must therefore use different type styles from code ◮ Code is easy: get it into a verbatim fixed-width code font ◮ literac focuses on comments much more than code
C-style Comment Taxonomy Two classes of comment delimiter: block and gloss ◮ Gloss comments use // and the end of same line (usually) ◮ Block comments use /* ... */ (possibly multiple lines) ◮ Also pseudo-gloss: /* ... // ... */ ◮ And pseudo-block: // ... /* ... */ ◮ Nested block: /* ... /* ... */ ... */ (Swift only) (not yet supported)
Comment Taxonomy – Rest-of-Line Gloss Comments Gloss-only (after indentation, comment on entire line) ◮ // ◮ // text ◮ // text \ more text Code then gloss on remainder of line ◮ foo = bar(n); // ◮ bar = foo(n); // text ◮ foo = bar(n); // text \ more text
Comment Taxonomy – Single Line Block Comments ◮ /**/ ◮ /* */ ◮ /* text */ ◮ /* text \ more text */ ◮ foo = bar(n); /* text */ ◮ foo = bar(n); /* text */ /* more text */ ◮ /* text */ bar = foo(n); /* more text */ ◮ foo = bar( /* text */ n);
Comment Taxonomy – Simple Block Comments ◮ /* */ ◮ /* text (delimiters are on their own lines) */ ◮ /* indented text */ ◮ /* * text * more text * yet more text * and a vertical * bar */
Comment Taxonomy – Quiet Block Comments Simple block comments with delimiters far to the right: /* ◮ A line of commenting text. */ /* ◮ A line of commenting text. Another line of commenting text. */ Style reduces syntactic noise on left edge of source code
Comment Taxonomy – Complex Block Comments /* or */ occurs on same line as some comment text or code ◮ /* text ... ... more text */ ◮ foo = far(n); /* text more text */ ◮ /* text more text */ foo = far(n); literac works to regularize these into simple block comments
Comment Taxonomy – ASCII Art Block Comments ◮ Lines or boxes made of * to create poor man’s rules ◮ /**************************************/ /* And In This Section of the Program */ /**************************************/ ◮ /************************************** \ * And In This Section of the Program * \ **************************************/ (this second example abuses line continuation on first line) ◮ literac erases the bars (currently doesn’t replace with any rules, but might in the future) to regularize
What literac does ◮ Classify each input line’s start as “in code” or “in comment” ◮ Determine whether line ends in code or comment ◮ Honor line continuation only for comment line ends, not code ◮ Divide line into two (possibly empty) areas: code or comment ◮ Typeset code area on left using verbatim fixed-width font ◮ Strip comment delimiters, unless in code area, or if ambiguity ◮ Execute all literac commands in remaining comment text ◮ Converts dividers to rules, and manages a table of contents ◮ Prevent T EX from getting confused by special characters ◮ Attempt to do smart-quoting in both code and comment ◮ Let T EX merge “similar” comment lines into paragraphs ◮ Comment vs. commentary styles, based on indentation or not
Special Delimiters Available Within Block Comments When typesetting block comment lines, literac responds to the following patterns when they appear by themselves (after any indentation, but no other text) on any line: ◮ /* Start a block comment, delete line if not indented ◮ */ End a block comment, delete line if not indented ◮ \\ Toggle one-liner mode; delete line if not indented If line not deleted, it becomes blank and is honored as such. ◮ |@ enters pure T EX line collection mode; line is deleted ◮ @| exits pure T EX line collection mode; line is deleted Pure T EX collection mode allows the injection of 0 or more lines of arbitrary T EX or L A T EX code, exactly as if in a ".tex" file.
Super Gloss Comments A super gloss comment tells literac to delete the delimiter and the rest of the line from the typeset code. There are three variants: ◮ /// Delete rest of line, trim whitespace, delete line if empty ◮ //@ Same, but doesn’t conflict with, e.g., Doxygen ◮ //. Delete rest of line, trim, but leave line blank if empty These are good for commenting out code that serves no purpose in the typeset version. Good for issuing literac gloss comment commands on lines that won’t be typeset as blank.
Special Commands Within Block or Gloss Comment Text literac commands consist of an identifier immediately followed by a (possibly empty) brace-enclosed argument. Everything must (currently) be on one comment line. These can occur anywhere in a block or gloss comment’s text. ◮ emph { text } Emphasize text (uses \ emph in L A T EX file) ◮ bold { text } Put text into bold (uses \ bfseries ) ◮ math { formula } Typeset formula inside $...$ math mode ◮ Math { formula } Same, but use a $$...$$ math display ◮ text { line } Prevent short line from being a divider title ◮ toc { title } Insert table of contents labeled with title Without an immediate left brace, it’s just more comment text.
Recommend
More recommend
