summaryrefslogtreecommitdiff
path: root/web/noweb/src/FAQ.html
blob: f492e5c5ca3699b83fee0f2b3f440bc590a4f5fe (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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
<html><head><title>
Noweb Frequently Asked Questions</title></head><body>

<h2><a name=toc1>Noweb Frequently Asked Questions</a></h2>

<tableofcontents>
<ul compact>
<li><a href="#toc2">Problems Building Noweb</a></li>
<li><a href="#toc3">Indentation of code, especially FORTRAN</a></li>
<li><a href="#toc4">Formatting the printed documentation</a></li>
<li><a href="#toc5">Microsoft Madness</a></li>
<li><a href="#toc6">Noweb and Emacs</a></li>
<li><a href="#toc7">Other Questions</a></li>
</ul>
</tableofcontents>

<h3><a name=toc2>Problems Building Noweb</a></h3>

<b>Q.</b>  The build fails because it can't find notangle.  What am I doing wrong? 

<p><blockquote><b>A.</b>  Your source files have the wrong timestamps.  The noweb files are
    carefully distributed so that the C code is more recent than the
    literate source code.  Retrieving that noweb distribution as a
    compressed tar file preserves these stamps.  The CTAN sites will
    create a compressed tar file on the fly for any directory.  Your
    best bet is to get the tar file, unpack it, and try again, because
    your abortive attempt will probably have stomped on a C file that
    you need.   
<p>
   I have reports that the former  CTAN site <tt>ftp.shsu.edu</tt>
fouled the timestamps.  Don't use the site!
If you get bad timestamps, 
   you can try 
    `make touch' as soon as you unpack the distribution, which should
    touch all of the derived files.  This trick won't work on NeXT
    systems, which have a strange idea of 'touch'.

</blockquote><p><b>Q.</b>  The system builds OK, but when I try to run noweave, I get an
    error in /usr/public/pkg/noweb/lib/totex (or some similar place)
    complaining about being out of environment space or something
    equally unpleasant.

<p><blockquote><b>A.</b>  The awk versions of the noweb scripts pass the awk programs as
    arguments on the command line.  Some shells or systems are too
    broken to handle a real awk program on the command line.  This
    problem is one of many reasons that the awk versions are
    officially deprecated.  The Icon versions will make you happy, but
    if you prefer, you can edit the offending scripts so that the awk
    programs reside in separate files and the scripts call awk -f.
</blockquote>

<p><b>Q.</b>  
   I'm unable to run noweb on Windows NT 4.0. The problem is that the
   Icon programs use a DOS extender which doesn't work in an NT console.
<p><blockquote><b>A.</b> 
   Clint Jeffery, the Icon Master for Windows, says to 
 use the <a href=ftp://ringer.cs.utsa.edu/pub/icon/nt/console>NT
console binaries</a>
 (<tt>nticont.exe</tt> and
<tt>nticonx.exe</tt>) rather than
<tt>wiconx.exe</tt> with its faux console.  Only applications that use
the graphics 
facilities require <tt>wiconx.exe</tt> and its kin.  The
<tt>nticonx*</tt> binaries should run fine 
on Win95 also.
</blockquote>


<p><b>Q.</b>  
   I'm having trouble getting noweb to work on Windows&nbsp;XP.
<p><blockquote><b>A.</b> 
Bad news.  There used to be a distribution from
<tt>literateprogramming.org</tt>, but as of January 2010, that domain
   is no longer registered, and I don't know where the distribution
   went.
<!--
Some users are very satisfied with a distribution from
<a
   href=http://www.literateprogramming.org><tt>http://www.literateprogramming.org</tt></a>.
This distribution requires
 Cygwin (in particular, Cygwin's bash shell) to get the pipes and so on
working.
  The installation instructions are at
<A href=http://www.literateprogramming.com/noweb/nowebinstall.html><tt>http://www.literateprogramming.com/noweb/nowebinstall.html</tt></a>.
-->
</blockquote>

<h3><a name=toc3>Indentation of code, especially FORTRAN</a></h3>

<b>Q.</b> 

Has anyone devised a clean way of handling FORTRAN 77 using a litprog tool 
such as noweb?  If I have the following:
<pre>
&lt;&lt;Block>>=
      &lt;&lt;Nicely Indented Chunk Title>>
@
&lt;&lt;Nicely Indented Chunk Title>>=
C   A comment in a chunk!
      Z = X * 
     + Y
@
</pre>
I'll get the "C" in column 7, and the continuation character "+" in column 
12, neither of which is desirable. 
<p><blockquote><b>A.</b>  
As noted on the man page, notangle's <tt>-L</tt> option suppresses the
usual behavior with respect to indentation.
Thus, a command like
<blockquote><tt>notangle -L'%N' pgm.nw > pgm.f</tt></blockquote>
should do the job.
</blockquote>


<p><b>Q.</b>  
I noticed the <tt>-L</tt> option to notangle turns off the usual indentation.
Is there an easy way to get both <tt>-L</tt> and indentation? 
<p><blockquote><b>A.</b> 
No. It was my design decision that <tt>-L</tt> should preserve the column numbers
in the original source code.  This behavior is extremely useful in
cases where a compiler reports an error in the source by line and
<em>column</em> number.  Of course, this decision precludes changing the
indentation of the input.
</blockquote>




<h3><a name=toc4>Formatting the printed documentation</a></h3>

<b>Q.</b>  There's too much white space at the bottom of the pages,
especially if a code chunk is followed by a section.  How do I fix it?

<p><blockquote><b>A.</b>  
Noweb is set up never to break chunks across pages.
You can get better results by relaxing this constraint, e.g., by
<pre>
\def\nwendcode{\endtrivlist \endgroup \vfil\penalty10\vfilneg}
\let\nwdocspar=\smallbreak
</pre>
or the even less liberal
<pre>
\def\nwendcode{\endtrivlist \endgroup}
\let\nwdocspar=\par
</pre>
</blockquote>

<p>
<b>Q.</b> 
In a noweb source file, what is the difference between a
line beginning with "@" followed by a space and some text
versus a line with nothing but "@"?
<p><blockquote><b>A.</b>  
A line with nothing but @ begins the `documentation chunk' with a
blank line.  TeX thinks blank lines are new paragraphs and good places
to put page breaks.  By default, TeX thinks that if a new
documentation chunk starts with a new paragraph, this is an especially
good place for a page break.
</blockquote>
<p>
<b>Q.</b> 
I know how to switch between code and documentation via
<tt>&lt;&lt;*&gt;&gt;=</tt> and <tt>@</tt>,
but sometimes, after a <tt>&lt;&lt;*&gt;&gt;=</tt> section, automatically a new page is
started, even if I do not want this but prefer to go on with commenting
directly after the inserted programm code. How can I avoid this?
<p><blockquote><b>A.</b>  
The <tt>@</tt> sign you use to switch back to documentation should not
appear on a line by itself, but should be followed by a blank space
and some text.
You should then put a bare <tt>@</tt> sign on a line by itself at the
next place that is suitable for a page break.
</blockquote>
<p>
<b>Q.</b> 
I don't quite understand noweb's default page breaking.
<pre>
Here is some text
that leads up to a chunk
&lt;&lt;chunk>>=
  a = b;
  c = d;
@ and here is some more text.
Sometimes this appears on a new page even though
there is plenty of room on this page.  Can I fix it by adding
the following line (which I  haven't been doing) ?
@
New paragraph here.
</pre>
<p>
<blockquote>
<b>A.</b> 
Sad but true.
Perhaps a future version of noweb will provide better facilities for
controlling page breaking.
</blockquote>




<p>
<b>Q.</b> I ran into a problem when trying to use several files in a single noweb
project.  In my project, I have a LaTeX master file (say, doc.tex) that
\include's three others: say, a.tex, b.tex, and copyright.tex.  These
later files are generated from a.nw, b.nw, and copyright.nw,
respectively, using the command "noweave -n -index" I <em>really</em> want to
keep these noweb files separated.  In the code chunks appearing in both
a.nw and b.nw a copyright notice chunk (defined in copyright.nw) is
included.
<p>
Tangling works fine, provided that copyright.nw appears in the notangle
command.  Problems arise with noweave.  Copyright chunks appear as
"(never defined)" in a.tex and b.tex, what is obvious, because I cannot
use copyright.nw for weaving a.nw or b.nw (otherwise the copyright
notice chunk would appear several times in my printed document).
<p>
Does someone know how to solve this problem?

<p><blockquote><b>A.</b>  
This is a form of question that arises repeatedly, which is to say,
``what is the scope of chunk names?''
In Noweb, chunk names are in the same scope if the files in which the
chunks appear are used on the same command line.
Thus, the normal rule is one Noweb file per command line, and
therefore each file is its own scope.
<p>
You want to have chunks in the same scope for purposes of tangling,
but not to weave files together.
If you want files a.nw and b.nw in separate scopes, the situation is
hopeless, because ``being in the same scope'' has to be a transitive
property, and if a.nw and b.nw are both in the same scope as
copyright.nw, they must be in the same scope as each other.
<p>
However, if you want all files to be in the same scope, there is a
solution, although it is a bit ugly.  The solution is to weave all the
files together, then use a special back end to split them into
separate .tex files.
This back end, called <a href=scopehack.icn><tt>scopehack</tt></a>, could
be used as follows:
<blockquote>
<pre>
noweave -n -index -backend scopehack *.nw
</pre>
</blockquote>
and this results in multiple *.tex files as required.
</blockquote>

<p>
<b>Q.</b> 
I have problems using LaTeX <code>\ifthenelse</code> with noweb---
code chunks inside an <code>\ifthenelse</code> are not typeset correctly and
a <code>%def</code> directive causes (La)TeX groups to be unbalanced.  

<p><blockquote><b>A.</b> 
Noweb code chunks are ``moving arguments'' (like <code>\verb</code>) and can't be
arguments to macros.  I suggest you combine  <code>\ifthenelse</code> with the noweb
'elide' filter to remove the offending code chunks.
</blockquote>

<p>
<b>Q.</b> 
I embed the build instructions for a noweb-based project in a code chunk
called <tt>build-script</tt> that I don't
wish to have show up in the printed documentation. So, I surround the
section with LaTeX <code>\iffalse ... \fi</code>.
If I do this at the same time as using noweb's index, the <code>\fi</code> shows up in
the generated TeX file
at the end of the index information, resulting in an empty index.
<p>
<blockquote><b>A.</b> 
Make sure that the <code>\fi</code> appears <em>before</em> the last
documentation chunk, by creating an empty documentation chunk
(with&nbsp;@) if necessary.
Then use <code>noweave -delay</code> to insert the index information.
<p>
Incidentally, it is recommended that, in addition to using
<code>\iffalse ... \fi</code>, you remove unwanted code chunks by
using the <tt>elide</tt> filter provided with noweb.
Latex can get confused if chunk cross-reference anchors are hidden
away inside <code>\iffalse ... \fi</code>.
</blockquote>

<b>Q.</b> When I write C&nbsp;code and use the decrement
operator <tt>--</tt>, it appears in the resulting document as a single
<tt>-</tt>. 
This unpleasantness seems to be a side effect of
<tt>\usepackage[T1]{fontenc}</tt>.
<p><blockquote><b>A.</b> 
Indeed.  We don't understand this behavior, but as an ill-understood
workaround, you can add
<pre>
\catcode`\-=\active
</pre>
to <tt>\def\setupcode</tt>, and things may work better.
</blockquote>





<h3><a name=toc5>Microsoft Madness</a></h3>
<b>Q.</b> Using the precompiled MS-DOS and Windows
binaries for noweb, many of the programs throw their
output to the screen and not to whatever receiving program/file they
ought to go to.  A typical example:  I go to /noweb/examples and type
<pre>
        notangle wc.nw > wc.c
</pre>
I see the tangled program scroll by on the screen, but it isn't piped to
the file wc.c as requested. 
Any solutions?

<p><blockquote><b>A.</b> 
This is a known COMMAND.COM problem. Try:
<pre>
        command /c notangle wc.nw > wc.c
</pre>
or get a COMMAND.COM replacement such as 4DOS.
Better yet, help with the <a href=todo3.html>noweb 3 port</a>.
</blockquote>

<p><b>Q.</b> 
For Windows 95/NT systems:
Why do I get the error message "This program cannot be run in DOS mode."
when I run some of the programs (including noweave.bat)?
<p><blockquote><b>A.</b> 
[Thanks to Chris Harris.]
The problem is that some of the files used in the noweb system (including
totex.exe and tohtml.exe used by noweave.bat) are written using an old
version of icon that uses a DOS extender which is incompatible with 95/NT.
The solution is to rebuild all of these files that were built using icon
source:
<ol>
<li>
Go get the console ICON executables for use on 95/NT.  They are the files
nticont.exe, nticonx.exe, noop.bat.  Put them in your noweb/bin directory.
<ol>
<li>The other two were available on the noweb ftp site, from the
FAQ, but noop.bat wasn't... it's availbe via FTP with the icon distribution,
but it's pretty easy to build yourself, it's contents are the single line:
<pre>
@rem this file prevents further batch processing after launching nticonx
</pre>
<li>So to build noop.bat, just type at the prompt "copy con
noop.bat<enter>" and then paste in the above line (starting with the @) hit
enter and ^Z and you're good to go.  Note: This file could really be empty,
the above line is a dos batch file comment, but you may want to put this in
there just so you remember in 2 years why you haven't deleted this file! :)
</ol>
<li>Get the noweb source distribution and extract just the icon files (i.e.
those located in the icon/ directory with a .icn extention)
<li>Build a batch file for each one using "nticont <filename>.icn"

<li>Copy all of the .bat files built in step #2 into your noweb/bin/
directory

<li>For each new .bat file you have in the bin directory, delete the
corresponding .exe file 
</ol>
Additionally, do NOT rename nticont to icont or nticonx to iconx.  The batch
files created with nticont REQUIRE nticonx to exist.  So if you rename it,
it'll get very confused.
</blockquote>



<h3><a name="toc6">Noweb and Emacs</a></h3>

<p><b>Q.</b>
Emacs noweb-mode is driving me crazy.  For example, I want 4-space tabs instead
of the usual 8.  I put this line in my file:
<pre>
% -*- mode: Noweb; noweb-code-mode: c-mode; tab-width: 4 -*-
</pre>
Or equivalently I do M-x set-variable tab-width 4.
Everything is fine until the cursor moves from one chunk to
another---then whammo!  Tabs are 8 spaces again.
What can I do??

<p><blockquote><b>A.</b>
If you have GNU emacs 20.4, or perhaps some other version, an
undocumented internal function of files.el will do what you want.
Try adding this to your ~/.emacs file:
<pre>
    (add-hook 'noweb-select-mode-hook
              '(lambda () (hack-local-variables-prop-line)))
</pre>
Thanks to Glenn Holloway for this discovery.
</blockquote>


<p><b>Q.</b>
Emacs noweb-mode is driving me crazy.
I&nbsp;want to use Tab or Ctl-J to handle indentation, but when I'm in the
middle of a code chunk, the indentation is wrong, and the cursor jumps
to a strange place.
How can I make emacs behave?
<p><blockquote><b>A.</b>
These symptoms indicate that perhaps emacs has lost track of the boundaries
between noweb chunks, perhaps material in documentation chunks is
confusing the auto-indenter, or perhaps both.
As of Emacs&nbsp;21 in 2008, you can now easily afford to fix these
problems using scary Emacs macros:
<pre>
  (defun my-newline-and-indent () 
    "Newline and indent that works better with noweb mode"
    (interactive "*")
    (if (and (boundp 'noweb-mode) noweb-mode)
        (save-restriction
          (noweb-update-chunk-vector)
          (noweb-narrow-to-chunk)
          (newline-and-indent))
        (newline-and-indent)))

  (defun my-tab-key () 
    "Tab that always tabs in Fundamental mode" (interactive)
    (if (string= "Fundamental" mode-name)
        (insert "\t")
      (if (and (boundp 'noweb-mode) noweb-mode)
          (save-restriction
            (noweb-update-chunk-vector)
            (noweb-narrow-to-chunk)
            (indent-for-tab-command))
        (indent-for-tab-command))))

  (defun use-my-indent-keys ()
    "Locally bind tab and ^J to keys that indent better" (interactive)
    (local-set-key "\t" 'my-tab-key)
    (local-set-key "\C-j" 'my-newline-and-indent))

  (add-hook 'noweb-select-code-mode-hook 'use-my-indent-keys)
</pre>
Add these to your <tt>.emacs</tt> file and perhaps the problem will go away.
Isn't Moore's law grand?
</blockquote>




<h3><a name=toc7>Other Questions</a></h3>

<b>Q.</b>  
What about noweb 3?

<p><blockquote><b>A.</b> 
  I use the <a href=nwalphacur.zip>alpha version</a>, which is alpha
  only because the new Hackers' Guide is not finished.
  But <strong>don't look for a release before I retire</strong>.
  Noweb&nbsp;3 is definitely an improvement over noweb&nbsp;2, but
  for most people, it's not <em>enough</em> of an improvement for me
  to go to the trouble of making a real release.
  Noweb&nbsp;3 
  was started in 1996(!) in response to situations that no longer
   obtain, and by 2000 it was substantially complete&mdash;the last
   significant revisions being done when I was first drafting my
   textbook.
   <p>
   Today performance is no longer an issue, and with Darwin and
   mingw/cygwin, portability is less of a concern as well.
   And with Lua 5.1 available, no sane person wants to use Lua 2.5.
   I&nbsp;believe that noweb&nbsp;3 no longer fills a need.
</blockquote><p>



<b>Q.</b>  
I compiled
and installed, and everything looks
OK, but when I ran the examples, two things do not work.
<ul>
<li>Noweave can not find definitions for 'C':
<pre>
noweave -index -autodefs c compress.nw > compress.tex
noweave: don't know how to find definitions for 'c'
</pre>
<li>Noweave can't find <tt>l2h</tt> for the <tt>-filter</tt>.
</ul>

<p><blockquote><b>A.</b> 
The awk library doesn't include all the filters that the Icon library
includes.  To get these extra features, you'll have to get <a
href=http://www.cs.arizona.edu/icon/>Icon</a> from 
the University of Arizona and re-install noweb using the Icon library.
</blockquote><p>

<b>Q.</b>  

I've been playing with LP, using noweb. I put related header, source and
test files into a single .nw file. But that means that if I make a change
in the source component, the header file is re-extracted, with the result
that many files which haven't actually changed are recompiled.
Any suggestions on simplifying the process?

<p><blockquote><b>A.</b> 
<pre>
notangle -Rheader foo.nw | cpif foo.h
</pre>
To understand why this works, see the <tt>cpif</tt> man page.
</blockquote><p>

<b>Q.</b>  What are these weird Makefile targets like install-preformat-man?
    Why is Makefile built from a .nw file?  Why is the Makefile so ugly?

<p><blockquote><b>A.</b>  Pay no attention to the man behind the curtain.  That's all
    trickery I use to build a Slackware-style package for Linux.

</blockquote><p><b>Q.</b> We often get an error from TeX asking us to have a wizard enlarge
   it, due to a line buffer overflow (the buffer is at 3000 bytes
   now).  This is truly annoying, since our wizard refuses to enlarge
   TeX, insisting there is a problem in our LaTeX macros or the Icon
   programs that generate them.  Unfortunately, that all comes straight
   from noweave.

<p><blockquote><b>A.</b>
Starting with web2c version 7,  you can increase the size up to 30000
in <tt>texmf.cnf</tt>. 
teTeX changed to a 30,000-byte line buffer starting in November, 1997,
so if you encounter this problem you should upgrade your TeX.
teTeX and web2c are both available from the <a
href=http://www.tug.org/>TeX User's Group</a>.
<p>

 Noweave emits very long lines on purpose, to preserve the desirable
   property that the source and TeX files have identical line numbers.
   This property guarantees that the line numbers in error messages
   from TeX refer to the lines of the source file, so that, for
   example, if TeX complains of an unknown control sequence on line 632,
   you can just refer to line 632 of your noweb file.
<p>
 Most very long lines are caused by long
   code chunks 
   containing lots of identifier definitions, so 
   if you cannot get a new TeX, you can
   fix the problem by adding more <<...>>= lines, which breaks up
   the big chunk into smaller chunks. 
 For example, instead of using a
   single chunk definition to define a large header file, use several:
<pre>
     &lt;&lt;alinfo.h>>=
     #define ...
     #define ...
       ...
     &lt;&lt;alinfo.h>>=
     #define ...
     #define ...
       ...
</pre>

</blockquote><p><b>Q.</b> I am trying to process multiple *.nw files independently of each
   other with noweb, only merging the *.tex files for the final
   documentation (using noindex and nodefs to produce cross
   references).  It seems that noweb uses the same labels (for TeX
   references) in different files. (The file names and the identifiers
   defined in these files are quite similar).

<p><blockquote><b>A.</b> Noweb uses the heuristic made famous by FORTH: names are reduced to
   the first three characters plus the length.  Changing your file names
   should be sufficient.  If you don't like that, you could use -filter
   with a sed script that adds a unique prefix to all the relevant labels
   (see the <a href=guide.html>Hacker's Guide</a> for info about where labels appear).

</blockquote><p><b>Q.</b> 
I have a problem with noweave's <code>-delay</code> option. It does not seem to prevent
 the program from inserting its information before the first chunk and after
 the last one.

<p><blockquote><b>A.</b> 
Put your first @ sign after the <code>\begin{document}</code> instead of at the
beginning of the file, and your last @ sign just before the
<code>\end{document}</code>.


</blockquote><p><b>Q.</b> How do I get an output file (root chunk) with an underscore in its name?
   LaTeX complains about the underscore.

<p><blockquote><b>A.</b> All chunk names are set in ordinary TeX mode.  This means that
   underscore is a subscript character.  Rather than use special
   hacks, I just avoid underscores in file names, since I prefer to
   use hyphens anyway.  However, you can write a simple sed script to
   filter the underscores for use by noweave:
<pre>
      noweave -filter 'sed "/^@use /s/_/\\\\_/g;/^@defn /s/_/\\\\_/g"'
</pre>
   and the filter will change _ to \_ before TeX sees it.


</blockquote><p><b>Q.</b> Having used nuweb2noweb on a nuweb file which uses @i to include
   other files I find that the resulting noweb file is enormous
   because the included files are written directly into the noweb
   file. How do I emulate nuweb's @i with noweb?

<p><blockquote><b>A.</b> The short answer is it can't be done.  (Some would say that it
   doesn't <em>need</em> to be done, because notangle and noweave can accept
   multiple files on the command line.)  The long answer is that you
   can usually use LaTeX's \include or \input commands and keep the
   noweb files separate.  If you actually need to tangle all those
   files together (as opposed to just weaving them), you can usually
   mention all the names on the command line: 
<pre>
      notangle foo.nw bar.nw quux.nw > big.out
</pre>

</blockquote><p><b>Q.</b> I have a problem with typesetting Mathematica's double-bracketed
  subscripting command using <code>[[</code>...<code>]]</code>
  in my documentation chunks.
noweb considers <code>[[a[[#]]&amp;]]</code> to mean the symbols <code>a[[#</code> in 
typewriter and then latex gets stuck on the offending <code>&amp;</code> character.
How can I get around this problem?

<p><blockquote><b>A.</b>
Split the quoted code into two
pieces, which you write consecutively, thus:
<blockquote>
  <code>[[a[[#]]]][[&amp;]]</code>
</blockquote>




</blockquote><p><b>Q.</b> Why is the <tt>noweb</tt> command so slow?


<p><blockquote><b>A.</b> It's expensive to create a TeX file, so
<pre>noweb foo</pre>
is probably at least 5 times slower than
<pre>noweb -t foo</pre>
and in an edit/compile/debug cycle you may not need the docs and can
   use the faster form.
</blockquote>

<p><b>Q.</b>  What is the origin of the ``no'' prefix in <tt>noweb</tt> ?

<p><blockquote><b>A.</b>
I wrote <tt>noweb</tt> at a time when language-dependent webs were
proliferating, e.g., adaweb, cweb, mweb, etc.  So the "no" in <tt>noweb</tt> is
a triple pun:
<ul>
<li>A language-independent web, not limited to one programming
      language, hence web for no particular language or `<tt>noweb</tt>'.
<li>A contraction of `Norman's web'
<li>The third part of the pun is not suitable for publication.
</ul>
</blockquote>

<p><b>Q.</b>
Norman, what made you choose <a href=http://www.lua.org/>Lua</a> as the
implementation language for Noweb&nbsp;3, rather
than, say, Python? 
<p><blockquote><b>A.</b>
Lua is small and simple.  I wanted not to be vulnerable to future
changes in language definitions or implementations, which meant I
would have to clone and maintain the implementation forever. When I
was making this decision in 1997, Lua&nbsp;2.5 was small enough that I
could feel comfortable doing this.
</blockquote>


<p><b>Q.</b>
    Are there noweb comments?
 It would be very useful to comment parts of a noweb file that wouldn't 
 be parsed as either TeX or code.
<p><blockquote><b>A.</b>
I recommend that you put comments in specially named chunks and use
    the <tt>elide</tt> filter that comes with the distribution.
For example, if the name of each comment chunk begins with
<tt>comment:</tt>, you could run
<blockquote>
<pre>
noweave -filter elide comment:* ...
</pre>
</blockquote>
(Because chunks that are not used are ignored, there would be no need
    to <tt>elide</tt> when tangling.)
</blockquote>

</body></html>