summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/ctwill.1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-02-28 19:09:21 +0000
committerKarl Berry <karl@freefriends.org>2019-02-28 19:09:21 +0000
commit342f4c70c13251fa670faa123091c128ec8bfdda (patch)
tree1738b687cc48d0cdb5551aee4e90bb291403c3b4 /Master/texmf-dist/doc/man/man1/ctwill.1
parent3a9439b815af6c2d41c60f6694d88f2852544442 (diff)
tl19 man page update
git-svn-id: svn://tug.org/texlive/trunk@50169 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/ctwill.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/ctwill.1239
1 files changed, 239 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/ctwill.1 b/Master/texmf-dist/doc/man/man1/ctwill.1
new file mode 100644
index 00000000000..b8b29e1b0f9
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/ctwill.1
@@ -0,0 +1,239 @@
+.\" Automatically generated by Pandoc 2.6
+.\"
+.TH "CTWILL" "1" "January 27, 2019" "Web2c 2019" "General Commands Manual"
+.hy
+.SH NAME
+.PP
+ctwill, ctwill-refsort, ctwill-twinx \[en] translate CWEB to TeX
+.PD 0
+.P
+.PD
+with mini-indexes per spread or per section
+.SH SYNOPSIS
+.PP
+\f[B]ctwill\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w]
+[{\f[I]changefile\f[R][.ch]|-} [\f[I]outfile\f[R][.tex]]]
+.PD 0
+.P
+.PD
+\f[B]ctwill-refsort\f[R] < \f[I]indexfile\f[R].ref > \f[I]indexfile\f[R].sref
+.PD 0
+.P
+.PD
+\f[B]ctwill-twinx\f[R] \f[I]outfile\f[R].tex [\f[I]outfile\f[R].tex \&...] >
+index.tex
+.SH DESCRIPTION
+.PP
+The \f[B]ctwill\f[R] program converts a CWEB source document into a
+TeX\ file that may be formatted and printed in the usual way.
+It takes appropriate care of typographic details like page layout and
+the use of indentation, \f[I]italics\f[R], \f[B]boldface\f[R], etc., and
+it supplies extensive cross-index information that it gathers
+automatically.
+.PP
+CWEB allows you to prepare a single document containing all the
+information that is needed both to produce a compilable C/C++\ program
+and to produce a well-formatted document describing the program in as
+much detail as the writer may desire.
+The user of CWEB ought to be familiar with TeX as well as C/C++.
+.SH USAGE
+.PP
+The command line should have one, two, or three names on it.
+The first is taken as the CWEB input file (and \f[B].w\f[R] is added if
+there is no extension).
+If there is a second name, it is a change file (and \f[B].ch\f[R] is
+added if there is no extension).
+The change file overrides parts of the CWEB file, as described in the
+documentation.
+If there is a third name, it overrides the default name of the output
+file, which is ordinarily the same as the name of the input file (but on
+the current directory) with the extension \f[B].tex\f[R].
+If you just want to change the output file name, but don\[cq]t have a
+change file to apply, you can use `\f[B]-\f[R]' as the second argument.
+.PP
+\f[B]ctwill\f[R] is exactly like \f[B]cweave\f[R] except that it
+produces much better documentation, for which you must work harder.
+You should run \f[B]ctwill\f[R] twice, once to prime the pump and once
+to get decent answers.
+Moreover, you must run the output twice through TeX.
+.PP
+After \f[B]tex foo\f[R] you will have output that looks like final pages
+except that the entries of mini-indexes won\[cq]t be alphabetized.
+The first run produces a weird file called \f[B]foo.ref\f[R].
+Say \f[B]ctwill-refsort < foo.ref > foo.sref\f[R] and then another \f[B]tex
+foo\f[R] will produce alphabetized output.
+.PP
+The \f[B]ctwill-twinx\f[R] program compiles a master index for a set of related
+programs that have been processed by \f[B]ctwill\f[R].
+The individual programs should define their names with a line of the
+form \f[B]\[rs]def\[rs]title{NAME}\f[R].
+.PP
+The mini-indexes list identifiers that are used but not defined on each
+two-page spread.
+At the end of each section, \f[B]ctwill\f[R] gives TeX a list of
+identifiers used in that section and information about where they are
+defined.
+.PP
+The current meaning of every identifier is initially
+\f[B]\[rs]uninitialized\f[R].
+Then \f[B]ctwill\f[R] reads the \f[B].aux\f[R] file for your job, if
+any.
+.PP
+Before reading the \f[B].aux\f[R] file, \f[B]ctwill\f[R] actually looks
+for a file called \f[B]system.bux\f[R], which will be read if present.
+And after \f[B]foo.aux\f[R], a third possibility is \f[B]foo.bux\f[R].
+The general convention is to put definitions of system procedures such
+as \f[I]printf\f[R] into \f[B]system.bux\f[R], and to put definitions
+found in specifically foo-ish header files into \f[B]foo.bux\f[R].
+Like the \f[B].aux\f[R] files, \f[B].bux\f[R] files should contain only
+\f[B]\[at]$\f[R] specifications.
+.PP
+The meaning specified by \f[B]\[at]$\&...\[at]>\f[R] generally has four
+components: an identifier (followed by space), a program name (enclosed
+in braces), a section number (followed by space), and a TeX\ part.
+.PP
+A special \f[I]proofmode\f[R] is provided so that you can check
+\f[B]ctwill\f[R]\[cq]s conclusions about cross-references.
+Run \f[B]ctwill\f[R] with the flag \f[B]+P\f[R], and TeX will produce a
+specially formatted document (\f[I]without\f[R] mini-indexes) in which
+you can check that your specifications are correct.
+.PP
+More details how to use \f[B]ctwill\f[R] can be found in the first
+sections of its source code, respectively the change file
+\f[B]cweav-twill.ch\f[R] applicable to the \f[B]cweave.w\f[R] source.
+.SH DIFFERENCES TO ORIGINAL CTWILL
+.PP
+The present incarnation of \f[B]ctwill\f[R] and its utilities tries hard
+to be a drop-in replacement for the original package.
+There are, however, a few differences worth noting:
+.IP \[bu] 2
+This version is based on the most recent version of CWEB (3.64c).
+.IP \[bu] 2
+In TeX\ Live the utility programs are prefixed with \f[B]ctwill-\f[R]
+and the macro files with \f[B]ct\f[R] for technical reasons.
+.IP \[bu] 2
+Options \f[B]--help\f[R], \f[B]--quiet\f[R], \f[B]--verbose\f[R],
+\f[B]--version\f[R], and flags \f[B]-i\f[R], \f[B]-o\f[R], and
+\f[B]+lX\f[R] are new in CWEBbin and TeX\ Live.
+.IP \[bu] 2
+Option \f[B]+lX\f[R] is accompanied by example wrapper files for
+\f[B]ctwimac.tex\f[R] and \f[B]ctproofmac.tex\f[R] with translated
+captions for German (\f[B]+ld\f[R]).
+.IP \[bu] 2
+\f[B]ctwill\f[R] in TeX\ Live operates silently by default; use the
+\f[B]--verbose\f[R] option to get the original behavior.
+.IP \[bu] 2
+File lookup with the environment variable CWEBINPUTS is extended to
+permit several, colon-separated, paths.
+.IP \[bu] 2
+If properly configured, the main program \f[B]ctwill\f[R] is localized
+with the \[lq]GNU gettext utilities\[rq].
+.SH OPTIONS
+.PP
+Options on the command line may be either turned off with `\f[B]-\f[R]'
+(if they are on by default) or turned on with `\f[B]+\f[R]' (if they are
+off by default).
+In fact, the options are processed from left to right, so a sequence
+like \f[B]--verbose -h\f[R] will only show the \f[B]banner line\f[R]
+(\f[B]+b\f[R]) and the \f[B]progress report\f[R] (\f[B]+p\f[R]), but
+leave out the \f[B]happy message\f[R] (\f[B]-h\f[R]).
+.IP \[bu] 2
+\f[B]+b\f[R]: print banner line on terminal
+.IP \[bu] 2
+\f[B]+h\f[R]: print success message on completion
+.IP \[bu] 2
+\f[B]+p\f[R]: print progress report messages
+.IP \[bu] 2
+\f[B]+q\f[R]/\f[B]-q\f[R]: shortcut for \f[B]-bhp\f[R]; also
+\f[B]--quiet\f[R] (default)
+.IP \[bu] 2
+\f[B]+v\f[R]/\f[B]-v\f[R]: shortcut for \f[B]+bhp\f[R]; also
+\f[B]--verbose\f[R]
+.IP \[bu] 2
+\f[B]-e\f[R]: do not enclose C/C++\ material in \f[B]\f[R]
+.IP \[bu] 2
+\f[B]-f\f[R]: do not force a newline after every C/C++\ statement in
+output
+.IP \[bu] 2
+\f[B]-i\f[R]: suppress indentation of parameter declarations
+.IP \[bu] 2
+\f[B]-o\f[R]: suppress separation of declarations and statements
+.IP \[bu] 2
+\f[B]-x\f[R]: omit indices, section names, table of contents
+.IP \[bu] 2
+\f[B]+P\f[R]: \f[B]\[rs]input ctproofmac.tex\f[R] instead of
+\f[B]ctwimac.tex\f[R]
+.IP \[bu] 2
+\f[B]+lX\f[R]/\f[B]-lX\f[R]: use macros for language \f[I]X\f[R] as of
+\f[I]X\f[R]{\f[B]ctwimac\f[R]|\f[B]ctproofmac\f[R]}\f[B].tex\f[R]
+.IP \[bu] 2
+\f[B]+s\f[R]: print usage statistics
+.IP \[bu] 2
+\f[B]--help\f[R]: display help message and exit
+.IP \[bu] 2
+\f[B]--version\f[R]: output version information and exit
+.SH ENVIRONMENT
+.PP
+The environment variable CWEBINPUTS is used to search for the input
+files, or the system default if CWEBINPUTS is not set.
+See tex(1) for the details of the searching.
+.PP
+If prepared for NLS support, \f[B]ctwill\f[R] like \f[B]ctangle\f[R] and
+\f[B]cweave\f[R] uses the environment variable TEXMFLOCALEDIR to
+configure the parent directory where the \[lq]GNU gettext utilities\[rq]
+search for translation catalogs.
+.PP
+These variables are preconfigured in TeX\ Live\[cq]s
+\f[B]texmf.cnf\f[R].
+.SH FILES
+.PP
+The location of the files mentioned below varies from system to system.
+Use the \f[B]kpsewhich\f[R] utility to find their locations.
+.IP \[bu] 2
+\f[B]ctwimac.tex\f[R]: The default TeX\ macros \f[B]\[rs]input\f[R] in
+the first line of the output file.
+.IP \[bu] 2
+\f[B]ctproofmac.tex\f[R]: If \f[B]ctwill\f[R] is invoked with the
+\f[B]+P\f[R] option, it will change the first line of the output file to
+\f[B]\[rs]input ctproofmac.tex\f[R].
+.PP
+In both cases you can request some prefix \f[I]X\f[R] with the
+\f[B]+lX\f[R] option, e.g., \f[B]+ld\f[R] will \f[B]\[rs]input
+dctwimac.tex\f[R] and \f[B]+Pld\f[R] will \f[B]\[rs]input
+dctproofmac.tex\f[R].
+.IP \[bu] 2
+\f[I]webfile\f[R]\f[B].bux\f[R]: Reference definitions to resolve from
+other modules.
+.IP \[bu] 2
+\f[B]system.bux\f[R]: Reference definitions to resolve from
+C/C++\ standard library header files like \f[B]<stdio.h>\f[R].
+.PP
+Other \f[B]aux\f[R]iliary files with references are created
+automatically by \f[B]ctwill\f[R] and the actual index files are created
+by TeX.
+.IP \[bu] 2
+\f[B]cwebman.tex\f[R]: The CWEB user manual, available in PDF from
+CTAN (https://ctan.org/pkg/cweb).
+.SH SEE ALSO
+.IP \[bu] 2
+The CWEB System of Structured Documentation: by Donald E.\ Knuth and
+Silvio Levy (hardcopy version of \f[B]cwebman.tex\f[R] and the source
+code listings of \f[B]common.w\f[R], \f[B]ctangle.w\f[R], and
+\f[B]cweave.w\f[R]).
+.IP \[bu] 2
+Literate Programming: by D.\ E.\ Knuth.
+.IP \[bu] 2
+Weaving a Program: by Wayne Sewell.
+.PP
+cweb(1), tex(1), cc(1)
+.SH AUTHORS
+.PP
+Don Knuth wrote \f[B]ctwill\f[R] based on \f[B]cweave\f[R] by Silvio
+Levy and Knuth.
+.PD 0
+.P
+.PD
+As of 2019, \f[B]ctwill\f[R] and its utilities \f[B]ctwill-refsort\f[R] and
+\f[B]ctwill-twinx\f[R] have been fully integrated with the extended CWEBbin
+system that serves as the basis for CWEB in TeX\ Live; see the project
+page (https://github.com/ascherer/cwebbin).