NOWEB(1)                                                              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
       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 contains references to other chunks, which
       are themselves expanded, and so on.  _n_o_w_e_b's  output  is  readable;  it
       preserves 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.11b.

AAUUTTHHOORR
       Norman  Ramsey,  Harvard  University.   Internet  address  nnrr@@eeeeccss..hhaarr--
       vvaarrdd..eedduu.
       Noweb home page at hhttttpp::////wwwwww..eeeeccss..hhaarrvvaarrdd..eedduu//~~nnrr//nnoowweebb.




                                local 3/28/2001                       NOWEB(1)
