summaryrefslogtreecommitdiff
path: root/web/noweb/src/xdoc/nowebfilters.txt
blob: 485674ffdc29744eb61099a1a382d4efabe0e756 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
NOWEB(7)               Miscellaneous Information Manual               NOWEB(7)



NNAAMMEE
       nowebfilters - filters and parsers for use with noweb

SSYYNNOOPPSSIISS
       [nnoowweeaavvee|nnoottaannggllee|nnoowweebb] [--ffiilltteerr _f_i_l_t_e_r|--mmaarrkkuupp _p_a_r_s_e_r] ...

DDEESSCCRRIIPPTTIIOONN
       This  man  page documents the various filters and parsers that are sup‐
       plied with _n_o_w_e_b(1).  A filter, which transforms the pipeline represen‐
       tation,  is  used  with  the  --ffiilltteerr  option.  A parser, which reads a
       source file and emits the pipeline representation,  is  used  with  the
       --mmaarrkkuupp  option.   Not  all  filters  and  parsers are available at all
       installations.

FFIILLTTEERRSS
       aauuttooddeeffss..**
              _n_o_w_e_a_v_e_'_s --aauuttooddeeffss and --sshhoowwaauuttooddeeffss options use these filters,
              which  automatically find defined identifiers.  The ** stands for
              the name of a programming language.  (Icon installation only.)

       bbttddeeffnn The bbttddeeffnn filter uses Dave Hanson's convention to mark  defini‐
              tions.  In code chunks, each defining instances of an identifier
              should be preceded by a single backtick character  (ASCII  140).
              The bbttddeeffnn filter removes these backticks from the code and con‐
              verts them to definitions, thus: ``ddeeffiinniittiioonn.  It, not  @@  %%ddeeff,
              should  be  used  with both _n_o_t_a_n_g_l_e(1) and _n_o_w_e_a_v_e(1), at least
              for programs written in C-like languages.

       ddiissaammbbiigguuaattee
              The ddiissaammbbiigguuaattee filter makes it possible  to  abbreviate  chunk
              names using a trailing ellipsis (three periods), in the style of
              WEB and _n_u_w_e_b(1).

       ddooccss22ccoommmmeennttss _o_p_t_i_o_n_s
              The ddooccss22ccoommmmeennttss filter converts documentation chunks  to  com‐
              ments  in code chunks.  Options include --aallll, which converts all
              documentation chunks into comments; --oonnee converts only one docu‐
              mentation  chunk preceding each code chunk.  The --ww_k option for‐
              mats comments _k columns wide.

              Other options control the language and  style  of  the  comment.
              Languages  available  include  --aawwkk, --cc, --cc++++, --ff7777, --ff9900, --iiccnn,
              --iiccoonn, --lliisspp, --mm33, --mmll, --ooccaammllwweebb, --ppaassccaall, --ssccmm, and --tteexx.

              Norman recommends using nnoottaannggllee(1) with ddooccssttooccoommmmeennttss  instead
              of nnoouunnttaannggllee(1).  (Icon installation only.)

       eelliiddee _p_a_t_t_e_r_n_s
              The eelliiddee 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 ** mmaattcchheess aannyy sseeqquueennccee ooff cchhaarr‐‐
              aacctteerrss..

       eemmppttyyddeeffnn
              The eemmppttyyddeeffnn filter makes an empty definition (<<<<>>>>==) an abbre‐
              viation for a continuation of the previous definition.

       ll22hh [--sshhooww--uunnkknnoowwnnss] [--hhttmmll--qquuootteess]
              The  ll22hh  filter converts LaTeX to HTML in documentation chunks.
              If the --sshhooww--uunnkknnoowwnnss options is given, unrecognized LaTeX  con‐
              trol   sequences   appear   in  bold  in  the  output.   If  the
              --hhttmmll--qquuootteess option is given, ll22hh  converts  LaTeX  double-quote
              ligatures  into  HTML  4  double-quote  entities.   ll22hh uses the
              LaTeX-generated .toc and .bbl files to help create table of con‐
              tents and bibliography.  (Icon installation only.)

       ppiippeeddooccss _c_o_m_m_a_n_d
              The  ppiippeeddooccss  filter  runs  each documentation chunk through an
              invocation of _c_o_m_m_a_n_d, which may be any Unix command.  The Noweb
              library  includes the command hh22aa, which uses _l_y_n_x(1) to convert
              HTML to ASCII.

       xxcchhuunnkkss _f_i_l_e_s
              The xxcchhuunnkkss filter pulls in code chunks from an external source.
              The _f_i_l_e_s argument lists one or more noweb files, which are used
              only for their definitions of code chunks.  Empty chunk  defini‐
              tions  in the main document are replaced with the external defi‐
              nitions 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.)

PPAARRSSEERRSS
       A  parser  converts  a source file to the noweb pipeline format, inter‐
       preting 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

       mmaarrkkuupp Converts standard _n_o_w_e_b(1) markup to pipeline format.

       nnuummaarrkkuupp
              Converts _n_u_w_e_b(1) markup to noweb pipeline format.   It  is  not
              part  of  the  standard  installation,  but  it  can be found in
              _n_o_w_e_b's ccoonnttrriibb//nnoorrmmaann directory.

FFIILLEESS
       All filters and parsers are stored in ||LLIIBBDDIIRR||

BBUUGGSS
       It is possible to tell ll22hh about new control sequences by putting  spe‐
       cial  TeX  comments in one's documentation chunks, but there's no docu‐
       mentation.  Use the source, Luke.

       nnuummaarrkkuupp loses information, e.g., about the proper treatment  of  tabs.
       It  also  doesn't  compensate for _n_o_t_a_n_g_l_e's newline-removal heuristic,
       which means results on _n_u_w_e_b files may differ subtly  from  those  pro‐
       duced by _n_u_w_e_b_.

       Many filters are not available in installations that use Awk instead of
       Icon.

SSEEEE AALLSSOO
       _n_o_w_e_a_v_e(1), _n_o_t_a_n_g_l_e(1), _n_o_w_e_b(1)
       The _N_o_w_e_b _H_a_c_k_e_r_'_s _G_u_i_d_e

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(7)