NAME¶
nowebfilters - filters and parsers for use with noweb
SYNOPSIS¶
[
noweave|
notangle|
noweb] [
-filter
filter|
-markup parser] ...
DESCRIPTION¶
This man page documents the various filters and parsers that are supplied with
noweb(1). A filter, which transforms the pipeline representation, is
used with the
-filter option. A parser, which reads a source file and
emits the pipeline representation, is used with the
-markup option. Not
all filters and parsers are available at all installations.
FILTERS¶
- autodefs.*
- noweave's -autodefs and -showautodefs options use
these filters, which automatically find defined identifiers. The *
stands for the name of a programming language. (Icon installation
only.)
- btdefn
- The btdefn filter uses Dave Hanson's convention to mark
definitions. In code chunks, each defining instances of an identifier
should be preceded by a single backtick character (ASCII 140). The
btdefn filter removes these backticks from the code and converts
them to definitions, thus: `definition. It, not @ %def,
should be used with both notangle(1) and noweave(1), at
least for programs written in C-like languages.
- disambiguate
- The disambiguate filter makes it possible to abbreviate chunk names
using a trailing ellipsis (three periods), in the style of WEB and
nuweb(1).
- docs2comments options
- The docs2comments filter converts documentation chunks to comments
in code chunks. Options include -all, which converts all
documentation chunks into comments; -one converts only one
documentation chunk preceding each code chunk. The -wk
option formats comments k columns wide.
- Other options control the language and style of the comment. Languages
available include -awk, -c, -c++, -f77,
-f90, -icn, -icon, -lisp, -m3,
-ml, -ocamlweb, -pascal, -scm, and
-tex.
- Norman recommends using notangle(1) with docstocomments
instead of nountangle(1). (Icon installation only.)
- elide patterns
- The elide filter removes from the stream any code chunk matching
any of the arguments. Each argument is a pattern in which ? matches
any single character and * matches any sequence of characters.
- emptydefn
- The emptydefn filter makes an empty definition (
<<>>=) an abbreviation for a continuation of the
previous definition.
- l2h [-show-unknowns]
- The l2h filter converts LaTeX to HTML in documentation chunks. If
the -show-unknowns options is given, unrecognized LaTeX control
sequences appear in bold in the output. l2h uses the
LaTeX-generated .toc and .bbl files to help create table of contents and
bibliography. (Icon installation only.)
- pipedocs command
- The pipedocs filter runs each documentation chunk through an
invocation of command, which may be any Unix command. The Noweb
library includes the command h2a, which uses lynx(1) to
convert HTML to ASCII.
- xchunks files
- The xchunks filter pulls in code chunks from an external source.
The files argument lists one or more noweb files, which are used
only for their definitions of code chunks. Empty chunk definitions in the
main document are replaced with the external definitions of the same name.
This filter makes it possible to include the same code chunks in multiple
documents, or even the same code chunks multiple times in the same
document. (Icon installation only.)
PARSERS¶
A parser converts a source file to the noweb pipeline format, interpreting the
``markup'' in that file. By default, the tools use the standard noweb markup,
but some installations may support nuweb markup as well. Parsers include
- markup
- Converts standard noweb(1) markup to pipeline format.
- numarkup
- Converts nuweb(1) markup to noweb pipeline format. It is not part
of the standard installation, but it can be found in noweb's
contrib/norman directory.
FILES¶
All filters and parsers are stored in
/usr/lib/noweb
BUGS¶
It is possible to tell
l2h about new control sequences by putting special
TeX comments in one's documentation chunks, but there's no documentation. Use
the source, Luke.
numarkup loses information, e.g., about the proper treatment of tabs. It
also doesn't compensate for
notangle's newline-removal heuristic, which
means results on
nuweb files may differ subtly from those produced by
nuweb.
Many filters are not available in installations that use Awk instead of Icon.
SEE ALSO¶
noweave(1),
notangle(1),
noweb(1)
The
Noweb Hacker's Guide
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.