path: root/web/noweb/src/xdoc/notangle.txt

NOWEB(1)                    General Commands Manual                   NOWEB(1)



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

SSYYNNOOPPSSIISS
       nnoottaannggllee [--RRrootname ...] [--ffiilltteerr command] [--LL[format]] [file] ...
       nnoouunnttaannggllee [--mmll|--mm33|--cc|--cc++++|--aawwkk|--tteexx|--ff7777|--ff9900|--lliisspp|--mmaattllaabb] [--RRroot‐
       name ...] [--ffiilltteerr command] [--wwwidth] [file] ...
       nnoowweeaavvee [options] [file] ...

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

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  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 \\cchhaapptteerr and \\sseeccttiioonn..

       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 concate‐
       nates their definitions to produce a single chunk, just  as  does  _t_a_n_‐
       _g_l_e(1).   Code  chunk  definitions are like macro definitions; _n_o_t_a_n_g_l_e
       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.  _n_o_t_a_n_g_l_e'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 _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,  [[[[aa[[ii]]]]]]  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.

TTAANNGGLLIINNGG
       _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:

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

       --LL_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, %%FF indicates the name of the source  file,  %%LL  indi‐
              cates  the  line  number of the source file, %%NN indicates a new‐
              line, and %%%% indicates a percent sign.  A sign and digit may  be
              inserted between the percent sign and the `LL', in which case the
              line number will be adjusted by that amount.  If _f_o_r_m_a_t is omit‐
              ted,  the default format is that accepted by the C preprocessor:
              `##lliinnee %%LL ""%%FF""%%NN'.  When using  the  --LL_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              --LL''##lliinnee %%LL ""%%FF""%%NN''
                 Sun FORTRAN    --LL''\\## %%LL ""%%FF""%%NN''
                 Icon           --LL''##lliinnee %%--11LL ""%%FF""%%NN''
                 Modula-3       --LL''<<**LLIINNEE %%LL ""%%FF"" **>>%%NN''
                 SML/NJ         --LL''((**##lliinnee %%LL ""%%FF""**))''

              To solve the converse problem, that is, to get noweb to do some‐
              thing sensible with ##lliinnee in its input, see the sshhaarrpplliinnee filter
              in the examples directory.

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

       --ffiilltteerr _c_m_d
              Filter the _n_o_w_e_b source through _c_m_d after converting 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 PPAATTHH, then in ||LLIIBBDDIIRR||.  Such filters can be used to  add
              features  to  _n_o_t_a_n_g_l_e;  for  an example see ||LLIIBBDDIIRR||//eemmppttyyddeeffnn.
              For experts only.

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

       --aawwkk || --cc || --iiccnn || --iiccoonn || --mmll || --mm33 || --ppaassccaall || --ff7777 || --ff9900 || --tteexx
              When  _n_o_u_n_t_a_n_g_l_e  transforms documentation chunks into comments,
              use the comment  format  of  the  language  named.   --cc  is  the
              default.  _n_o_t_a_n_g_l_e ignores these options.

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

WWEEAAVVIINNGG
       Output  from _n_o_w_e_a_v_e can be used in _T_e_X documents that \\iinnppuutt nnwwmmaacc,, in
       _L_a_T_e_X documents that  use the nnoowweebb package (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 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  ter‐
       minates 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 num‐
       bers 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.

       --llaatteexx Emit LaTeX, including wrapper in aarrttiiccllee style  with  the  nnoowweebb
              package and page style. (Default)

       --tteexx   Emit plain TeX, including wrapper with nnwwmmaacc macros.

       --hhttmmll  Emit  HTML,  using  HTML  wrapper.   The output is uninteresting
              without --iinnddeexx or --xx.  The tags <<nnoowweebbcchhuunnkkss>> and  <<nnoowweebbiinnddeexx>>,
              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.

       --llaatteexx++hhttmmll
              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 --nn.  _U_s_e _o_f _t_h_i_s _o_p_t_i_o_n  _i_s  ddeepprreeccaatteedd;;  use
              --hhttmmll with --ffiilltteerr ll22hh instead.

       --ttrrooffff 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 --ttrrooffff to Arnold Rob‐
              bins <<aarrnnoolldd@@sskkeeeevvee..ccoomm>>..

       --nn     Don't  use any wrapper (header or trailer).  This option is use‐
              ful when _n_o_w_e_a_v_e's output will be a part of a  larger  document.
              See also --ddeellaayy..

       --ffiilltteerr _c_m_d
              Filters the _n_o_w_e_b source through _c_m_d after converting 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 PPAATTHH,, then in ||LLIIBBDDIIRR||..  Such filters can be used
              to  add  features  to  _n_o_w_e_a_v_e_;  for  an  example,   see   ||LLIIBB‐‐
              DDIIRR||//nnooxxrreeff..kkrroomm..   _N_o_w_e_a_v_e supports up to four filters; one can
              get more by shell trickery, for example, --ffiilltteerr ""iiccoonn..ffiilltteerr  ||
              nnooiiddxx"".   The  --aauuttooddeeffss, --xx, --iinnddeexx, and --iinnddeexxffrroomm options are
              implemented as filters.  Filters are executed with  the  shell's
              eevvaall command, so _c_m_d should be quoted accordingly.

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

       --ooppttiioonn _o_p_t
              Adds \\nnoowweebbooppttiioonnss{{_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 --llaatteexx option,
              but --ooppttiioonn lloonnggxxrreeff works black magic with --hhttmmll..

       --ddeellaayy By default, _n_o_w_e_a_v_e puts file-name and  other  information  into
              the output before the first chunk of the program.  --ddeellaayy delays
              that information until after the first documentation chunk, mak‐
              ing act a little bit like the _W_E_B ``limbo.''  The option is typ‐
              ically used to enable a user to put a specialized  _L_a_T_e_X  \\ddooccuu‐‐
              mmeennttccllaassss command and other preamble material in the first docu‐
              mentation chunk (i.e., _b_e_f_o_r_e 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  docu‐
              ment;  the  final  chunk  is expected to contain \\eenndd{{ddooccuummeenntt}}..
              The --ddeellaayy option implies the --nn option.

       --tt_k    Expand tabs with stops every _k columns.  (Default is  to  expand
              every 8 columns.)

       --tt     Copy tabs to the output.

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

IINNDDEEXXIINNGG AANNDD CCRROOSSSS--RREEFFEERREENNCCEE
       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 definitions may be marked by hand using back‐
       ticks (`); the --ffiilltteerr bbttddeeffnn option recognizes  these  markings.   For
       some  languages,  definitions  may  be  found  automatically  using the
       --aauuttooddeeffss option.  This section describes the indexing and cross-refer‐
       ence options; it might well be skipped on first reading.

       --xx     For  _L_a_T_e_X_, 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 _H_T_M_L_, create
              hypertext links between uses and definitions  of  chunks.   When
              nnoowweeaavvee --xx is used with _L_a_T_e_X_, the control sequence \\nnoowweebbcchhuunnkkss
              expands to a sorted list of all code chunks.

       --iinnddeexx Build  cross-reference  information  (or  hypertext  links)  for
              defined  identifiers.   Definitions are those found in the input
              files by --aauuttooddeeffss _l_a_n_g_u_a_g_e or by --ffiilltteerrbtdefn.  Requires _L_a_T_e_X
              or  _H_T_M_L_.   --iinnddeexx  implies  --xx;;  including  both  will generate
              strange-looking output.  _n_o_w_e_a_v_e does not generate  cross-refer‐
              ences to identifiers that appear in quoted code (@@[[[[...@@]]]]), but
              it does generate hypertext links.  When nnoowweeaavvee --iinnddeexx  is  used
              with _L_a_T_e_X_, the control sequence \\nnoowweebbiinnddeexx expands to an index
              of identifiers.

       --iinnddeexxffrroomm _i_n_d_e_x
              Like --iinnddeexx,, but the identifiers to be indexed  are  taken  from
              file _i_n_d_e_x.  See _n_o_i_n_d_e_x_(_1_)_.

       --aauuttooddeeffss _l_a_n_g
              Discover  identifier  definitions automatically.  Code in chunks
              must be in  language  _l_a_n_g.   Permissible  _l_a_n_gs  vary  but  may
              include tteexx or iiccoonn..  Useless without --iinnddeexx,, which it must pre‐
              cede.

       --sshhoowwaauuttooddeeffss
              Show values of _l_a_n_g usable with --aauuttooddeeffss.

EERRRROORR MMEESSSSAAGGEESS
       If _n_o_t_a_n_g_l_e or _n_o_w_e_a_v_e 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.

EEXXAAMMPPLLEESS
       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  ffoooo..nnww
       file  with  a  C  program in chunk <<<<ffoooo..cc>>>> and a header file in chunk
       <<<<ffoooo..hh>>>>, 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
              nnoottaannggllee --LL --RRffoooo..cc ffoooo..nnww >> ffoooo..cc
       To rebuild your header file, try
              nnoottaannggllee --RRffoooo..hh ffoooo..nnww || ccppiiff ffoooo..hh
       There  are  two  compromises here.  Omitting --LL keeps ##lliinnee out of your
       header file, and using ccppiiff prevents the command from  rewriting  ffoooo..hh
       unless  the contents have changed.  Thus, this is good code to put in a
       Makefile rule.

       To build a printed document, run
              nnoowweeaavvee --aauuttooddeeffss cc --iinnddeexx ffoooo..nnww >> ffoooo..tteexx
       If you have your own preamble, containing \\ddooccuummeennttccllaassss and  all,  you
       will also need the --ddeellaayy option.

       To build a web page, run
              nnoowweeaavvee  --ffiilltteerr ll22hh --aauuttooddeeffss cc --iinnddeexx --hhttmmll ffoooo..nnww || hhttmmllttoocc >>
              ffoooo..hhttmmll
       Have fun!

FFIILLEESS
       |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_)

SSEEEE AALLSSOO
       _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)

BBUUGGSS
       _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 def‐
       initions  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.





















       The _-_L option of _n_o_t_a_n_g_l_e puts an implicit initial newline in the  for‐
       mat string.

       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.

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

VVEERRSSIIOONN
       This man page is from _n_o_w_e_b version 2.12.

AAUUTTHHOORR
       Norman   Ramsey,   Tufts   University.   Internet  address  NNoorrmmaann..RRaamm‐‐
       sseeyy@@ttuuffttss..eedduu.
       Noweb home page at hhttttpp::////wwwwww..ccss..ttuuffttss..eedduu//~~nnrr//nnoowweebb.




                               local 10/40/2008                       NOWEB(1)