[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Axiom-developer] [noweb] (new)

From: Bill Page
Subject: [Axiom-developer] [noweb] (new)
Date: Tue, 18 Oct 2005 21:22:03 -0500

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

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

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

     A <U>noweb</U> file is a sequence of <U>chunks</U>, 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
     &lt;&lt;<U>chunk</U> <U>name</U>&gt;&gt;=
     on a line by itself.  The double  left  angle  bracket  (&lt;&lt;)
     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  <U>notan-</U>
     <U>gle</U>  and  copied  verbatim  to  standard  output  by <U>noweave</U>
     (except for quoted code).   <U>noweave</U>  can  work  with  <U>LaTeX</U>,
     plain  <U>TeX</U>, or <U>HTML</U>.  With plain <U>TeX</U>, it inserts a 
     to a <U>TeX</U> macro package, <U>nwmac</U>, 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; <U>notangle</U> concatenates their definitions to  produce  a
     single chunk, just as does <B>tangle</A></B>. Code chunk definitions
     are like macro definitions; <U>notangle</U> extracts a  program  by
     expanding  one  chunk  (by  default, the chunk named &lt;&lt;*&gt;&gt;).
     The definition of that chunk contains  references  to  other
     chunks,   which   are   themselves   expanded,  and  so  on.
     <U>notangle</U>'s output is readable; it preserves the  indentation
     of  expanded chunks with respect to the chunks in which they

     Code may be quoted within documentation  chunks  by  placing
     double  square  brackets  ([[...]]) around it.  These double
     square brackets are ignored by <U>notangle</U>,  but  they  may  be
     used  by <U>noweave</U> to give the code special typographic treat-
     ment, e.g., hypertext links.  If quoted code ends with three
     or  more square brackets, <U>noweave</U> choose 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.

     If double left and right angle brackets are not paired, they
     are  treated as literal &lt;&lt; and &gt;&gt;.  Users can force any such
     brackets, even paired brackets, to be treated as literal  by
     using a preceding at sign (e.g. @&lt;&lt;).

     Some programming or formatting languages may require a  sin-
     gle @ 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
     @ %def <U>identifiers</U>
     it is taken to mean that the  preceding  chunk  defines  the
     identifiers  listed in <U>identifiers</U>. This list contains iden-
     tifiers separated by whitespace; any  sequence  of  nonwhite
     characters  may  be  an  identifier.   <U>noweb</U>  uses  a simple
     heuristic to avoid recognizing  identifiers  that  are  sub-
     strings of other identifiers.

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

          Expand the &lt;&lt;<U>name</U>&gt;&gt; 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  &lt;&lt;*&gt;&gt;.

          Emit line number indications at  chunk  boundaries.   A
          line  number  indication  identifies  the source of the
          line that follows it.  In <U>format</U>, %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 <U>format</U> is
          omitted, the default format is that accepted by  the  C
          preprocessor:   `#line  %L  "%F"%N'.   When  using  the
          -L<U>format</U> option, <U>notangle</U> ensures that all text appears
          in  the  same  column  in input and output.  <U>nountangle</U>
          ignores this option.

          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.

     -t<U>k</U>   Copy tabs untouched from input to output, and use tabs
          for  indentation,  assuming  stops every <U>k</U> columns.  By
          default, tabs are expanded to spaces with stops every 8

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

     -markup <U>parser</U>
          Use <U>parser</U> to parse the input  file.   Enables  use  of
          noweb tools on files in other formats; for example, the
          numarkup  parser  understands  <B>nuweb</B>  format.    See
          <B>nowebfilters</B>  for  more  information.   For  experts

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

     -w<U>n</U>  When <U>nountangle</U> transforms  documentation  chunks  into
          comments,  create comments on lines of width <U>n</U>.  <U>notan-</U>
          <U>gle</U> ignores this option.

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

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

     <U>noweave</U> 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

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

          Emit plain TeX, including wrapper with nwmac macros.

          Emit HTML, using HTML wrapper.   The  output  is  unin-
          teresting without -index or -x.  The tags &lt;nowebchunks&gt;
          and &lt;nowebindex&gt;, on lines  by  themselves,  produce  a
          list  of  chunks  and  an index of identifiers, respec-
          tively.  If these tags are not present,  the  list  and
          index are placed at the end of the file.

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

          Emit <B>troff</B> markup (with  no  wrapper).   The  result
          should  be  processed with <B>noroff</B>. Bug reports for -
          troff to Phil Bewig &lt;address@hidden&gt;.

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

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

     -markup <U>parser</U>
          Use <U>parser</U> to parse the input  file.   Enables  use  of
          noweb tools on files in other formats; for example, the
          numarkup  parser  understands  <B>nuweb</B>  format.    See
          <B>nowebfilters</B>  for  more  information.   For  experts

     -option <U>opt</U>
          Adds  \noweboptions{<U>opt</U>}  to  the  <U>LaTeX</U>  header.   See
          <B>nowebstyle</B>  for  values of <U>opt</U>. Normally useful only
          with the -latex option, but   - option  longxref  works
          black magic with -html.

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

     -t<U>k</U>   Expand tabs with stops every <U>k</U> columns.   (Default  is
          to expand every 8 columns.)

     -t    Copy tabs to the output.

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

     When used with <U>LaTeX</U> or <U>HTML</U>, <U>noweave</U> can  provide  
     and   cross-reference   information   for   chunks  and  for
     programming-language  identifiers.   Identifier  definitions
     may  be  marked  by hand using @ %def, or for some languages
     they 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 <U>LaTeX</U>, add a page number to each chunk name  iden-
          tifying  the  location  of that chunk's definition, and
          emit cross-reference information  relating  definitions
          and  uses.   For  <U>HTML</U>,  create hypertext links between
          uses and definitions of chunks.   When  noweave  -x  is
          used  with  <U>LaTeX</U>,  the  control  sequence \nowebchunks
          expands to a sorted list of all code chunks.

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

     -indexfrom <U>index</U>
          Like -index, but the  identifiers  to  be  indexed  are
          taken from file <U>index</U>.  See <B>noindex</B>.

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

          Show values of <U>lang</U> usable with -autodefs.

     If <U>notangle</U> or <U>noweave</U> encounters a chunk name within  docu-
     mentation,  it assumes that this indicates an error, usually
     misspelling ``&lt;&lt;name&gt;&gt;=''.  Other error messages  should  be

     It is incorrect to refer to a chunk that is  never  defined,
     but it is OK for chunks to be defined and not used.

     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
     &lt;&lt;foo.c&gt;&gt;  and  a  header  file in chunk 
&lt;&lt;foo.h&gt;&gt;, and that
     your documentation is marked up using LaTeX.  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 &gt; 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 &gt; 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 &gt; foo.html
     Have fun!

     /usr/cs/contrib/lib/noweb/markup                               markup 
     /usr/cs/contrib/lib/noweb/unmarkup                             inverts 
     /usr/cs/contrib/lib/noweb/nt                                   notangle 
     /usr/cs/contrib/lib/noweb/finduses                             find uses 
of identifiers for index
     /usr/cs/contrib/lib/noweb/noidx                                generate 
index and cross-reference info
     /usr/cs/contrib/lib/noweb/totex                                back end to 
emit <U>TeX</U> or <U>LaTeX</U>
     /usr/cs/contrib/lib/noweb/tohtml                               back end to 
emit HTML
     /usr/cs/contrib/share/texmf/tex/latex2e/contrib/nwmac.tex      formatting 
<U>TeX</U> macros
     /usr/cs/contrib/share/texmf/tex/latex2e/contrib/noweb.sty      use in 
<U>LaTeX</U> documents; see <B>nowebstyle</B>

     <U>notangle</U> and <U>nountangle</U> 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.  <B>noroots</B> can be  used  to
     catch this mistake.

     <U>noweb</U> requires the new version of <U>awk</U>, assumed to be  called
     <U>nawk</U>. DEC <U>nawk</U> has a bug in that that causes noweave to fail
     to translate braces correctly.   GNU  <U>gawk</U>  is  reported  to

     DEC <U>sh</U> has a bug that causes the  - filter  option  to  fail
     whenever the filter command contains more than one word.

     The default <U>LaTeX</U> pagestyles don't  set  the  width  of  the
     boxes  containing  headers  and  footers.   Since <U>noweb</U> code
     paragraphs are extra wide, this <U>LaTeX</U> bug sometimes  results
     in  extra-wide  headers and footers.  The remedy is to rede-
     fine the relevant address@hidden commands; address@hidden in  noweb.sty  
     be used as an example.

     <B>latex2html</B> mangles some source files.

     <U>noweave</U> has too many options, and this man page is too long.

     This man page is from <U>noweb</U> version 2.8a.

     Norman Ramsey, University  of  Virginia.   Internet  address
     Noweb home page at <a href="";></a>.

Man(1) output converted with
<a href="";>man2html</a>

forwarded from

reply via email to

[Prev in Thread] Current Thread [Next in Thread]