


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, or
       _H_T_M_L source for typeset  documentation.   _n_o_u_n_t_a_n_g_l_e  con-
       verts a literate program into an ordinary program by turn-
       ing 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,  or _H_T_M_L.  With plain _T_e_X, it inserts a refer-
       ence 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 4/17/97                         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  choose  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 instead of <<<<*>>>>.

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



                          local 4/17/97                         2





NOWEB(1)                                                 NOWEB(1)


              column  in  input  and  output.  _n_o_u_n_t_a_n_g_l_e ignores
              this option.

              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 some-
       what 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



                          local 4/17/97                         3





NOWEB(1)                                                 NOWEB(1)


       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 Phil Bewig <<ppbbeewwiigg@@nneettccoomm..ccoomm>>..

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

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



                          local 4/17/97                         4





NOWEB(1)                                                 NOWEB(1)


              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 or _H_T_M_L_, _n_o_w_e_a_v_e can provide indexing
       and  cross-reference  information  for chunks and for pro-
       gramming-language identifiers.  Identifier definitions may
       be marked by hand using @@ %%ddeeff, or for some languages they
       may be found automatically  using  the  --aauuttooddeeffss  option.
       This  section  describes  the indexing and cross-reference
       options; it might well be skipped on first reading.

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




                          local 4/17/97                         5





NOWEB(1)                                                 NOWEB(1)


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

       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



                          local 4/17/97                         6





NOWEB(1)                                                 NOWEB(1)


       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|/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_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
       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.8a.



                          local 4/17/97                         7





NOWEB(1)                                                 NOWEB(1)


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 4/17/97                         8


