Debian Codegraph @

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

raw
1 .TH TWILL 1 "3 February 2026" "Web2C 2026"
2 .\"=====================================================================
3 .if n .ds MF Metafont
4 .if t .ds MF Metafont
5 .if n .ds TX TeX
6 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
7 .\"=====================================================================
8 .SH NAME
9 twill, twill-refsort \- translate a literate programming WEB to TeX with mini-indexes
10 .SH SYNOPSIS
11 .PP
12 \f[B]twill\f[R] [\f[B]-x\f[R]]
13 \f[I]webfile\f[R][\f[B].web\f[R]]
14 [{\f[I]changefile\f[R][\f[B].ch\f[R]]|\f[B]-\f[R]}
15 [\f[I]outfile\f[R][\f[B].tex\f[R]]]]
16 .PD 0
17 .PP
18 \f[B]twill-refsort\f[R] <
19 \f[I]reffile\f[B].ref\f[R] >
20 \f[I]sreffile\f[B].sref\f[R]
21 .PD
22 .\"=====================================================================
23 .SH DESCRIPTION
24 The
25 .B twill
26 program is used to create a \*(TX file for viewing a literate program
27 written in WEB. The output \*(TX file name is formed by adding
28 .I .tex
29 to the root of the \*(WB file name.
30 .PP
31 \fBtwill\fP is like
32 .BR weave (1),
33 but also supplies cross-reference information in the form of
34 `mini-indexes' for each spread of pages, for identifiers used on that
35 spread, and a `master index' at the end that it gathers automatically.
36 .PP
37 You need to run
38 .B twill
39 twice, once to prime the pump and once to get decent answers.
40 Moreover, you must run the output twice through \*(TX.
41 .PP
42 For a program \fIfoo.web\fP, after a first
43 .I tex foo
44 you will have output that looks like final pages
45 except that the entries of mini-indexes will not be alphabetized.
46 The first run produces an auxiliary file named
47 .IR foo.ref .
48 .br
49 Run
50 .I twill-refsort <foo.ref >foo.sref
51 and then another
52 .I tex foo
53 will produce alphabetized output.
54 .\"=====================================================================
55 .SH OPTIONS
56 See
57 .BR tex (1)
58 for details of command-line parsing, and
59 .BR weave (1)
60 for options accepted.
61 .\"=====================================================================
62 .SH ENVIRONMENT
63 The environment variable WEBINPUTS is used to search for the input files,
64 If it is not set, it uses the system default. See the
65 Kpathsea manual at https://tug.org/kpathsea for the details of the
66 searching.
67 .\"=====================================================================
68 .SH BUGS
69 The table of contents file, \fICONTENTS.tex\fP, is generated but ignored
70 (unless macros in \fItwimac-web.tex\fP are redefined).
71 .\"=====================================================================
72 .SH FILES
73 .TP \w'@@'u+2n
74 .I $TEXMFMAIN/tex/plain/cweb/cwebbin/twimac-web.tex
75 \*(TX macros used by
76 .B twill
77 output.
78 .\"=====================================================================
79 .SH "SEE ALSO"
80 .BR tangle (1)
81 for references, authors, and other information about WEB in general.
82 .PP
83 Donald E. Knuth, Mini-indexes for literate programs,
84 Software\-Concepts and Tools, 15(1):2-11, 1994.
85 .br
86 https://arxiv.org/abs/cs/9401102
87 .PP
88 CTWILL program source, section 287:
89 .br
90 https://mirror.ctan.org/info/knuth-pdf/cweb/ctwill.pdf
91 .br
92 (Not all features described there are available in the older
93 \fBtwill\fP system, but you will get the gist.)
94 .PP
95 Public discussion list and bug reports: https://lists.tug.org/tex-k