From 342f4c70c13251fa670faa123091c128ec8bfdda Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 28 Feb 2019 19:09:21 +0000 Subject: tl19 man page update git-svn-id: svn://tug.org/texlive/trunk@50169 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/cweb.1 | 300 ++++++++++++++++++---------------- 1 file changed, 159 insertions(+), 141 deletions(-) (limited to 'Master/texmf-dist/doc/man/man1/cweb.1') diff --git a/Master/texmf-dist/doc/man/man1/cweb.1 b/Master/texmf-dist/doc/man/man1/cweb.1 index 20df712a52a..d230e49618d 100644 --- a/Master/texmf-dist/doc/man/man1/cweb.1 +++ b/Master/texmf-dist/doc/man/man1/cweb.1 @@ -1,152 +1,170 @@ -.TH CWEB 1 "7 April 2010" "Web2C 2018" -.\"===================================================================== +.\" Automatically generated by Pandoc 2.6 +.\" +.TH "CWEB" "1" "January 27, 2019" "Web2c 2019" "General Commands Manual" +.hy .SH NAME -ctangle, cweave \- translate CWEB to C and/or TeX -.\"===================================================================== +.PP +ctangle, cweave \[en] translate CWEB to TeX .SH SYNOPSIS -.na -.B ctangle -.RB [ \-bhp ] -.RB [ +s ] -.IR webfile [ \fB.w\fP ] -.RI [{ changefile [ \fB.ch\fP ]| \fB\-\fP } -.RI [ outfile [ \fB.c\fP ]]] -.br -.B cweave -.RB [ \-befhpx ] -.RB [ +s ] -.IR webfile [ \fB.w\fP ] -.RI [{ changefile [ \fB.ch\fP ]| \fB\-\fP } -.RI [ outfile [ \fB.tex\fP ]]] -.ad -.\"===================================================================== +.PP +\f[B]ctangle\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w] +[{\f[I]changefile\f[R][.ch]|-} [\f[I]outfile\f[R][.c]]] +.PD 0 +.P +.PD +\f[B]cweave\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]]] .SH DESCRIPTION -The -.B ctangle -program converts a CWEB -source document into a C\ program that may be compiled in the usual way. -The output file includes #line specifications so that debugging can be -done in terms of the CWEB source file. -.PP -The -.B cweave -program converts the same CWEB file 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, italics, boldface, 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\ 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. +.PP +The \f[B]ctangle\f[R] program converts a CWEB source document into a +C/C++\ program that may be compiled in the usual way. +The output file includes \f[B]#line\f[R] specifications so that +debugging can be done in terms of the CWEB source file. +.PP +The \f[B]cweave\f[R] program converts the same CWEB file 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 file (and -.B .w -is added if there is no extension). -If that file cannot be opened, the extension -.B .web -is tried instead. (But -.B .w -is recommended, since -.B .web -usually implies Pascal.) -If there is a second name, it is a change file (and -.B .ch -is added if there is no extension). -The change file overrides parts of the WEB 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 -.B .c -or -.BR .tex . -.PP -Options in the command line may be either turned off with\ \- -(if they are on by default) or turned on with\ + (if they are off by -default). -In fact, the options are processed from left to right, -so a sequence like -f\ +f corresponds to +f (which is the default). -.PP -The -.B \-b -option suppresses the banner line that normally appears on your terminal -when ctangle or cweave begins. -The -.B \-h -option suppresses the happy message that normally appears if the processing -was successful. -The -.B \-p -option suppresses progress reports (starred module numbers) as the processing -takes place. -If you say -.BR \-bhp , -you get nothing but error messages. -.PP -The -.B +s -option prints statistics about memory usage at the end of a run -(assuming that the programs have been compiled with the -DSTAT switch). -.PP -There are three other options applicable to -.B cweave -only: -.B \-f -means do not force a newline after every statement in the formatted output. -.B \-e -inhibits the enclosure of C\ material formatted by -.I cweave -in brackets -\ePB{.\|.\|.}. -Such brackets are normally inserted so that special hooks -can be used by -.I cweb-latex -and similar programs. -.B \-x -means omit the index and table of contents. -.\"===================================================================== +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. +.SH DIFFERENCES TO ORIGINAL CWEB +.PP +CWEBbin tries hard to be a drop-in replacement for CWEB, so in general +you should not notice any differences in invoking the programs nor in +the resulting output. +There are, however, a few differences worth noting: +.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 several wrapper files for +\f[B]cwebmac.tex\f[R] with translated captions for German +(\f[B]+ld\f[R]), French (\f[B]+lf\f[R]), and Italian (\f[B]+li\f[R]). +.IP \[bu] 2 +CWEB in TeX\ Live operates silently by default (as of 2019); 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 programs \f[B]ctangle\f[R] and +\f[B]cweave\f[R] are 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]). +.PP +The first batch of options are common to both \f[B]ctangle\f[R] and +\f[B]cweave\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]+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 +.PP +There are six other options applicable to \f[B]cweave\f[R] only: +.IP \[bu] 2 +\f[B]-e\f[R]: do not enclose C/C++\ material in \f[B]\[rs]PB{\&...}\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]+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]cwebmac.tex\f[R] .SH ENVIRONMENT -The environment variable CWEBINPUTS is used to search for the input files, -or the system default if CWEBINPUTS is not set. See -.BR tex (1) -for the details of the searching. -.\"===================================================================== +.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]ctangle\f[R] and \f[B]cweave\f[R] use +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 -The location of the files mentioned below varies from system to -system. Use the -.B kpsewhich -utility to find their locations. -.TP -.I cwebmac.tex -TeX macros used by cweave output. -.TP -.I cwebman.tex -The user manual. -.\"===================================================================== -.SH "SEE ALSO" -.TP -.I Literate Programming -by D. E. Knuth. -.TP -.I Weaving a Program -by Wayne Sewell. -.TP -.I The CWEB System of Structured Documentation -by Donald E. Knuth and Silvio Levy (hardcopy version of cwebman.tex -and the source code listings). -.PP -.BR tex (1), -.BR cc (1). -.\"===================================================================== +.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]cwebmac.tex\f[R]: The default TeX\ macros \f[B]\[rs]input\f[R] in +the first line of the \f[B]cweave\f[R] output file. +.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 WEB for TeX and Pascal. -Silvio Levy designed and developed CWEB -by adapting the WEB conventions to\ C and by recoding everything in CWEB. +.PD 0 +.P +.PD +Silvio Levy designed and developed CWEB by adapting the WEB conventions +to C and by recoding everything in CWEB. Knuth began using CWEB and made further refinements. Many other helpers are acknowledged in the CWEB manual. - +.PD 0 +.P +.PD +As of 2019, the CWEB system in TeX\ Live is based on the CWEBbin +extension that collects ideas and improvements from numerous +contributors; see the project +page (https://github.com/ascherer/cwebbin). -- cgit v1.2.3