Debian Codegraph @

texmf-dist/doc/man/man1/tangle.1

raw
1 .TH TANGLE 1 "25 January 2026" "Web2C 2026"
2 .\"=====================================================================
3 .if n .ds MF Metafont
4 .if t .ds MF Metafont
5 .if t .ds TX \fRT\\h'-0.10m'\\v'0.17v'E\\v'-0.17v'\\h'-0.06m'X\fP
6 .if n .ds TX TeX
7 .ie t .ds OX \fIT\h'-0.17m'\v'+0.21m'E\v'-0.21m'\h'-0.04m'X\fP
8 .el .ds OX TeX
9 .\"=====================================================================
10 .SH NAME
11 tangle, otangle \- translate a literate programming WEB to Pascal
12 .SH SYNOPSIS
13 \f[B]tangle\f[R] [\f[I]options\f[R]]
14 \f[I]webfile\f[R][\f[B].web\f[R]]
15 [{\f[I]changefile\f[R][\f[B].ch\f[R]]|\f[B]-\f[R]}
16 [\f[I]outfile\f[R][\f[B].p\f[R]]]]
17 .\"=====================================================================
18 .SH DESCRIPTION
19 The
20 .B tangle
21 program converts a WEB literate programming source document into a
22 Pascal program. In addition to being processed with a Pascal compiler,
23 nowadays, the Pascal output is often translated to C; this is how the
24 \*(TX family of programs are compiled in \*(TX Live.
25 .PP
26 The WEB language allows you to prepare a single document containing all
27 the information that is needed to produce both a compilable Pascal
28 program and a well-formatted document describing the program in as much
29 detail as the writer may desire. The user of WEB must be familiar with
30 both \*(TX and Pascal. WEB also provides a relatively simple, although
31 adequate, macro facility that permits a Pascal program to be written in
32 small modules, written in an arbitrary order.
33 .PP
34 The command line should have one, two or three filenames on it. The
35 first is taken as the WEB file; ".web" is added if there is no
36 extension.
37 .PP
38 If a second filename is given, it is taken as a change file, and ".ch"
39 is added if there is no extension. The change file overrides parts of
40 the WEB file, as described in the WEB system documentation. If no second
41 filename, there is no change file.
42 .PP
43 If a third filename is given, it is taken as the Pascal output file, and
44 ".p" is added if there is no extension. To specify an output file with
45 no change, you can use "-" for the second argument, meaning an empty
46 change file (not stdin). If no third filename is given, the name of the
47 Pascal file is formed by adding ".p" to the root of the WEB file name.
48 .PP
49 The output file is packed into lines of 72 characters or
50 less, with the only concession to readability being the termination of
51 lines at semicolons when this can be done conveniently.
52 .PP
53 If the WEB program uses the built-in string handling feature
54 (double-quoted strings), a second output file is a string pool file,
55 whose name is always formed by adding ".pool" to the root of the Pascal
56 file name.
57 .PP
58 The
59 .B otangle
60 variant supports a larger character range. It was written for the Omega
61 project, the first \*(TX supporting Unicode, now provided as the
62 .BR aleph (1)
63 descendant program.
64 .\"=====================================================================
65 .SH "OPTIONS"
66 See
67 .BR tex (1)
68 for details of command-line parsing.
69 .PP
70 Some of these options may render the output unsuitable for processing by
71 a Pascal compiler.
72 .TP
73 .B --help
74 Print help message and exit.
75 .TP
76 .BI --length \ number
77 Compare only the first
78 .I number
79 characters of identifiers when checking for collisions. The default
80 is 32; the original
81 .B tangle
82 used 7.
83 .TP
84 .B --loose
85 When checking for collisions between identifiers, honor the settings
86 of the
87 .BR --lowercase ,
88 .BR --mixedcase ,
89 .BR --uppercase ,
90 and
91 .B --underline
92 options. This is the default.
93 .TP
94 .B --lowercase
95 Convert all identifiers to lowercase.
96 .TP
97 .B --mixedcase
98 Retain the case of identifiers. This is the default.
99 .TP
100 .B --strict
101 When checking for collisions between identifiers, strip underlines and
102 convert all identifiers to uppercase first.
103 .TP
104 .B --underline
105 Retain underlines (also known as underscores) in identifiers.
106 .TP
107 .B --uppercase
108 Convert all identifiers to uppercase. This is the behaviour of the
109 original
110 .BR tangle .
111 .TP
112 .B --version
113 Print version information and exit.
114 .PP
115 .B otangle
116 supports only the \fB--help\fP and \fB--version\fP options,
117 .\"=====================================================================
118 .SH ENVIRONMENT
119 The programs look for the input files using the environment variable
120 WEBINPUTS. If it is not set, it uses the system default. See the
121 Kpathsea manual at https://tug.org/kpathsea for the details of the
122 searching.
123 .\"=====================================================================
124 .SH "SEE ALSO"
125 Donald E. Knuth,
126 .IR "The WEB System of Structured Documentation" .
127 .br
128 https://mirrors.ctan.org/info/knuth-pdf/web/webman.pdf
129 .PP
130 Donald E. Knuth,
131 .IR Literate Programming,
132 CSLI Lecture Notes, no. 27.
133 .br
134 https://www-cs-faculty.stanford.edu/~knuth/lp.html
135 .PP
136 Donald E. Knuth,
137 .I "\*(OX: The Program"
138 (Volume B of
139 .IR "Computers & Typesetting" ).
140 .br
141 Donald E. Knuth,
142 .I "\*(MF: The Program"
143 (Volume D of
144 .IR "Computers & Typesetting" ).
145 .br
146 These latter two are by far the largest extant examples of WEB programs.
147 .PP
148 Literate programming topic on CTAN: https://ctan.org/topic/litprog
149 .br
150 Package page on CTAN: https://ctan.org/pkg/tangle
151 .br
152 Section in the Web2c manual:
153 https://tug.org/texinfohtml/web2c.html#tangle-invocation
154 .br
155 Typeset source code for all the original Stanford WEB programs:
156 https://ctan.org/pkg/knuth-pdf
157 .\"=====================================================================
158 .SH AUTHORS
159 WEB was designed by Donald E. Knuth, based on an earlier system called
160 DOC (implemented by Ignacio Zabala), inspired by considerable earlier
161 work, notably Pierre-Arnoul de Marneffe's concept of ``holon
162 programming'' (https://github.com/holon-scribe/holon-programming).
163 .PP
164 The updates for Omega were written by John Plaice and Yannis Haralambous.
165 .PP
166 The
167 .B tangle
168 and
169 .B weave
170 programs are themselves written in WEB. The system was originally ported
171 to Unix at Stanford by Howard Trickey, and at Cornell by Pavel Curtis.
172 .PP
173 Public discussion list and bug reports: https://lists.tug.org/tex-k