home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / shroud.zip / SHROUD.MAN < prev    next >
Text File  |  1990-01-14  |  5KB  |  119 lines
  1. SHROUD (1)                                                        SHROUD (1)
  2.  
  3. NAME
  4.  
  5.         SHROUD - ANSI-conforming C language source code shrouder Version 2
  6.  
  7. SYNOPSIS
  8.  
  9.         shroud [ option ] file [ file ] ...
  10.  
  11. DESCRIPTION
  12.  
  13.         shroud copies the input [ files ] to standard output, expanding C
  14.         language macros and executing C language preprocessor directives as
  15.         specified in the Draft Proposed ANSI Standard for the C Language.
  16.  
  17.         In the process, all white space is removed, and the output is formed
  18.         into long lines.  All identifiers, other than those first encountered
  19.         in library header (#include <...>) files are replaced with
  20.         gobbledygook.
  21.  
  22.         The following options are recognized.
  23.  
  24.         -d or -D        Define the following (empty) macro.
  25.         -l or -L        Shroud identifiers in library headers as well.
  26.         -w or -W        Leave whitespace unaffected.
  27.         -x or -X        Do not recognize Watcom extended keywords.
  28.  
  29.         The preprocessed output may be used as input to most C compilers.
  30.         #pragmas and extended keywords specific to the Watcom C compiler are
  31.         specifically recognized.
  32.  
  33. EXAMPLES
  34.  
  35.         The following command displays the source file EXAMPLE.C on standard
  36.         output, after performing all preprocessing directives, replacing all
  37.         macros, and shrouding.
  38.  
  39.                 shroud example.c
  40.  
  41.         The following command deposits the shrouded source of EXAMPLE.C in the
  42.         file EXAMPLE.SHR.  White space is retained, library headers are
  43.         shrouded, extended keywords are treated as ordinary identifiers, and a
  44.         macro is defined as if by "#define MACRO_NAME".
  45.  
  46.                 shroud -wlxdMACRO_NAME example.c >example.shr
  47.  
  48.         The following command deposits the shrouded source of EXAMPLE.H and
  49.         EXAMPLE.C in the file EXAMPLE.SHR.  EXAMPLE.H is handled as if the
  50.         directive "#include "example.h"" precedes the first line of EXAMPLE.C.
  51.  
  52.                 shroud example.h example.c >example.shr
  53.  
  54. SEE ALSO
  55.  
  56.         Steven Bruce Williams
  57.         "Using Tomorrow's C Standard Today"
  58.         Computer Language Magazine
  59.         Volume 5, Number 7
  60.         July 1988
  61.  
  62.         Draft Proposed American National Standard for Information Systems --
  63.         Programming Language C - X3 Secretariat: Computer and Business
  64.         Equipment Manufacturers Association - Available from Global
  65.         Engineering Documents, Inc. 800-854-7179
  66.  
  67.         WATCOM C Optimizing Compiler and Tools User's Guide
  68.         WATCOM Publications Limited
  69.         415 Phillip Street
  70.         Waterloo, Ontario, Canada
  71.         N2L 3X2
  72.         519-886-3700
  73.  
  74. BUGS
  75.  
  76.         Token pasting is quite limited.  The left token must be an identifier.
  77.         The right token must be either an identifier or an integer.  The
  78.         result is always an identifier.  Although this probably permits the
  79.         most common usage, there are certainly others that are valid.
  80.  
  81.         The shrouding is quite unsophisticated.
  82.  
  83.         If more than one shrouded modules need to have linkage to each other,
  84.         the programmer must sit funny in his chair while writing the
  85.         unshrouded source code, as follows.
  86.  
  87.         1. All objects with external linkage (see ANSI 3.1.2.2) must be
  88.            declared in #include files.  (It can be argued that it is bad form
  89.            to declare objects with external linkage other than in #include
  90.            files in any case.)
  91.  
  92.         2. These #include files must contain #if directives that render them
  93.            empty if #included more than once.  For example, the file EXAMPLE.H
  94.            might start with:
  95.  
  96.                 #if !defined(EXAMPLE_H)
  97.                 #define EXAMPLE_H
  98.  
  99.            and end with:
  100.  
  101.                 #endif
  102.  
  103.         3. ALL #include files used by ANY of the modules must precede EACH
  104.            module on the shroud command line, in exactly the same order.  For
  105.            example:
  106.  
  107.                 shroud include1.h include2.h include3.h module1.c >module1.shr
  108.                 shroud include1.h include2.h include3.h module2.c >module2.shr
  109.                 shroud include1.h include2.h include3.h module3.c >module3.shr
  110.  
  111.            Remember, ALL #include files must precede EVERY module, even if the
  112.            module does not use the include file.
  113.  
  114.         These steps are necessary because each identifier's gobbledygook
  115.         replacement is determined, in part, by the order in which identifiers
  116.         are encountered.  Including every #include file in the same order for
  117.         each module ensures that the gobbledygook for identifiers with
  118.         external linkage is the same for each module.
  119.