


NOWEB(1)                                                 NOWEB(1)


NNAAMMEE
       notangle, noweave, nountangle - noweb, a literate-program-
       ming tool

SSYYNNOOPPSSIISS
       nnoottaannggllee [--RRrootname ...] [--ffiilltteerr  command]  [--LL[format]]
       [file] ...
       nnoouunnttaannggllee  [--mmll|--mm33|--cc|--cc++++|--aawwkk|--tteexx|--ff7777|--ff9900] [--RRroot-
       name ...] [--ffiilltteerr command] [--wwwidth] [file] ...
       nnoowweeaavvee [options] [file] ...

DDEESSCCRRIIPPTTIIOONN
       _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.

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  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 \\cchhaapptteerr and \\sseeccttiioonn..

       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 concatenates their definitions to produce a
       single chunk, just as does _t_a_n_g_l_e(1).  Code chunk  defini-
       tions are like macro definitions; _n_o_t_a_n_g_l_e extracts a pro-
       gram 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 indenta-
       tion of expanded chunks with  respect  to  the  chunks  in



                         local 2/16/1998                        1





NOWEB(1)                                                 NOWEB(1)


       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, [[[[aa[[ii]]]]]] 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.

       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. @@<<<<).

       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.

       Any  line beginning with `@@ ' terminates a code chunk, but
       if the line has the form
       @@ %%ddeeff _i_d_e_n_t_i_f_i_e_r_s
       it is taken to mean that the preceding chunk  defines  the
       identifiers  listed  in  _i_d_e_n_t_i_f_i_e_r_s.   This list contains
       identifiers separated by whitespace; any sequence of  non-
       white  characters may be an identifier.  _n_o_w_e_b uses a sim-
       ple heuristic to avoid recognizing  identifiers  that  are
       substrings of other identifiers.

TTAANNGGLLIINNGG
       _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:

       --RR_n_a_m_e Expand  the <<<<_n_a_m_e>>>> code chunk.  The --RR option can
              be repeated, in which case each chunk is written to
              the  output.   If no --RR option is given, expand the
              chunk named  <<<<*>>>>.

       --LL_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, %%FF  indicates
              the  name of the source file, %%LL indicates the line
              number of the source file, %%NN indicates a  newline,
              and  %%%% indicates a percent sign.  A sign and digit
              may be inserted between the percent  sign  and  the
              `LL', in which case the line number will be adjusted
              by that amount.  If _f_o_r_m_a_t is omitted, the  default



                         local 2/16/1998                        2





NOWEB(1)                                                 NOWEB(1)


              format  is  that  accepted  by  the C preprocessor:
              `##lliinnee %%LL ""%%FF""%%NN'.  When using the --LL_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              --LL''##lliinnee %%LL ""%%FF""%%NN''
                 Sun FORTRAN    --LL''\\## %%LL ""%%FF""%%NN''
                 Icon           --LL''##lliinnee %%--11LL ""%%FF""%%NN''
                 Modula-3       --LL''<<**LLIINNEE %%LL ""%%FF"" **>>%%NN''
                 SML/NJ         --LL''((**##lliinnee %%LL ""%%FF""**))''

              To  solve  the  converse  problem,  that is, to get
              noweb to do something sensible with  ##lliinnee  in  its
              input,  see  the  sshhaarrpplliinnee  filter in the examples
              directory.

       --tt_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.

       --ffiilltteerr _c_m_d
              Filter  the _n_o_w_e_b source through _c_m_d after convert-
              ing 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 PPAATTHH, then in
              ||LLIIBBDDIIRR||.  Such filters can be used to add features
              to _n_o_t_a_n_g_l_e; for an example see ||LLIIBBDDIIRR||//eemmppttyyddeeffnn.
              For experts only.

       --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.

       --aawwkk || --cc || --iiccnn || --iiccoonn || --mmll || --mm33 || --ppaassccaall || --ff7777  ||
              --ff9900  || --tteexx
              When  _n_o_u_n_t_a_n_g_l_e  transforms  documentation  chunks
              into  comments,  use the comment format of the lan-
              guage named.  --cc is the default.  _n_o_t_a_n_g_l_e  ignores
              these options.

       --ww_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.

WWEEAAVVIINNGG
       Output  from  _n_o_w_e_a_v_e  can  be  used in _T_e_X documents that
       \\iinnppuutt nnwwmmaacc,, in _L_a_T_e_X documents that  use the nnoowweebb pack-
       age  (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



                         local 2/16/1998                        3





NOWEB(1)                                                 NOWEB(1)


       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
       terminates 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 numbers 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.

       --llaatteexx Emit LaTeX, including wrapper in aarrttiiccllee style with
              the nnoowweebb package and page style. (Default)

       --tteexx   Emit   plain  TeX,  including  wrapper  with  nnwwmmaacc
              macros.

       --hhttmmll  Emit HTML, using HTML wrapper.  The output is unin-
              teresting  without  --iinnddeexx  or --xx.  The tags <<nnoowwee--
              bbcchhuunnkkss>> and <<nnoowweebbiinnddeexx>>, on lines by  themselves,
              produce  a  list  of chunks and an index of identi-
              fiers, respectively.  If these tags  are  not  pre-
              sent,  the  list and index are placed at the end of
              the file.

       --llaatteexx++hhttmmll
              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 --nn.  _U_s_e _o_f _t_h_i_s  _o_p_t_i_o_n  _i_s  ddeepprreeccaatteedd;;  use
              --hhttmmll with --ffiilltteerr ll22hh instead.

       --ttrrooffff 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 --ttrrooffff to Aharon Robbins <<aarrnnoolldd@@ggnnuu..oorrgg>>..

       --nn     Don't  use  any  wrapper (header or trailer).  This
              option is useful when _n_o_w_e_a_v_e's output  will  be  a
              part of a larger document.  See also --ddeellaayy..





                         local 2/16/1998                        4





NOWEB(1)                                                 NOWEB(1)


       --ffiilltteerr _c_m_d
              Filters the _n_o_w_e_b source through _c_m_d after convert-
              ing 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 PPAATTHH,,
              then in ||LLIIBBDDIIRR||..  Such filters can be used to  add
              features  to  _n_o_w_e_a_v_e_;  for  an  example, see ||LLIIBB--
              DDIIRR||//nnooxxrreeff..kkrroomm..  _N_o_w_e_a_v_e supports up to four fil-
              ters; one can get more by shell trickery, for exam-
              ple, --ffiilltteerr ""iiccoonn..ffiilltteerr || nnooiiddxx"".  The --aauuttooddeeffss,
              --xx,  --iinnddeexx, and --iinnddeexxffrroomm options are implemented
              as filters.  Filters are executed with the  shell's
              eevvaall  command, so _c_m_d should be quoted accordingly.

       --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.

       --ooppttiioonn _o_p_t
              Adds \\nnoowweebbooppttiioonnss{{_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 --llaatteexx option, but  --ooppttiioonn  lloonnggxxrreeff
              works black magic with --hhttmmll..

       --ddeellaayy By default, _n_o_w_e_a_v_e puts file-name and other infor-
              mation into the output before the  first  chunk  of
              the  program.  --ddeellaayy delays that information until
              after the first documentation chunk, making  act  a
              little  bit  like the _W_E_B ``limbo.''  The option is
              typically used to enable a user to put  a  special-
              ized  _L_a_T_e_X \\ddooccuummeennttccllaassss command and other pream-
              ble material  in  the  first  documentation  chunk.
              This  option also forces trailing cross-referencing
              information to be emitted  just  before  the  final
              chunk,  instead  of at the end of the document; the
              final chunk is expected to contain  \\eenndd{{ddooccuummeenntt}}..
              The --ddeellaayy option implies the --nn option.

       --tt_k    Expand  tabs  with stops every _k columns.  (Default
              is to expand every 8 columns.)

       --tt     Copy tabs to the output.

       --vv     Print the pipeline and RCS info on standard  error.

IINNDDEEXXIINNGG AANNDD CCRROOSSSS--RREEFFEERREENNCCEE
       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 defini-
       tions may be marked by hand using @@ %%ddeeff, or for some lan-
       guages they may be found automatically using the --aauuttooddeeffss
       option.  This section describes the  indexing  and  cross-



                         local 2/16/1998                        5





NOWEB(1)                                                 NOWEB(1)


       reference options; it might well be skipped on first read-
       ing.

       --xx     For _L_a_T_e_X_, add a page number  to  each  chunk  name
              identifying  the  location  of that chunk's defini-
              tion, and emit cross-reference information relating
              definitions  and  uses.  For _H_T_M_L_, create hypertext
              links between uses and definitions of chunks.  When
              nnoowweeaavvee --xx is used with _L_a_T_e_X_, the control sequence
              \\nnoowweebbcchhuunnkkss expands to a sorted list of  all  code
              chunks.

       --iinnddeexx Build  cross-reference  information  (or  hypertext
              links) for identifiers defined by
              @@ %%ddeeff _i_d_e_n_t_i_f_i_e_r_s
              Definitions  are  those  found  in   input   files.
              Requires _L_a_T_e_X or _H_T_M_L_.  --iinnddeexx implies --xx;; includ-
              ing  both  will  generate  strange-looking  output.
              _n_o_w_e_a_v_e does not generate cross-references to iden-
              tifiers that appear in quoted code (@@[[[[...@@]]]]), but
              it  does  generate  hypertext  links.  When nnoowweeaavvee
              --iinnddeexx is used with  _L_a_T_e_X_,  the  control  sequence
              \\nnoowweebbiinnddeexx expands to an index of identifiers.

       --iinnddeexxffrroomm _i_n_d_e_x
              Like  --iinnddeexx,, but the identifiers to be indexed are
              taken from file _i_n_d_e_x.  See _n_o_i_n_d_e_x_(_1_)_.

       --aauuttooddeeffss _l_a_n_g
              Discover  identifier   definitions   automatically.
              Code in chunks must be in language _l_a_n_g.  Permissi-
              ble _l_a_n_gs vary but may include tteexx or  iiccoonn..   Use-
              less without --iinnddeexx,, which it must precede.

       --sshhoowwaauuttooddeeffss
              Show values of _l_a_n_g usable with --aauuttooddeeffss.

EERRRROORR MMEESSSSAAGGEESS
       If _n_o_t_a_n_g_l_e or _n_o_w_e_a_v_e encounters a chunk name within doc-
       umentation, it assumes that this indicates an error,  usu-
       ally  misspelling  ``<<name>>=''.   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.

EEXXAAMMPPLLEESS
       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 ffoooo..nnww file with a C program in chunk
       <<<<ffoooo..cc>>>> and a header file in chunk <<<<ffoooo..hh>>>>,  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.




                         local 2/16/1998                        6





NOWEB(1)                                                 NOWEB(1)


       To rebuild your C source, try
              nnoottaannggllee --LL --RRffoooo..cc ffoooo..nnww >> ffoooo..cc
       To rebuild your header file, try
              nnoottaannggllee --RRffoooo..hh ffoooo..nnww || ccppiiff ffoooo..hh
       There are two compromises here.  Omitting --LL  keeps  ##lliinnee
       out  of your header file, and using ccppiiff prevents the com-
       mand  from  rewriting  ffoooo..hh  unless  the  contents   have
       changed.   Thus,  this  is  good code to put in a Makefile
       rule.

       To build a printed document, run
              nnoowweeaavvee --aauuttooddeeffss cc --iinnddeexx ffoooo..nnww >> ffoooo..tteexx
       If you have your own preamble,  containing  \\ddooccuummeennttccllaassss
       and all, you will also need the --ddeellaayy option.

       To build a web page, run
              nnoowweeaavvee --ffiilltteerr ll22hh --aauuttooddeeffss cc --iinnddeexx --hhttmmll ffoooo..nnww
              || hhttmmllttoocc >> ffoooo..hhttmmll
       Have fun!

FFIILLEESS
       |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_)

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

BBUUGGSS
       _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 definitions 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.

       _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
       nnoowweeaavvee  to  fail to translate braces correctly.  GNU _g_a_w_k
       is reported to work.

       DEC _s_h has a bug that causes the --ffiilltteerr  option  to  fail
       whenever the filter command contains more than one word.

       The  default  _L_a_T_e_X  pagestyles don't set the width of the



                         local 2/16/1998                        7





NOWEB(1)                                                 NOWEB(1)


       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.

       _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.

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

AAUUTTHHOORR
       Norman  Ramsey,  University of Virginia.  Internet address
       nnrr@@ccss..vviirrggiinniiaa..eedduu.
       Noweb home page at hhttttpp::////wwwwww..ccss..vviirrggiinniiaa..eedduu//~~nnrr//nnoowweebb.







































                         local 2/16/1998                        8


