Provided by: noweb_2.11b-7.1ubuntu1_amd64 bug

NAME

       notangle, noweave, nountangle - noweb, a literate-programming tool

SYNOPSIS

       notangle [-Rrootname ...] [-filter command] [-L[format]] [file] ...
       nountangle  [-ml|-m3|-c|-c++|-awk|-tex|-f77|-f90|-lisp|-matlab]  [-Rrootname ...] [-filter
       command] [-wwidth] [file] ...
       noweave [options] [file] ...

DESCRIPTION

       Noweb is a literate-programming tool  like  Knuth's  WEB,  only  simpler.   A  noweb  file
       contains  program  source  code  interleaved with documentation.  When notangle is given a
       noweb file, it writes the program on standard output.  When noweave is given a noweb file,
       it  reads  the  noweb  source and produces, on standard output, LaTeX, TeX, troff, or HTML
       source for typeset documentation.  nountangle converts a literate program into an ordinary
       program  by  turning interleaved documentation into comments.  The file name `-' refers to
       standard input.

FORMAT OF NOWEB FILES

       A noweb file is a sequence of chunks, 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
       <<chunk name>>=
       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 documentation chunk.

       Documentation  chunks  contain  text  that  is  ignored by notangle and copied verbatim to
       standard output by noweave (except for quoted code).  noweave can work with  LaTeX,  plain
       TeX, troff or HTML.  With plain TeX, it inserts a reference to a TeX macro package, nwmac,
       which defines commands like \chapter and \section.

       Code chunks contain program source code and references to other code chunks.  Several code
       chunks may have the same name; notangle concatenates their definitions to produce a single
       chunk, just as does  tangle(1).   Code  chunk  definitions  are  like  macro  definitions;
       notangle  extracts  a  program 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.   notangle's  output  is readable; it preserves the indentation of
       expanded chunks with respect to the chunks in which they appear.

       Code may be quoted within documentation chunks by placing double square brackets ([[...]])
       around  it.  These double square brackets are ignored by notangle, but they may be used by
       noweave to give the code special typographic treatment, e.g., hypertext links.  If  quoted
       code ends with three or more square brackets, noweave chooses the rightmost pair, so that,
       for example, [[a[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.

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

       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.

TANGLING

       notangle and nountangle accept the same set of options, although some options have effects
       only on one or the other.  The options are:

       -Rname Expand the <<name>> code chunk.  The -R option can be repeated, in which case  each
              chunk  is  written to the output.  If no -R option is given, expand the chunk named
              <<*>>.

       -Lformat
              Emit line number  indications  at  chunk  boundaries.   A  line  number  indication
              identifies  the  source  of  the line that follows it.  In format, %F indicates the
              name of the source file, %L indicates the  line  number  of  the  source  file,  %N
              indicates  a  newline,  and  %%  indicates a percent sign.  A sign and digit may be
              inserted between the percent sign and the `L', in which case the line  number  will
              be  adjusted  by  that  amount.   If  format is omitted, the default format is that
              accepted by the C preprocessor: `#line %L "%F"%N'.  When using the -Lformat option,
              notangle  ensures  that  all  text  appears in the same column in input and output.
              nountangle ignores this option.

              Common format strings include:
                 C              -L'#line %L "%F"%N'
                 Sun FORTRAN    -L'\# %L "%F"%N'
                 Icon           -L'#line %-1L "%F"%N'
                 Modula-3       -L'<*LINE %L "%F" *>%N'
                 SML/NJ         -L'(*#line %L "%F"*)'

              To solve the converse problem, that is, to get noweb to do something sensible  with
              #line in its input, see the sharpline filter in the examples directory.

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

       -filter cmd
              Filter  the  noweb  source  through cmd after converting it to tool form and before
              tangling.  notangle looks for cmd first on the user's PATH, then in /usr/lib/noweb.
              Such  filters  can  be  used  to  add  features  to  notangle;  for  an example see
              /usr/lib/noweb/emptydefn.  For experts only.

       -markup parser
              Use parser to parse the input file.  Enables use of noweb tools on files  in  other
              formats;  for  example,  the  numarkup  parser  understands  nuweb(1)  format.  See
              nowebfilters(7) for more information.  For experts only.

       -awk | -c | -icn | -icon | -ml | -m3 | -pascal | -f77 | -f90 | -tex
              When nountangle transforms documentation chunks  into  comments,  use  the  comment
              format of the language named.  -c is the default.  notangle ignores these options.

       -wn    When  nountangle  transforms documentation chunks into comments, create comments on
              lines of width n.  notangle ignores this option.

WEAVING

       Output from noweave can be used in TeX documents that \input  nwmac,  in  LaTeX  documents
       that   use the noweb package (see nowebstyle(1)), and in HTML documents to be browsed with
       Mosaic(1).  Noweave treats code chunks somewhat like LaTeX list environments.  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, noweave puts  TeX
       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.

       Noweave  inserts  no  extra  newlines  in its TeX output, so the line numbers given in TeX
       error messages are the same as those in the input file.

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

       -latex Emit LaTeX, including wrapper in article style with  the  noweb  package  and  page
              style. (Default)

       -tex   Emit plain TeX, including wrapper with nwmac macros.

       -html  Emit  HTML,  using HTML wrapper.  The output is uninteresting without -index or -x.
              The tags <nowebchunks> and <nowebindex>, on lines by themselves, produce a list  of
              chunks  and  an index of identifiers, respectively.  If these tags are not present,
              the list and index are placed at the end of the file.

       -latex+html
              Assume documentation chunks are LaTeX, but generate HTML for code chunks,  suitably
              marked  so conversion with latex2html(1) yields reasonable output.  A LaTeX wrapper
              is implied, but can be turned off with -n.  Use of this option is  deprecated;  use
              -html with -filter l2h instead.

       -troff Emit  troff(1)  markup  (with  no  wrapper).   The  result should be processed with
              noroff(1).  Bug reports for -troff to Aharon Robbins <arnold@gnu.org>.

       -n     Don't use any wrapper (header or trailer).  This option is  useful  when  noweave's
              output will be a part of a larger document.  See also -delay.

       -filter cmd
              Filters  the  noweb  source through cmd after converting it to tool form and before
              converting to TeX.  noweave looks for  cmd  first  on  the  user's  PATH,  then  in
              /usr/lib/noweb.   Such  filters  can  be  used  to  add features to noweave; for an
              example, see /usr/lib/noweb/noxref.krom.  Noweave supports up to four filters;  one
              can  get  more  by shell trickery, for example, -filter "icon.filter | noidx".  The
              -autodefs, -x, -index, and -indexfrom options are implemented as filters.   Filters
              are executed with the shell's eval command, so cmd should be quoted accordingly.

       -markup parser
              Use  parser  to parse the input file.  Enables use of noweb tools on files in other
              formats; for  example,  the  numarkup  parser  understands  nuweb(1)  format.   See
              nowebfilters(7) for more information.  For experts only.

       -option opt
              Adds  \noweboptions{opt} to the LaTeX header.  See nowebstyle(1) for values of opt.
              Normally useful only with the -latex option, but -option longxref works black magic
              with -html.

       -delay By default, noweave puts file-name and other information into the output before the
              first chunk of the program.  -delay delays that information until after  the  first
              documentation chunk, making act a little bit like the WEB ``limbo.''  The option is
              typically used to enable a user to put a specialized LaTeX  \documentclass  command
              and  other  preamble  material  in  the first documentation chunk (i.e., before the
              first @ sign).  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 \end{document}.  The -delay option  implies  the
              -n option.

       -tk    Expand tabs with stops every k columns.  (Default is to expand every 8 columns.)

       -t     Copy tabs to the output.

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

INDEXING AND CROSS-REFERENCE

       When  used  with  LaTeX,  troff, or HTML, noweave can provide indexing and cross-reference
       information for chunks and for programming-language identifiers.   Identifier  definitions
       may  be  marked  by  hand  using backticks (`); the -filter btdefn option recognizes these
       markings.  For some languages, defintioins may be found automatically using the  -autodefs
       option.  This section describes the indexing and cross-reference options; it might well be
       skipped on first reading.

       -x     For LaTeX, add a page number to each chunk name identifying the  location  of  that
              chunk's  definition,  and emit cross-reference information relating definitions and
              uses.  For HTML, create hypertext links between uses  and  definitions  of  chunks.
              When  noweave -x is used with LaTeX, the control sequence \nowebchunks expands to a
              sorted list of all code chunks.

       -index Build cross-reference information (or hypertext  links)  for  defined  identifiers.
              Definitions  are  those  found  in  the  input  files  by  -autodefs language or by
              -filterbtdefn.  Requires LaTeX or HTML.  -index implies  -x;  including  both  will
              generate  strange-looking  output.   noweave  does not generate cross-references to
              identifiers that appear in quoted code (@[[...@]]), but it does generate  hypertext
              links.   When  noweave  -index is used with LaTeX, the control sequence \nowebindex
              expands to an index of identifiers.

       -indexfrom index
              Like -index, but the identifiers to be indexed are  taken  from  file  index.   See
              noindex(1).

       -autodefs lang
              Discover  identifier definitions automatically.  Code in chunks must be in language
              lang.  Permissible langs vary but may include tex or icon.  Useless without -index,
              which it must precede.

       -showautodefs
              Show values of lang usable with -autodefs.

ERROR MESSAGES

       If  notangle or noweave encounters a chunk name within documentation, it assumes that this
       indicates an error, usually 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.

EXAMPLES

       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 foo.nw file with a C program in chunk <<foo.c>>
       and a header file in chunk <<foo.h>>, and that  your  documentation  is  marked  up  using
       latex(1).  I'll show you how to build things using the most common options.

       To rebuild your C source, try
              notangle -L -Rfoo.c foo.nw > foo.c
       To rebuild your header file, try
              notangle -Rfoo.h foo.nw | cpif foo.h
       There  are  two  compromises  here.   Omitting -L keeps #line out of your header file, and
       using cpif prevents the command from rewriting foo.h unless  the  contents  have  changed.
       Thus, this is good code to put in a Makefile rule.

       To build a printed document, run
              noweave -autodefs c -index foo.nw > foo.tex
       If  you  have your own preamble, containing \documentclass and all, you will also need the
       -delay option.

       To build a web page, run
              noweave -filter l2h -autodefs c -index -html foo.nw | htmltoc > foo.html
       Have fun!

FILES

       /usr/lib/noweb/markup                          markup preprocessor
       /usr/lib/noweb/unmarkup                        inverts markup
       /usr/lib/noweb/nt                              notangle proper
       /usr/lib/noweb/finduses                        find uses of identifiers for index
       /usr/lib/noweb/noidx                           generate index and cross-reference info
       /usr/lib/noweb/toroff                          back end to emit troff
       /usr/lib/noweb/totex                           back end to emit TeX or LaTeX
       /usr/lib/noweb/tohtml                          back end to emit HTML
       /usr/share/texmf/tex/plain/misc/nwmac.tex      formatting TeX macros
       /usr/share/texmf/tex/plain/misc/noweb.sty      use in LaTeX documents; see nowebstyle(7)

SEE ALSO

       cpif(1),  nodefs(1),   noroots(1),   noweb(1),   noindex(1),   noroff(1),   nowebstyle(7),
       nowebfilters(7)

BUGS

       notangle and nountangle 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.   noroots(1)  can  be  used  to
       catch this mistake.

       The -L option of notangle puts an implicit initial newline in the format string.

       The  default  LaTeX  pagestyles  don't  set  the width of the boxes containing headers and
       footers.  Since noweb code paragraphs are extra wide, this LaTeX bug sometimes results  in
       extra-wide  headers  and  footers.   The remedy is to redefine the relevant ps@* commands;
       ps@noweb in noweb.sty can be used as an example.

       latex2html(1) mangles some source files.

       noweave has too many options, and this man page is too long.

VERSION

       This man page is from noweb version 2.11b.

AUTHOR

       Norman Ramsey, Harvard University.  Internet address nr@eecs.harvard.edu.
       Noweb home page at http://www.eecs.harvard.edu/~nr/noweb.

                                         local 3/28/2001                                 NOWEB(1)