C to Lout preprocessor

[Jeff Kingston]

I'm just getting around to writing a C to Lout preprocessor,
and I would appreciate any comments on the way I plan to do
it as described in the following hypothetical manual entry.

Jeff Kingston.

============================================================




C2LOUT(1)           RISC/os Reference Manual            C2LOUT(1)



NAME
     c2lout - convert C source code into Lout

SYNOPSIS
     c2lout C-files
     c2lout -r Lout-files

DESCRIPTION
     Convert C source code into a slightly modified form suitable
     for input to the Lout document formatting system for pretty-
     printing, taking care of comments, character strings,
     backslash characters, etc.

     Without the -r flag, c2lout reads the named C source files
     and produces on standard output a Lout source file suitable
     for piping into the command "lout -icprint".  Thus the Unix
     pipeline

          c2lout myprog.c | lout -icprint | lpr

     will prettyprint a C program.  The cprint include file con-
     tains a large number of options for controlling the final
     appearance, including running headers, tables of contents,
     font changes, and so on.

     With the -r flag, c2lout reads the named Lout source files
     and replaces them with files in which the C parts, defined
     as everything lying outside any Lout comment or string and
     lying within @CC { ... }, are modified for prettyprinting.
     For example,

          in the following program:
          @IndentedDisplay @CC {
          for( i = 0;  i < MAX;  i++ ) {
              fprintf(stderr, "Error on line %d\n", i);
          }
          }
          and so on.

     becomes

          in the following program:
          @IndentedDisplay @CX {
          for( i = 0;  i < MAX;  i++ ) %{
              fprintf(stderr, "\"Error on line %d\\n\"", i);
          %}
          }
          and so on.

     Either the C part must have balanced braces or else it must
     be bracketed by the alternative form @CC @Begin ... @End
     @CC.  Note that @CC is replaced by @CX, which means that a
     second run through c2lout can do no harm.  If c2lout finds
     an error anywhere in the file, no replacement is made and
     the file remains as it was before.  This file replacement
     approach is better than piping everything straight into
     Lout, because the line numbers of Lout error messages are
     useless (naturally) under the latter scheme.

OPTIONS
     -u   Print usage information on stderr.

     -V   Print version information on stderr.

SEE ALSO
     lout(1), lpr(1), ghostview(1)

REFERENCES
     Jeffrey H. Kingston, "Printing C programs with the Lout
     document formatting system".

AUTHOR
     Jeffrey H. Kingston