


NOWEB(1)                                                 NOWEB(1)


NNAAMMEE
       noweb - a simple literate-programming tool

SSYYNNOOPPSSIISS
       nnoowweebb [--tt] [--oo] [--_r_m_a_t] [--mmaarrkkuupp _p_a_r_s_e_r] [file] ...

DDEESSCCRRIIPPTTIIOONN
       _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 simpler.  A _n_o_w_e_b file contains program source
       code   interleaved  with  documentation.   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.

FFOORRMMAATT OOFF NNOOWWEEBB FFIILLEESS
       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 newline.  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 documenta-
       tion 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 documentation chunk must  contain  a
       _L_a_T_e_X  \\ddooccuummeennttccllaassss  command,  it must contain \\uusseeppaacckk--
       aaggee{{nnoowweebb}} in the preamble, and finally it must also  con-
       tain a _L_a_T_e_X \\bbeeggiinn{{ddooccuummeenntt}} 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
       spaces,  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 con-
       tains 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,



                         local 3/28/2001                        1





NOWEB(1)                                                 NOWEB(1)


       _n_o_w_e_b includes line-number information as specified by the
       --LL_f_o_r_m_a_t option (or for C if no --LL_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  typo-
       graphic  treatment  in  the _T_e_X file.  If quoted code ends
       with three or more  square  brackets,  _n_o_w_e_b  chooses  the
       rightmost  pair,  so that, for example, [[[[aa[[ii]]]]]] is parsed
       correctly.

       If double left and right angle brackets  are  not  paired,
       they  are  treated  as literal <<<< and >>>>.  Users can force
       any such brackets, even paired brackets, to be treated  as
       literal by using a preceding at sign (e.g. @@<<<<).

OOPPTTIIOONNSS
       --tt     Suppress generation of a _T_e_X file.

       --oo     Suppress generation of output files.

       --LL_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);

       --mmaarrkkuupp _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 nnuummaarrkkuupp 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.

BBUUGGSS
       Ignoring unused chunks whose names  contain  spaces  some-
       times causes problems, especially in the case when a chunk
       has multiple definitions and one is misspelled;  the  mis-
       spelled  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 mis-
       take.

       _n_o_w_e_b  is  intended  for users who don't want the power or
       the complexity of command-line  options.   More  sophisti-
       cated  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 prob-
       lems  with  braces in _T_e_X output.  GNU _g_a_w_k is reported to
       work.




                         local 3/28/2001                        2





NOWEB(1)                                                 NOWEB(1)


       The default _L_a_T_e_X pagestyles don't set the  width  of  the
       boxes  containing  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  ppss@@**  commands;  ppss@@nnoowweebb  in
       nnoowweebb..ssttyy can be used as an example.

SSEEEE AALLSSOO
       _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.

VVEERRSSIIOONN
       This man page is from _n_o_w_e_b version 2.10a.

AAUUTTHHOORR
       Norman   Ramsey,  Harvard  University.   Internet  address
       nnrr@@eeeeccss..hhaarrvvaarrdd..eedduu.
       Noweb home page at  hhttttpp::////wwwwww..eeeeccss..hhaarrvvaarrdd..eedduu//~~nnrr//nnoowweebb.





































                         local 3/28/2001                        3


