source/texk/web2c/man/tangle.man

   1 .TH TANGLE 1 "16 June 2015" "Web2C @VERSION@"
   2 .\"=====================================================================
   3 .if n .ds MF Metafont
   4 .if t .ds MF Metafont
   5 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
   6 .if n .ds TX TeX
   7 .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
   8 .el .ds OX TeX
   9 .\" BX definition must follow TX so BX can use TX
  10 .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
  11 .if n .ds BX BibTeX
  12 .\" LX definition must follow TX so LX can use TX
  13 .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
  14 .if n .ds LX LaTeX
  15 .if n .ds WB Web
  16 .if t .ds WB W\s-2EB\s0
  17 .\"=====================================================================
  18 .SH NAME
  19 tangle \- translate WEB to Pascal
  20 .SH SYNOPSIS
  21 .B tangle
  22 .RI [ options ]
  23 .IR webfile [ \fB.web\fP ]
  24 .RI [ changefile [ \fB.ch\fP ]]
  25 .\"=====================================================================
  26 .SH DESCRIPTION
  27 This manual page is not meant to be exhaustive.  The complete
  28 documentation for this version of \*(TX can be found in the info file
  29 or manual
  30 .IR "Web2C: A TeX implementation" .
  31 .PP
  32 The
  33 .B tangle
  34 program converts a \*(WB
  35 source document into a Pascal program that may be compiled in the usual
  36 way with the on-line Pascal compiler (e.g.,
  37 .BR pc (1)).
  38 The output file is packed into lines of 72 characters or less, with
  39 the only concession to readability being the termination of lines at
  40 semicolons when this can be done conveniently.
  41 .PP
  42 The \*(WB language allows you to prepare a single document containing all
  43 the information that is needed both to produce a compilable Pascal
  44 program and to produce a well-formatted document describing the program
  45 in as much detail as the writer may desire.  The user of \*(WB must be
  46 familiar with both \*(TX and Pascal.  \*(WB also provides a relatively
  47 simple, although adequate, macro facility that permits a Pascal program
  48 to be written in small easily-understood modules.
  49 .PP
  50 The command line should have either one or two names on it.
  51 The first is taken as the \*(WB file (and
  52 .B .web
  53 is added if there is no
  54 extension).
  55 If there is another name, it is a change file (and
  56 .B .ch
  57 is added if there is
  58 no extension).  The change file overrides parts of the \*(WB file,
  59 as described in the \*(WB system documentation.
  60 .PP
  61 The output files are a Pascal file and a string pool file,
  62 whose names are formed by adding
  63 .B .p
  64 and
  65 .B .pool
  66 respectively to the root of the \*(WB file name.
  67 .\"=====================================================================
  68 .SH "OPTIONS"
  69 This version of
  70 .B tangle
  71 understands the following options.  Note that some of these options
  72 may render the output unsuitable for processing by a Pascal compiler.
  73 .TP
  74 .B --help
  75 Print help message and exit.
  76 .TP
  77 .BI --length \ number
  78 Compare only the first
  79 .I number
  80 characters of identifiers when checking for collisions.  The default
  81 is 32, the original
  82 .B tangle
  83 used 7.
  84 .TP
  85 .B --loose
  86 When checking for collisions between identifiers, honor the settings
  87 of the
  88 .BR --lowercase ,
  89 .BR --mixedcase ,
  90 .BR --uppercase ,
  91 and
  92 .B --underline
  93 options. This is the default.
  94 .TP
  95 .B --lowercase
  96 Convert all identifiers to lowercase.
  97 .TP
  98 .B --mixedcase
  99 Retain the case of identifiers.  This is the default.
 100 .TP
 101 .B --strict
 102 When checking for collisions between identifiers, strip underlines and
 103 convert all identifiers to uppercase first.
 104 .TP
 105 .B --underline
 106 Retain underlines (also known as underscores) in identifiers.
 107 .TP
 108 .B --uppercase
 109 Convert all identifiers to uppercase.  This is the behaviour of the
 110 original
 111 .BR tangle .
 112 .TP
 113 .B --version
 114 Print version information and exit.
 115 .\"=====================================================================
 116 .SH ENVIRONMENT
 117 The environment variable WEBINPUTS is used to search for the input files,
 118 or the system default if WEBINPUTS is not set.  See
 119 .BR tex (1)
 120 for the details of the searching.
 121 .\"=====================================================================
 122 .SH "SEE ALSO"
 123 .BR pc (1),
 124 .BR pxp (1)
 125 (for formatting
 126 .B tangle
 127 output when debugging),
 128 .BR tex (1).
 129 .PP
 130 Donald E. Knuth,
 131 .IR "The \*(WB System of Structured Documentation" .
 132 .PP
 133 Donald E. Knuth,
 134 .IR "Literate Programming" ,
 135 Computer Journal
 136 .BR 27 ,
 137 97\-111, 1984.
 138 .PP
 139 Wayne Sewell,
 140 .IR "Weaving a Program" ,
 141 Van Nostrand Reinhold, 1989, ISBN 0-442-31946-0.
 142 .PP
 143 Donald E. Knuth,
 144 .I "\*(OX: The Program"
 145 (Volume B of
 146 .IR "Computers and Typesetting" ),
 147 Addison-Wesley, 1986, ISBN 0-201-13437-3.
 148 .PP
 149 Donald E. Knuth,
 150 .I "\*(MF: The Program"
 151 (Volume D of
 152 .IR "Computers and Typesetting" ),
 153 Addison-Wesley, 1986, ISBN 0-201-13438-1.
 154 .PP
 155 These last two are by far the largest extant examples of \*(WB
 156 programs.
 157 .PP
 158 There is an active Internet electronic mail discussion list on the
 159 subject of literate programming; send a subscription request to
 160 .I litprog-request@shsu.edu
 161 to join.
 162 .\"=====================================================================
 163 .SH AUTHORS
 164 \*(WB was designed by Donald E. Knuth, based on an earlier system
 165 called DOC (implemented by Ignacio Zabala).
 166 The
 167 .B tangle
 168 and
 169 .B weave
 170 programs are themselves written in \*(WB. The system
 171 was originally ported to Unix at Stanford by Howard Trickey, and at
 172 Cornell by Pavel Curtis.