NOWEB(1) General Commands Manual NOWEB(1) NNAAMMEE noweb - a simple literate-programming tool SSYYNNOOPPSSIISS nnoowweebb [--tt] [--oo] [--LL_f_o_r_m_a_t] [--mmaarrkkuupp _p_a_r_s_e_r] [file] ... DDEESSCCRRIIPPTTIIOONN _N_o_w_e_b is a literate-programming tool like _F_u_n_n_e_l_W_E_B or _n_u_w_e_b, only sim‐ pler. A _n_o_w_e_b file contains program source code interleaved with docu‐ mentation. When _n_o_w_e_b is invoked, it writes the program source code to the output files mentioned in the noweb file, and it writes a _T_e_X file for typeset documentation. The _n_o_w_e_b(1) command is for people who don't like reading man pages or who are switching from _n_u_w_e_b. To get the most out of _n_o_w_e_b, use _n_o_t_a_n_‐ _g_l_e(1) and _n_o_w_e_a_v_e(1) instead. 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 copied verbatim to the _T_e_X file (except for quoted code). _n_o_w_e_b works with _L_a_T_e_X; the first docu‐ mentation chunk must contain a _L_a_T_e_X \\ddooccuummeennttccllaassss command, it must contain \\uusseeppaacckkaaggee{{nnoowweebb}} in the preamble, and finally it must also contain a _L_a_T_e_X \\bbeeggiinn{{ddooccuummeenntt}} command. Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; _n_o_w_e_b concatenates their definitions to produce a single chunk, just as other literate- programming tools do. _n_o_w_e_b looks for chunks that are defined but not used in the source file. If the name of such a chunk contains no spa‐ ces, the chunk is an ``output file;'' _n_o_w_e_b expands it and writes the result onto the file of the same name. A code-chunk definition is like a macro definition; it contains references to other chunks, which are themselves expanded, and so on. _n_o_w_e_b's output is readable; it pre‐ serves the indentation of expanded chunks with respect to the chunks in which they appear. If a star (**) is appended to the name of an output file, _n_o_w_e_b includes line-number information as specified by the --LL_f_o_r_m_a_t option (or for C if no --LL_f_o_r_m_a_t option is given). The name itself may not contain shell metacharacters. Code may be quoted within documentation chunks by placing double square brackets ([[[[_._._.]]]]) around it. These double square brackets are used to give the code special typographic treatment in the _T_e_X file. If quoted code ends with three or more square brackets, _n_o_w_e_b chooses the right‐ most pair, so that, for example, [[[[aa[[ii]]]]]] is parsed correctly. 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. @@<<<<). OOPPTTIIOONNSS --tt Suppress generation of a _T_e_X file. --oo Suppress generation of output files. --LL_f_o_r_m_a_t Use _f_o_r_m_a_t to format line-number information for starred output files. (If the option is omitted, a format suitable for C is used.) _f_o_r_m_a_t is as defined by _n_o_t_a_n_g_l_e(1); --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. BBUUGGSS Ignoring unused chunks whose names contain spaces sometimes causes problems, especially in the case when a chunk has multiple definitions and one is misspelled; the misspelled definition will be silently ignored. _n_o_r_o_o_t_s(1) can be used as a sanity checker to catch this sort of mistake. _n_o_w_e_b is intended for users who don't want the power or the complexity of command-line options. More sophisticated users should avoid _n_o_w_e_b and use _n_o_w_e_a_v_e and _n_o_t_a_n_g_l_e instead. If the design were better, we could all use the same commands. _n_o_w_e_b requires the new version of _a_w_k, assumed to be called _n_a_w_k. DEC _n_a_w_k has a bug in that that causes problems with braces in _T_e_X output. GNU _g_a_w_k is reported to work. 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. SSEEEE AALLSSOO _n_o_t_a_n_g_l_e(1), _n_o_w_e_a_v_e(1), _n_o_r_o_o_t_s(1), _n_o_u_n_t_a_n_g_l_e(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), _n_u_w_e_b_2_n_o_w_e_b(1) Norman Ramsey, _L_i_t_e_r_a_t_e _p_r_o_g_r_a_m_m_i_n_g _s_i_m_p_l_i_f_i_e_d_, _I_E_E_E _S_o_f_t_w_a_r_e 11(5):97-105, September 1994. 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)