summaryrefslogtreecommitdiff
path: root/web/noweb/src/xdoc/noindex.txt
blob: a3823e448939952f53c58a36521d5233cc544a35 (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
NOWEB(1)                    General Commands Manual                   NOWEB(1)



NNAAMMEE
       noindex - build external index for noweb document

SSYYNNOOPPSSIISS
       nnooiinnddeexx _b_a_s_e_n_a_m_e[..tteexx]

DDEESSCCRRIIPPTTIIOONN
       _n_o_i_n_d_e_x  looks  through _L_a_T_e_X ..aauuxx files for identifiers that should go
       in a _n_o_w_e_b external index.  It sorts all  identifiers  and  writes  the
       results on _b_a_s_e_n_a_m_e..nnwwii_.

NNOOWWEEBB IINNDDEEXXIINNGG SSTTRRAATTEEGGIIEESS
       A  _n_o_w_e_b  program  consists  of one or more files.  In the simple case,
       these files are run through _n_o_w_e_a_v_e together, to produce a single _L_a_T_e_X
       file.   _n_o_w_e_a_v_e _-_i_n_d_e_x suffices to produce an index and cross-referenc‐
       ing information; neither _n_o_d_e_f_s nor _n_o_i_n_d_e_x is required.

       When a _n_o_w_e_b program consists of several source files, it is often bet‐
       ter  to  run  each source file through _n_o_w_e_a_v_e to produce its own _L_a_T_e_X
       file, then use _n_o_i_n_d_e_x to produce an external  index.   This  technique
       has several advantages:

              The  line numbers in the _L_a_T_e_X files correspond to the line num‐
              bers in the source files, so it  is  easier  to  diagnose  _L_a_T_e_X
              errors.

              The  _L_a_T_e_X  \\iinncclluuddeeoonnllyy feature can be used, making it possible
              to format parts  of  large  programs  while  retaining  complete
              cross-reference information.

              When  used  with  _m_a_k_e(1),  the technique avoids running _n_o_w_e_a_v_e
              over source files that have not changed.

              Using the external index places fewer demands on _L_a_T_e_X's memory,
              making it read its ..aauuxx files much more quickly.

       The  disadvantages  are  that  _n_o_d_e_f_s  and  _n_o_i_n_d_e_x are needed for full
       cross-referencing and a properly sorted index.

EEXXAAMMPPLLEE
       This example assumes a _n_o_w_e_b program of three source files: aa..nnww ,, bb..nnww
       ,,  and cc..nnww.  The file ddoocc..tteexx is assumed to contain _L_a_T_e_X boilerplate,
       including the commands

              \noweboptions{externalindex}
              \include{a}
              \include{b}
              \include{c}

       The first sequence of steps is to create a file listing all the identi‐
       fiers defined anywhere in aa, bb, or cc.

              nodefs a.nw > a.defs
              nodefs b.nw > b.defs
              nodefs c.nw > c.defs
              sort -u a.defs b.defs c.defs | cpif all.defs

       Using  _s_o_r_t  _-_u  and _c_p_i_f(1) avoids changing aallll..ddeeffss unless the set of
       identifiers changes.  This technique, used in a Makefile, avoids unnec‐
       essary rebuilding.

       The  next series of steps is to create _L_a_T_e_X files with full cross-ref‐
       erence information for all identifiers.

              noweave -n -indexfrom all.defs a.nw > a.tex
              noweave -n -indexfrom all.defs b.nw > b.tex
              noweave -n -indexfrom all.defs c.nw > c.tex

       The final steps run _L_a_T_e_X once to create ..aauuxx files,  then  _n_o_i_n_d_e_x  to
       create the index, then _L_a_T_e_X again to format the complete document.

              latex doc
              noindex doc
              latex doc

       In a Makefile, _n_o_i_n_d_e_x can be run before every invocation of _L_a_T_e_X_.

BBUUGGSS
       _n_o_i_n_d_e_x  is  distributed  in awk and Icon versions.  The awk version is
       slow and does a poorer job sorting.

       There is no comparable machinery to make it possible  to  use  multiple
       files with the HTML back end.

SSEEEE AALLSSOO
       _n_o_w_e_a_v_e(1), _n_o_d_e_f_s(1), _c_p_i_f(1)

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)