NOWEB(1) General Commands Manual NOWEB(1) NNAAMMEE notangle, noweave, nountangle - noweb, a literate-programming tool SSYYNNOOPPSSIISS nnoottaannggllee [--RRrootname ...] [--ffiilltteerr command] [--LL[format]] [file] ... nnoouunnttaannggllee [--mmll|--mm33|--cc|--cc++++|--aawwkk|--tteexx|--ff7777|--ff9900|--lliisspp|--mmaattllaabb] [--RRroot‐ name ...] [--ffiilltteerr command] [--wwwidth] [file] ... nnoowweeaavvee [options] [file] ... DDEESSCCRRIIPPTTIIOONN _N_o_w_e_b is a literate-programming tool like Knuth's _W_E_B_, only simpler. A _n_o_w_e_b file contains program source code interleaved with documentation. When _n_o_t_a_n_g_l_e is given a _n_o_w_e_b file, it writes the program on standard output. When _n_o_w_e_a_v_e is given a _n_o_w_e_b file, it reads the _n_o_w_e_b source and produces, on standard output, _L_a_T_e_X, _T_e_X, _t_r_o_f_f, or _H_T_M_L source for typeset documentation. _n_o_u_n_t_a_n_g_l_e converts a literate program into an ordinary program by turning interleaved documentation into comments. The file name `-' refers to standard input. FFOORRMMAATT OOFF NNOOWWEEBB FFIILLEESS A _n_o_w_e_b file is a sequence of _c_h_u_n_k_s, which may appear in any order. A chunk may contain code or documentation. Documentation chunks begin with a line that starts with an at sign (@) followed by a space or new‐ line. They have no names. Code chunks begin with <<_c_h_u_n_k _n_a_m_e>>= on a line by itself. The double left angle bracket (<<) must be in the first column. Chunks are terminated by the beginning of another chunk, or by end of file. If the first line in the file does not mark the beginning of a chunk, it is assumed to be the first line of a documen‐ tation chunk. Documentation chunks contain text that is ignored by _n_o_t_a_n_g_l_e and copied verbatim to standard output by _n_o_w_e_a_v_e (except for quoted code). _n_o_w_e_a_v_e can work with _L_a_T_e_X, plain _T_e_X, _t_r_o_f_f or _H_T_M_L. With plain _T_e_X, it inserts a reference to a _T_e_X macro package, _n_w_m_a_c, which defines commands like \\cchhaapptteerr and \\sseeccttiioonn.. Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; _n_o_t_a_n_g_l_e concate‐ nates their definitions to produce a single chunk, just as does _t_a_n_‐ _g_l_e(1). Code chunk definitions are like macro definitions; _n_o_t_a_n_g_l_e extracts a program by expanding one chunk (by default, the chunk named <<<<*>>>>). The definition of that chunk contains references to other chunks, which are themselves expanded, and so on. _n_o_t_a_n_g_l_e's output is readable; it preserves the indentation of expanded chunks with respect to the chunks in which they appear. Code may be quoted within documentation chunks by placing double square brackets ([[[[_._._.]]]]) around it. These double square brackets are ignored by _n_o_t_a_n_g_l_e_, but they may be used by _n_o_w_e_a_v_e to give the code special typographic treatment, e.g., hypertext links. If quoted code ends with three or more square brackets, _n_o_w_e_a_v_e chooses the rightmost pair, so that, for example, [[[[aa[[ii]]]]]] is parsed correctly. The names of code chunks may appear within quoted code unless that quoted code is itself part of the name of a code chunk. In code, noweb treats unpaired double left or right angle brackets as literal <<<< and >>>>. To force any such brackets, even paired brackets or brackets in documentation, to be treated as literal, use a preceding at sign (e.g. @@<<<<). Some programming or formatting languages may require a single @@ sign in the first column. Noweb users may achieve this effect by putting a doubled @@@@ in the first column; in this position only, it stands for a single @@ sign. TTAANNGGLLIINNGG _n_o_t_a_n_g_l_e and _n_o_u_n_t_a_n_g_l_e accept the same set of options, although some options have effects only on one or the other. The options are: --RR_n_a_m_e Expand the <<<<_n_a_m_e>>>> code chunk. The --RR option can be repeated, in which case each chunk is written to the output. If no --RR option is given, expand the chunk named <<<<*>>>>. --LL_f_o_r_m_a_t Emit line number indications at chunk boundaries. A line number indication identifies the source of the line that follows it. In _f_o_r_m_a_t, %%FF indicates the name of the source file, %%LL indi‐ cates the line number of the source file, %%NN indicates a new‐ line, and %%%% indicates a percent sign. A sign and digit may be inserted between the percent sign and the `LL', in which case the line number will be adjusted by that amount. If _f_o_r_m_a_t is omit‐ ted, the default format is that accepted by the C preprocessor: `##lliinnee %%LL ""%%FF""%%NN'. When using the --LL_f_o_r_m_a_t option, _n_o_t_a_n_g_l_e ensures that all text appears in the same column in input and output. _n_o_u_n_t_a_n_g_l_e ignores this option. Common format strings include: C --LL''##lliinnee %%LL ""%%FF""%%NN'' Sun FORTRAN --LL''\\## %%LL ""%%FF""%%NN'' Icon --LL''##lliinnee %%--11LL ""%%FF""%%NN'' Modula-3 --LL''<<**LLIINNEE %%LL ""%%FF"" **>>%%NN'' SML/NJ --LL''((**##lliinnee %%LL ""%%FF""**))'' To solve the converse problem, that is, to get noweb to do some‐ thing sensible with ##lliinnee in its input, see the sshhaarrpplliinnee filter in the examples directory. --tt_k Copy tabs untouched from input to output, and use tabs for indentation, assuming stops every _k columns. By default, tabs are expanded to spaces with stops every 8 columns. --ffiilltteerr _c_m_d Filter the _n_o_w_e_b source through _c_m_d after converting it to tool form and before tangling. _n_o_t_a_n_g_l_e looks for _c_m_d first on the user's PPAATTHH, then in ||LLIIBBDDIIRR||. Such filters can be used to add features to _n_o_t_a_n_g_l_e; for an example see ||LLIIBBDDIIRR||//eemmppttyyddeeffnn. For experts only. --mmaarrkkuupp _p_a_r_s_e_r Use _p_a_r_s_e_r to parse the input file. Enables use of noweb tools on files in other formats; for example, the nnuummaarrkkuupp parser understands _n_u_w_e_b(1) format. See _n_o_w_e_b_f_i_l_t_e_r_s(7) for more information. For experts only. --aawwkk || --cc || --iiccnn || --iiccoonn || --mmll || --mm33 || --ppaassccaall || --ff7777 || --ff9900 || --tteexx When _n_o_u_n_t_a_n_g_l_e transforms documentation chunks into comments, use the comment format of the language named. --cc is the default. _n_o_t_a_n_g_l_e ignores these options. --ww_n When _n_o_u_n_t_a_n_g_l_e transforms documentation chunks into comments, create comments on lines of width _n. _n_o_t_a_n_g_l_e ignores this option. WWEEAAVVIINNGG Output from _n_o_w_e_a_v_e can be used in _T_e_X documents that \\iinnppuutt nnwwmmaacc,, in _L_a_T_e_X documents that use the nnoowweebb package (see _n_o_w_e_b_s_t_y_l_e_(_1_)), and in _H_T_M_L documents to be browsed with _M_o_s_a_i_c_(_1_)_. _N_o_w_e_a_v_e treats code chunks somewhat like _L_a_T_e_X _l_i_s_t _e_n_v_i_r_o_n_m_e_n_t_s_. If the ``@@ '' that ter‐ minates a code chunk is followed immediately by text, that text follows the code chunk without a paragraph break. If the rest of the line is blank, _n_o_w_e_a_v_e puts _T_e_X into ``vertical mode,'' and later text starts a fresh, indented paragraph. No page breaks occur in the middle of code chunks unless necessary to avoid an overfull vbox. The documentation chunk immediately preceding a code chunk appears on the same page as that code chunk unless doing so would violate the previous rule. _N_o_w_e_a_v_e inserts no extra newlines in its _T_e_X output, so the line num‐ bers given in _T_e_X error messages are the same as those in the input file. _n_o_w_e_a_v_e has options that dictate choice of formatter and that support different formatting idioms and tools. Basic options are described here; options related to index and cross-reference information are described in the INDEXING AND CROSS-REFERENCE section. --llaatteexx Emit LaTeX, including wrapper in aarrttiiccllee style with the nnoowweebb package and page style. (Default) --tteexx Emit plain TeX, including wrapper with nnwwmmaacc macros. --hhttmmll Emit HTML, using HTML wrapper. The output is uninteresting without --iinnddeexx or --xx. The tags <> and <>, on lines by themselves, produce a list of chunks and an index of identifiers, respectively. If these tags are not present, the list and index are placed at the end of the file. --llaatteexx++hhttmmll Assume documentation chunks are LaTeX, but generate HTML for code chunks, suitably marked so conversion with _l_a_t_e_x_2_h_t_m_l_(_1_) yields reasonable output. A LaTeX wrapper is implied, but can be turned off with --nn. _U_s_e _o_f _t_h_i_s _o_p_t_i_o_n _i_s ddeepprreeccaatteedd;; use --hhttmmll with --ffiilltteerr ll22hh instead. --ttrrooffff Emit _t_r_o_f_f(1) markup (with no wrapper). The result should be processed with _n_o_r_o_f_f(1). Bug reports for --ttrrooffff to Arnold Rob‐ bins <>.. --nn Don't use any wrapper (header or trailer). This option is use‐ ful when _n_o_w_e_a_v_e's output will be a part of a larger document. See also --ddeellaayy.. --ffiilltteerr _c_m_d Filters the _n_o_w_e_b source through _c_m_d after converting it to tool form and before converting to _T_e_X_. _n_o_w_e_a_v_e looks for _c_m_d first on the user's PPAATTHH,, then in ||LLIIBBDDIIRR||.. Such filters can be used to add features to _n_o_w_e_a_v_e_; for an example, see ||LLIIBB‐‐ DDIIRR||//nnooxxrreeff..kkrroomm.. _N_o_w_e_a_v_e supports up to four filters; one can get more by shell trickery, for example, --ffiilltteerr ""iiccoonn..ffiilltteerr || nnooiiddxx"". The --aauuttooddeeffss, --xx, --iinnddeexx, and --iinnddeexxffrroomm options are implemented as filters. Filters are executed with the shell's eevvaall command, so _c_m_d should be quoted accordingly. --mmaarrkkuupp _p_a_r_s_e_r Use _p_a_r_s_e_r to parse the input file. Enables use of noweb tools on files in other formats; for example, the nnuummaarrkkuupp parser understands _n_u_w_e_b(1) format. See _n_o_w_e_b_f_i_l_t_e_r_s(7) for more information. For experts only. --ooppttiioonn _o_p_t Adds \\nnoowweebbooppttiioonnss{{_o_p_t}} to the _L_a_T_e_X header. See _n_o_w_e_b_s_t_y_l_e_(_1_) for values of _o_p_t_. Normally useful only with the --llaatteexx option, but --ooppttiioonn lloonnggxxrreeff works black magic with --hhttmmll.. --ddeellaayy By default, _n_o_w_e_a_v_e puts file-name and other information into the output before the first chunk of the program. --ddeellaayy delays that information until after the first documentation chunk, mak‐ ing act a little bit like the _W_E_B ``limbo.'' The option is typ‐ ically used to enable a user to put a specialized _L_a_T_e_X \\ddooccuu‐‐ mmeennttccllaassss command and other preamble material in the first docu‐ mentation chunk (i.e., _b_e_f_o_r_e the first @ sign). This option also forces trailing cross-referencing information to be emitted just before the final chunk, instead of at the end of the docu‐ ment; the final chunk is expected to contain \\eenndd{{ddooccuummeenntt}}.. The --ddeellaayy option implies the --nn option. --tt_k Expand tabs with stops every _k columns. (Default is to expand every 8 columns.) --tt Copy tabs to the output. --vv Print the pipeline and RCS info on standard error. IINNDDEEXXIINNGG AANNDD CCRROOSSSS--RREEFFEERREENNCCEE When used with _L_a_T_e_X, _t_r_o_f_f, or _H_T_M_L_, _n_o_w_e_a_v_e can provide indexing and cross-reference information for chunks and for programming-language identifiers. Identifier definitions may be marked by hand using back‐ ticks (`); the --ffiilltteerr bbttddeeffnn option recognizes these markings. For some languages, definitions may be found automatically using the --aauuttooddeeffss option. This section describes the indexing and cross-refer‐ ence options; it might well be skipped on first reading. --xx For _L_a_T_e_X_, add a page number to each chunk name identifying the location of that chunk's definition, and emit cross-reference information relating definitions and uses. For _H_T_M_L_, create hypertext links between uses and definitions of chunks. When nnoowweeaavvee --xx is used with _L_a_T_e_X_, the control sequence \\nnoowweebbcchhuunnkkss expands to a sorted list of all code chunks. --iinnddeexx Build cross-reference information (or hypertext links) for defined identifiers. Definitions are those found in the input files by --aauuttooddeeffss _l_a_n_g_u_a_g_e or by --ffiilltteerrbtdefn. Requires _L_a_T_e_X or _H_T_M_L_. --iinnddeexx implies --xx;; including both will generate strange-looking output. _n_o_w_e_a_v_e does not generate cross-refer‐ ences to identifiers that appear in quoted code (@@[[[[...@@]]]]), but it does generate hypertext links. When nnoowweeaavvee --iinnddeexx is used with _L_a_T_e_X_, the control sequence \\nnoowweebbiinnddeexx expands to an index of identifiers. --iinnddeexxffrroomm _i_n_d_e_x Like --iinnddeexx,, but the identifiers to be indexed are taken from file _i_n_d_e_x. See _n_o_i_n_d_e_x_(_1_)_. --aauuttooddeeffss _l_a_n_g Discover identifier definitions automatically. Code in chunks must be in language _l_a_n_g. Permissible _l_a_n_gs vary but may include tteexx or iiccoonn.. Useless without --iinnddeexx,, which it must pre‐ cede. --sshhoowwaauuttooddeeffss Show values of _l_a_n_g usable with --aauuttooddeeffss. EERRRROORR MMEESSSSAAGGEESS If _n_o_t_a_n_g_l_e or _n_o_w_e_a_v_e encounters a chunk name within documentation, it assumes that this indicates an error, usually misspelling ``<>=''. Other error messages should be self-explanatory. It is incorrect to refer to a chunk that is never defined, but it is OK for chunks to be defined and not used. EEXXAAMMPPLLEESS If you have trouble digesting this man page, you're not alone. Here are a few examples to get you started. I'll assume you have a ffoooo..nnww file with a C program in chunk <<<>>> and a header file in chunk <<<>>>, and that your documentation is marked up using _l_a_t_e_x_(_1_). I'll show you how to build things using the most common options. To rebuild your C source, try nnoottaannggllee --LL --RRffoooo..cc ffoooo..nnww >> ffoooo..cc To rebuild your header file, try nnoottaannggllee --RRffoooo..hh ffoooo..nnww || ccppiiff ffoooo..hh There are two compromises here. Omitting --LL keeps ##lliinnee out of your header file, and using ccppiiff prevents the command from rewriting ffoooo..hh unless the contents have changed. Thus, this is good code to put in a Makefile rule. To build a printed document, run nnoowweeaavvee --aauuttooddeeffss cc --iinnddeexx ffoooo..nnww >> ffoooo..tteexx If you have your own preamble, containing \\ddooccuummeennttccllaassss and all, you will also need the --ddeellaayy option. To build a web page, run nnoowweeaavvee --ffiilltteerr ll22hh --aauuttooddeeffss cc --iinnddeexx --hhttmmll ffoooo..nnww || hhttmmllttoocc >> ffoooo..hhttmmll Have fun! FFIILLEESS |LIBDIR|/markup markup preprocessor |LIBDIR|/unmarkup inverts markup |LIBDIR|/nt notangle proper |LIBDIR|/finduses find uses of identifiers for index |LIBDIR|/noidx generate index and cross-reference info |LIBDIR|/toroff back end to emit _t_r_o_f_f |LIBDIR|/totex back end to emit _T_e_X or _L_a_T_e_X |LIBDIR|/tohtml back end to emit HTML |TEXINPUTS|/nwmac.tex formatting _T_e_X macros |TEXINPUTS|/noweb.sty use in _L_a_T_e_X documents; see _n_o_w_e_b_s_t_y_l_e_(_7_) SSEEEE AALLSSOO _c_p_i_f(1), _n_o_d_e_f_s(1), _n_o_r_o_o_t_s(1), _n_o_w_e_b(1), _n_o_i_n_d_e_x(1), _n_o_r_o_f_f(1), _n_o_w_e_b_‐ _s_t_y_l_e(7), _n_o_w_e_b_f_i_l_t_e_r_s(7) BBUUGGSS _n_o_t_a_n_g_l_e and _n_o_u_n_t_a_n_g_l_e fail if names used on the command line contain single quotes. Ignoring unused chunks can cause problems; if a chunk has multiple def‐ initions and one is misspelled, the misspelled definition is silently ignored. _n_o_r_o_o_t_s(1) can be used to catch this mistake. The _-_L option of _n_o_t_a_n_g_l_e puts an implicit initial newline in the for‐ mat string. The default _L_a_T_e_X pagestyles don't set the width of the boxes contain‐ ing headers and footers. Since _n_o_w_e_b code paragraphs are extra wide, this _L_a_T_e_X bug sometimes results in extra-wide headers and footers. The remedy is to redefine the relevant ppss@@** commands; ppss@@nnoowweebb in nnoowweebb..ssttyy can be used as an example. _l_a_t_e_x_2_h_t_m_l(1) mangles some source files. _n_o_w_e_a_v_e has too many options, and this man page is too long. VVEERRSSIIOONN This man page is from _n_o_w_e_b version 2.12. AAUUTTHHOORR Norman Ramsey, Tufts University. Internet address NNoorrmmaann..RRaamm‐‐ sseeyy@@ttuuffttss..eedduu. Noweb home page at hhttttpp::////wwwwww..ccss..ttuuffttss..eedduu//~~nnrr//nnoowweebb. local 10/40/2008 NOWEB(1)