Fix modes tracking
[newfangle.git] / fangle.tm
blobfce0cd08ad346f17d3089aee070d587586bc28f7
1 <TeXmacs|1.0.7.10>
3 <style|<tuple|book|fangle|header-book|tmdoc-keyboard>>
5 <\body>
6   <hide-preamble|<assign|LyX|<macro|L<space|-0.1667em><move|Y|0fn|-0.25em><space|-0.125em>X>><assign|par-first|0fn><assign|par-par-sep|0.5fn>>
8   <doc-data|<doc-title|fangle>|<doc-author-data|<author-name|Sam
9   Liddicott>|<\author-address>
10     sam@liddicott.com
11   </author-address>>|<doc-date|August 2009>>
13   <section*|Introduction>
15   <name|Fangle> is a tool for fangled literate programming. Newfangled is
16   defined as <em|New and often needlessly novel> by
17   <name|TheFreeDictionary.com>.
19   In this case, fangled means yet another not-so-new<footnote|but improved.>
20   method for literate programming.
22   <name|Literate Programming> has a long history starting with the great
23   <name|Donald Knuth> himself, whose literate programming tools seem to make
24   use of as many escape sequences for semantic markup as <TeX> (also by
25   <name|Donald Knuth>).
27   <name|Norman Ramsey> wrote the <name|Noweb> set of tools
28   (<verbatim|notangle>, <verbatim|noweave> and <verbatim|noroots>) and
29   helpfully reduced the amount of magic character sequences to pretty much
30   just <verbatim|\<less\>\<less\>>, <verbatim|\<gtr\>\<gtr\>> and
31   <verbatim|@>, and in doing so brought the wonders of literate programming
32   within my reach.
34   While using the <LyX> editor for <LaTeX> editing I had various troubles
35   with the noweb tools, some of which were my fault, some of which were
36   noweb's fault and some of which were <LyX>'s fault.
38   <name|Noweb> generally brought literate programming to the masses through
39   removing some of the complexity of the original literate programming, but
40   this would be of no advantage to me if the <LyX> / <LaTeX> combination
41   brought more complications in their place.
43   <name|Fangle> was thus born (originally called <name|Newfangle>) as an awk
44   replacement for notangle, adding some important features, like better
45   integration with <LyX> and <LaTeX> (and later <TeXmacs>), multiple output
46   format conversions, and fixing notangle bugs like indentation when using -L
47   for line numbers.
49   Significantly, fangle is just one program which replaces various programs
50   in <name|Noweb>. Noweave is done away with and implemented directly as
51   <LaTeX> macros, and noroots is implemented as a function of the untangler
52   fangle.
54   Fangle is written in awk for portability reasons, awk being available for
55   most platforms. A Python version<\footnote>
56     hasn't anyone implemented awk in python yet?
57   </footnote> was considered for the benefit of <LyX> but a scheme version
58   for <TeXmacs> will probably materialise first; as <TeXmacs> macro
59   capabilities help make edit-time and format-time rendering of fangle chunks
60   simple enough for my weak brain.
62   As an extension to many literate-programming styles, Fangle permits code
63   chunks to take parameters and thus operate somewhat like C pre-processor
64   macros, or like C++ templates. Name parameters (or even local
65   <em|variables> in the callers scope) are anticipated, as parameterized
66   chunks <emdash> useful though they are <emdash> are hard to comprehend in
67   the literate document.
69   <section*|License><new-page*><label|License>
71   Fangle is licensed under the GPL 3 (or later).
73   This doesn't mean that sources generated by fangle must be licensed under
74   the GPL 3.
76   This doesn't mean that you can't use or distribute fangle with sources of
77   an incompatible license, but it means you must make the source of fangle
78   available too.
80   As fangle is currently written in awk, an interpreted language, this should
81   not be too hard.
83   <\nf-chunk|gpl3-copyright>
84     <item>fangle - fully featured notangle replacement in awk
86     <item>
88     <item>Copyright (C) 2009-2010 Sam Liddicott
89     \<less\>sam@liddicott.com\<gtr\>
91     <item>
93     <item>This program is free software: you can redistribute it and/or
94     modify
96     <item>it under the terms of the GNU General Public License as published
97     by
99     <item>the Free Software Foundation, either version 3 of the License, or
101     <item>(at your option) any later version.
103     <item>
105     <item>This program is distributed in the hope that it will be useful,
107     <item>but WITHOUT ANY WARRANTY; without even the implied warranty of
109     <item>MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. \ See the
111     <item>GNU General Public License for more details.
113     <item>
115     <item>You should have received a copy of the GNU General Public License
117     <item>along with this program. \ If not, see
118     \<less\>http://www.gnu.org/licenses/\<gtr\>.
119   </nf-chunk|text|>
121   <\table-of-contents|toc>
122   </table-of-contents>
124   <part|Using Fangle>
126   <chapter|Introduction to Literate Programming>
128   Todo: Should really follow on from a part-0 explanation of what literate
129   programming is.
131   <chapter|Running Fangle>
133   Fangle is a replacement for <name|noweb>, which consists of
134   <verbatim|notangle>, <verbatim|noroots> and <verbatim|noweave>.
136   Like <verbatim|notangle> and <verbatim|noroots>, <verbatim|fangle> can read
137   multiple named files, or from stdin.
139   <section|Listing roots>
141   The -r option causes fangle to behave like noroots.
143   <code*|fangle -r filename.tex>
145   will print out the fangle roots of a tex file.\ 
147   Unlike the <verbatim|noroots> command, the printed roots are not enclosed
148   in angle brackets e.g. <verbatim|\<less\>\<less\>name\<gtr\>\<gtr\>>,
149   unless at least one of the roots is defined using the <verbatim|notangle>
150   notation <verbatim|\<less\>\<less\>name\<gtr\>\<gtr\>=>.
152   Also, unlike noroots, it prints out all roots --- not just those that are
153   not used elsewhere. I find that a root not being used doesn't make it
154   particularly top level <emdash> and so-called top level roots could also be
155   included in another root as well.\ 
157   My convention is that top level roots to be extracted begin with
158   <verbatim|./> and have the form of a filename.
160   Makefile.inc, discussed in <reference|makefile.inc>, can automatically
161   extract all such sources prefixed with <verbatim|./>
163   <section|Extracting roots>
165   notangle's <verbatim|-R> and <verbatim|-L> options are supported.
167   If you are using <LyX> or <LaTeX>, the standard way to extract a file would
168   be:
170   <verbatim|fangle -R./Makefile.inc fangle.tex \<gtr\> ./Makefile.inc>
172   If you are using <TeXmacs>, the standard way to extract a file would
173   similarly be:
175   <verbatim|fangle -R./Makefile.inc fangle.txt \<gtr\> ./Makefile.inc>
177   <TeXmacs> users would obtain the text file with a <em|verbatim> export from
178   <TeXmacs> which can be done on the command line with <verbatim|texmacs -s
179   -c fangle.tm fangle.txt -q>
181   Unlike the <verbatim|noroots> command, the <verbatim|<verbatim|-L>> option
182   to generate C pre-preocessor <verbatim|#file> style line-number
183   directives,does not break indenting of the generated file..
185   Also, thanks to mode tracking (described in <reference|modes>) the
186   <verbatim|-L> option does not interrupt (and break) multi-line C macros
187   either.
189   This does mean that sometimes the compiler might calculate the source line
190   wrongly when generating error messages in such cases, but there isn't any
191   other way around if multi-line macros include other chunks.
193   Future releases will include a mapping file so that line/character
194   references from the C compiler can be converted to the correct part of the
195   source document.
197   <section|Formatting the document>
199   The noweave replacement built into the editing and formatting environment
200   for <TeXmacs>, <LyX> (which uses <LaTeX>), and even for raw <LaTeX>.
202   Use of fangle with <TeXmacs>, <LyX> and <LaTeX> are explained the the next
203   few chapters.
205   <chapter|Using Fangle with <LaTeX>>
207   Because the noweave replacement is impemented in <LaTeX>, there is no
208   processing stage required before running the <LaTeX> command. Of course,
209   <LaTeX> may need running two or more times, so that the code chunk
210   references can be fully calculated.
212   The formatting is managed by a set of macros shown in
213   <reference|latex-source>, and can be included with:
215   <verbatim|\\usepackage{fangle.sty}>
217   Norman Ramsay's origial <filename|noweb.sty> package is currently required
218   as it is used for formatting the code chunk captions.
220   The <filename|listings.sty> package is required, and is used for formatting
221   the code chunks and syntax highlighting.
223   The <filename|xargs.sty> package is also required, and makes writing
224   <LaTeX> macro so much more pleasant.
226   <todo|Add examples of use of Macros>
228   <chapter|Using Fangle with <LyX>>
230   <LyX> uses the same <LaTeX> macros shown in <reference|latex-source> as
231   part of a <LyX> module file <filename|fangle.module>, which automatically
232   includes the macros in the document pre-amble provided that the fangle
233   <LyX> module is used in the document.
235   <section|Installing the <LyX> module>
237   Copy <filename|fangle.module> to your <LyX> layouts directory, which for
238   unix users will be <filename|~/.lyx/layouts>
240   In order to make the new literate styles availalble, you will need to
241   reconfigure <LyX> by clicking Tools-\<gtr\>Reconfigure, and then re-start
242   <LyX>.
244   <section|Obtaining a decent mono font>
246   The syntax high-lighting features of <name|lstlistings> makes use of bold;
247   however a mono-space tt font is used to typeset the listings. Obtaining a
248   <with|font-family|tt|<strong|bold> tt font> can be impossibly difficult and
249   amazingly easy. I spent many hours at it, following complicated
250   instructions from those who had spend many hours over it, and was finally
251   delivered the simple solution on the lyx mailing list.
253   <subsection|txfonts>
255   The simple way was to add this to my preamble:
257   <\verbatim>
258     \\usepackage{txfonts}
260     \\renewcommand{\\ttdefault}{txtt}
261   </verbatim>
263   \;
265   <subsection|ams pmb>
267   The next simplest way was to use ams poor-mans-bold, by adding this to the
268   pre-amble:
270   <\verbatim>
271     \\usepackage{amsbsy}
273     %\\renewcommand{\\ttdefault}{txtt}
275     %somehow make \\pmb be the command for bold, forgot how, sorry, above
276     line not work
277   </verbatim>
279   It works, but looks wretched on the dvi viewer.
281   <subsection|Luximono>
283   The lstlistings documention suggests using Luximono.
285   Luximono was installed according to the instructions in Ubuntu Forums
286   thread 1159181<\footnote>
287     http://ubuntuforums.org/showthread.php?t=1159181
288   </footnote> with tips from miknight<\footnote>
289     http://miknight.blogspot.com/2005/11/how-to-install-luxi-mono-font-in.html
290   </footnote> stating that <verbatim|sudo updmap --enable MixedMap ul9.map>
291   is required. It looks fine in PDF and PS view but still looks rotten in dvi
292   view.
294   <section|Formatting your Lyx document>
296   It is not necessary to base your literate document on any of the original
297   <LyX> literate classes; so select a regular class for your document type.
299   Add the new module <em|Fangle Literate Listings> and also <em|Logical
300   Markup> which is very useful.
302   In the drop-down style listbox you should notice a new style defined,
303   called <em|Chunk>.
305   When you wish to insert a literate chunk, you enter it's plain name in the
306   Chunk style, instead of the old <name|noweb> method that uses
307   <verbatim|\<less\>\<less\>name\<gtr\>\<gtr\>=> type tags. In the line (or
308   paragraph) following the chunk name, you insert a listing with:
309   Insert-\<gtr\>Program Listing.
311   Inside the white listing box you can type (or paste using
312   <kbd|shift+ctrl+V>) your listing. There is no need to use <kbd|ctrl+enter>
313   at the end of lines as with some older <LyX> literate techniques --- just
314   press enter as normal.
316   <subsection|Customising the listing appearance>
318   The code is formatted using the <name|lstlistings> package. The chunk style
319   doesn't just define the chunk name, but can also define any other chunk
320   options supported by the lstlistings package <verbatim|\\lstset> command.
321   In fact, what you type in the chunk style is raw latex. If you want to set
322   the chunk language without having to right-click the listing, just add
323   <verbatim|,lanuage=C> after the chunk name. (Currently the language will
324   affect all subsequent listings, so you may need to specify
325   <verbatim|,language=> quite a lot).
327   <todo|so fix the bug>
329   Of course you can do this by editing the listings box advanced properties
330   by right-clicking on the listings box, but that takes longer, and you can't
331   see at-a-glance what the advanced settings are while editing the document;
332   also advanced settings apply only to that box --- the chunk settings apply
333   through the rest of the document<\footnote>
334     It ought to apply only to subsequent chunks of the same name. I'll fix
335     that later
336   </footnote>.
338   <todo|So make sure they only apply to chunks of that name>
340   <subsection|Global customisations>
342   As lstlistings is used to set the code chunks, it's <verbatim|\\lstset>
343   command can be used in the pre-amble to set some document wide settings.
345   If your source has many words with long sequences of capital letters, then
346   <verbatim|columns=fullflexible> may be a good idea, or the capital letters
347   will get crowded. (I think lstlistings ought to use a slightly smaller font
348   for captial letters so that they still fit).
350   The font family <verbatim|\\ttfamily> looks more normal for code, but has
351   no bold (an alternate typewriter font is used).\ 
353   With <verbatim|\\ttfamily>, I must also specify
354   <verbatim|columns=fullflexible> or the wrong letter spacing is used.
356   In my <LaTeX> pre-amble I usually specialise my code format with:
358   <\nf-chunk|document-preamble>
359     <item>\\lstset{
361     <item>numbers=left, stepnumber=1, numbersep=5pt,
363     <item>breaklines=false,
365     <item>basicstyle=\\footnotesize\\ttfamily,
367     <item>numberstyle=\\tiny,
369     <item>language=C,
371     <item>columns=fullflexible,
373     <item>numberfirstline=true
375     <item>}
376   </nf-chunk|tex|>
378   \;
380   <section|Configuring the build script>
382   You can invoke code extraction and building from the <LyX> menu option
383   Document-\<gtr\>Build Program.
385   First, make sure you don't have a conversion defined for Lyx-\<gtr\>Program
387   From the menu Tools-\<gtr\>Preferences, add a conversion from
388   Latex(Plain)-\<gtr\>Program as:
390   <\verbatim>
391     set -x ; fangle -Rlyx-build $$i \|\ 
393     \ \ env LYX_b=$$b LYX_i=$$i LYX_o=$$o LYX_p=$$p LYX_r=$$r bash
394   </verbatim>
396   (But don't cut-n-paste it from this document or you may be be pasting a
397   multi-line string which will break your lyx preferences file).\ 
399   I hope that one day, <LyX> will set these into the environment when calling
400   the build script.
402   You may also want to consider adding options to this conversion...
404   <verbatim|parselog=/usr/share/lyx/scripts/listerrors>
406   ...but if you do you will lose your stderr<\footnote>
407     There is some bash plumbing to get a copy of stderr but this footnote is
408     too small
409   </footnote>.
411   Now, a shell script chunk called <filename|lyx-build> will be extracted and
412   run whenever you choose the Document-\<gtr\>Build Program menu item.
414   This document was originally managed using <LyX> and lyx-build script for
415   this document is shown here for historical reference.\ 
417   <\verbatim>
418     lyx -e latex fangle.lyx && \\
420     \ \ fangle fangle.lyx \<gtr\> ./autoboot
421   </verbatim>
423   This looks simple enough, but as mentioned, fangle has to be had from
424   somewhere before it can be extracted.
426   <subsection|...>
428   When the lyx-build chunk is executed, the current directory will be a
429   temporary directory, and <verbatim|LYX_SOURCE> will refer to the tex file
430   in this temporary directory. This is unfortunate as our makefile wants to
431   run from the project directory where the Lyx file is kept.
433   We can extract the project directory from <verbatim|$$r>, and derive the
434   probable Lyx filename from the noweb file that Lyx generated.
436   <\nf-chunk|lyx-build-helper>
437     <item>PROJECT_DIR="$LYX_r"
439     <item>LYX_SRC="$PROJECT_DIR/${LYX_i%.tex}.lyx"
441     <item>TEX_DIR="$LYX_p"
443     <item>TEX_SRC="$TEX_DIR/$LYX_i"
444   </nf-chunk|sh|>
446   And then we can define a lyx-build fragment similar to the autoboot
447   fragment
449   <\nf-chunk|lyx-build>
450     <item>#! /bin/sh
452     <item>=\<less\>\\chunkref{lyx-build-helper}\<gtr\>
454     <item>cd $PROJECT_DIR \|\| exit 1
456     <item>
458     <item>#/usr/bin/fangle -filter ./notanglefix-filter \\
460     <item># \ -R./Makefile.inc "../../noweb-lyx/noweb-lyx3.lyx" \\
462     <item># \ \| sed '/NOWEB_SOURCE=/s/=.*/=samba4-dfs.lyx/' \\
464     <item># \ \<gtr\> ./Makefile.inc
466     <item>#
468     <item>#make -f ./Makefile.inc fangle_sources
469   </nf-chunk|sh|>
471   \;
473   <chapter|Using Fangle with <TeXmacs>>
475   <todo|Write this chapter>
477   <chapter|Fangle with Makefiles><label|makefile.inc>
479   Here we describe a <filename|Makefile.inc> that you can include in your own
480   Makefiles, or glue as a recursive make to other projects.
482   <filename|Makefile.inc> will cope with extracting all the other source
483   files from this or any specified literate document and keeping them up to
484   date.\ 
486   It may also be included by a <verbatim|Makefile> or <verbatim|Makefile.am>
487   defined in a literate document to automatically deal with the extraction of
488   source files and documents during normal builds.
490   Thus, if <verbatim|Makefile.inc> is included into a main project makefile
491   it add rules for the source files, capable of extracting the source files
492   from the literate document.
494   <section|A word about makefiles formats>
496   Whitespace formatting is very important in a Makefile. The first character
497   of each action line must be a TAB.\ 
499   <\verbatim>
500     target: pre-requisite
502     <nf-tab>action
504     <nf-tab>action
505   </verbatim>
507   This requires that the literate programming environment have the ability to
508   represent a TAB character in a way that fangle will generate an actual TAB
509   character.
511   We also adopt a convention that code chunks whose names beginning with
512   <verbatim|./> should always be automatically extracted from the document.
513   Code chunks whose names do not begin with <verbatim|./> are for internal
514   reference. Such chunks may be extracted directly, but will not be
515   automatically extracted by this Makefile.
517   <section|Extracting Sources>
519   Our makefile has two parts; variables must be defined before the targets
520   that use them.
522   As we progress through this chapter, explaining concepts, we will be adding
523   lines to <nf-ref|Makefile.inc-vars|> and <nf-ref|Makefile.inc-targets|>
524   which are included in <nf-ref|./Makefile.inc|> below.
526   <\nf-chunk|./Makefile.inc>
527     <item><nf-ref|Makefile.inc-vars|>
529     <item><nf-ref|Makefile.inc-targets|>
530   </nf-chunk|make|>
532   We first define a placeholder for <verbatim|LITERATE_SOURCE> to hold the
533   name of this document. This will normally be passed on the command line.
535   <\nf-chunk|Makefile.inc-vars>
536     <item>LITERATE_SOURCE=
537   </nf-chunk||>
539   Fangle cannot process <LyX> or <TeXmacs> documents directly, so the first
540   stage is to convert these to more suitable text based formats<\footnote>
541     <LyX> and <TeXmacs> formats are text-based, but not suitable for fangle
542   </footnote>.
544   <subsection|Converting from <LyX> to <LaTeX>><label|Converting-from-Lyx>
546   The first stage will always be to convert the <LyX> file to a <LaTeX> file.
547   Fangle must run on a <TeX> file because the <LyX> command
548   <verbatim|server-goto-file-line><\footnote>
549     The Lyx command <verbatim|server-goto-file-line> is used to position the
550     Lyx cursor at the compiler errors.
551   </footnote> requries that the line number provided be a line of the <TeX>
552   file and always maps this the line in the <LyX> docment. We use
553   <verbatim|server-goto-file-line> when moving the cursor to error lines
554   during compile failures.
556   The command <verbatim|lyx -e literate fangle.lyx> will produce
557   <verbatim|fangle.tex>, a <TeX> file; so we define a make target to be the
558   same as the <LyX> file but with the <verbatim|.tex> extension.
560   The <verbatim|EXTRA_DIST> is for automake support so that the <TeX> files
561   will automaticaly be distributed with the source, to help those who don't
562   have <LyX> installed.
564   <\nf-chunk|Makefile.inc-vars>
565     <item>TEX_SOURCE=$(LYX_SOURCE:.lyx=.tex)
567     <item>EXTRA_DIST+=$(TEX_SOURCE)
568   </nf-chunk||>
570   We then specify that the <TeX> source is to be generated from the <LyX>
571   source.
573   <\nf-chunk|Makefile.inc-targets>
574     <item>$(TEX_SOURCE): $(LYX_SOURCE)
576     <item><nf-tab>lyx -e latex $\<less\>
578     <item>clean_tex:
580     <item><nf-tab>rm -f -- $(TEX_SOURCE)
582     <item>clean: clean_tex
583   </nf-chunk||>
585   <subsection|Converting from <TeXmacs>><label|Converting-from-Lyx>
587   Fangle cannot process <TeXmacs> files directly<\footnote>
588     but this is planned when <TeXmacs> uses xml as it's native format
589   </footnote>, but must first convert them to text files.
591   The command <verbatim|texmacs -c fangle.tm fangle.txt -q> will produce
592   <verbatim|fangle.txt>, a text file; so we define a make target to be the
593   same as the <TeXmacs> file but with the <verbatim|.txt> extension.
595   The <verbatim|EXTRA_DIST> is for automake support so that the <TeX> files
596   will automaticaly be distributed with the source, to help those who don't
597   have <LyX> installed.
599   <\nf-chunk|Makefile.inc-vars>
600     <item>TXT_SOURCE=$(LITERATE_SOURCE:.tm=.txt)
602     <item>EXTRA_DIST+=$(TXT_SOURCE)
603   </nf-chunk||>
605   <todo|Add loop around each $\<less\> so multiple targets can be specified>
607   <\nf-chunk|Makefile.inc-targets>
608     <item>$(TXT_SOURCE): $(LITERATE_SOURCE)
610     <item><nf-tab>texmacs -c $\<less\> $(TXT_SOURCE) -q
612     <item>clean_txt:
614     <item><nf-tab>rm -f -- $(TXT_SOURCE)
616     <item>clean: clean_txt
617   </nf-chunk||>
619   <section|Extracting Program Source>
621   The program source is extracted using fangle, which is designed to operate
622   on text or a <LaTeX> documents<\footnote>
623     <LaTeX> documents are just slightly special text documents
624   </footnote>.
626   <\nf-chunk|Makefile.inc-vars>
627     <item>FANGLE_SOURCE=$(TEX_SOURCE) $(TXT_SOURCE)
628   </nf-chunk||>
630   The literate document can result in any number of source files, but not all
631   of these will be changed each time the document is updated. We certainly
632   don't want to update the timestamps of these files and cause the whole
633   source tree to be recompiled just because the literate explanation was
634   revised. We use <verbatim|CPIF> from the <em|Noweb> tools to avoid updating
635   the file if the content has not changed, but should probably write our own.
637   However, if a source file is not updated, then the fangle file will always
638   have a newer time-stamp and the makefile would always re-attempt to extact
639   a newer source file which would be a waste of time.
641   Because of this, we use a stamp file which is always updated each time the
642   sources are fully extracted from the <LaTeX> document. If the stamp file is
643   newer than the document, then we can avoid an attempt to re-extract any of
644   the sources. Because this stamp file is only updated when extraction is
645   complete, it is safe for the user to interrupt the build-process
646   mid-extraction.
648   We use <verbatim|echo> rather than <verbatim|touch> to update the stamp
649   file beause the <verbatim|touch> command does not work very well over an
650   <verbatim|sshfs>mount \ that I was using.
652   <\nf-chunk|Makefile.inc-vars>
653     <item>FANGLE_SOURCE_STAMP=$(FANGLE_SOURCE).stamp
654   </nf-chunk||>
656   <\nf-chunk|Makefile.inc-targets>
657     <item>$(FANGLE_SOURCE_STAMP): $(FANGLE_SOURCE) \\
659     <item><nf-tab> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $(FANGLE_SOURCES) ; \\
661     <item><nf-tab>echo -n \<gtr\> $(FANGLE_SOURCE_STAMP)
663     <item>clean_stamp:
665     <item><nf-tab>rm -f $(FANGLE_SOURCE_STAMP)
667     <item>clean: clean_stamp
668   </nf-chunk||>
670   <section|Extracting Source Files>
672   We compute <verbatim|FANGLE_SOURCES> to hold the names of all the source
673   files defined in the document. We compute this only once, by means of
674   <verbatim|:=> in assignent. The sed deletes the any
675   <verbatim|\<less\>\<less\>> and <verbatim|\<gtr\>\<gtr\>> which may
676   surround the roots names (for compatibility with Noweb's noroots command).
678   As we use chunk names beginning with <filename|./> to denote top level
679   fragments that should be extracted, we filter out all fragments that do not
680   begin with <filename|./>
682   <\note>
683     <verbatim|FANGLE_PREFIX> is set to <verbatim|./> by default, but whatever
684     it may be overridden to, the prefix is replaced by a literal
685     <verbatim|./> before extraction so that files will be extracted in the
686     current directory whatever the prefix. This helps namespace or
687     sub-project prefixes like <verbatim|documents:> for chunks like
688     <verbatim|documents:docbook/intro.xml>
689   </note>
691   <todo|This doesn't work though, because it loses the full name and doesn't
692   know what to extact!>
694   <\nf-chunk|Makefile.inc-vars>
695     <item>FANGLE_PREFIX:=\\.\\/
697     <item>FANGLE_SOURCES:=$(shell \\
699     <item> \ fangle -r $(FANGLE_SOURCE) \|\\
701     <item> \ sed -e 's/^[\<less\>][\<less\>]//;s/[\<gtr\>][\<gtr\>]$$//;/^$(FANGLE_PREFIX)/!d'
702     \\
704     <item> \ \ \ \ \ -e 's/^$(FANGLE_PREFIX)/\\.\\//' )
705   </nf-chunk||>
707   The target below, <verbatim|echo_fangle_sources> is a helpful debugging
708   target and shows the names of the files that would be extracted.
710   <\nf-chunk|Makefile.inc-targets>
711     <item>.PHONY: echo_fangle_sources
713     <item>echo_fangle_sources: ; @echo $(FANGLE_SOURCES)
714   </nf-chunk||>
716   We define a convenient target called <verbatim|fangle_sources> so that
717   <verbatim|make -f fangle_sources> will re-extract the source if the
718   literate document has been updated.\ 
720   <\nf-chunk|Makefile.inc-targets>
721     <item>.PHONY: fangle_sources
723     <item>fangle_sources: $(FANGLE_SOURCE_STAMP)
724   </nf-chunk||>
726   And also a convenient target to remove extracted sources.
728   <\nf-chunk|Makefile.inc-targets>
729     <item>.PHONY: clean_fangle_sources
731     <item>clean_fangle_sources: ; \\
733     <item> \ \ \ \ \ \ \ rm -f -- $(FANGLE_SOURCE_STAMP) $(FANGLE_SOURCES)
734   </nf-chunk||>
736   We now look at the extraction of the source files.
738   This makefile macro <verbatim|if_extension> takes 4 arguments: the filename
739   <verbatim|$(1)>, some extensions to match <verbatim|$(2)> and a shell
740   command to return if the filename does match the exensions <verbatim|$(3)>,
741   and a shell command to return if it does not match the extensions
742   <verbatim|$(4)>.
744   <\nf-chunk|Makefile.inc-vars>
745     <item>if_extension=$(if $(findstring $(suffix $(1)),$(2)),$(3),$(4))
746   </nf-chunk||>
748   For some source files like C files, we want to output the line number and
749   filename of the original <LaTeX> document from which the source
750   came<\footnote>
751     I plan to replace this option with a separate mapping file so as not to
752     pollute the generated source, and also to allow a code pretty-printing
753     reformatter like <verbatim|indent> be able to re-format the file and
754     adjust for changes through comparing the character streams.
755   </footnote>.
757   To make this easier we define the file extensions for which we want to do
758   this.
760   <\nf-chunk|Makefile.inc-vars>
761     <item>C_EXTENSIONS=.c .h
762   </nf-chunk||>
764   We can then use the <verbatim|if_extensions> macro to define a macro which
765   expands out to the <verbatim|-L> option if fangle is being invoked in a C
766   source file, so that C compile errors will refer to the line number in the
767   <TeX> document.\ 
769   <\nf-chunk|Makefile.inc-vars>
770     <item>TABS=8
772     <item>nf_line=-L -T$(TABS)
774     <item>fangle=fangle $(call if_extension,$(2),$(C_EXTENSIONS),$(nf_line))
775     -R"$(2)" $(1)
776   </nf-chunk||>
778   We can use a similar trick to define an indent macro which takes just the
779   filename as an argument and can return a pipeline stage calling the indent
780   command. Indent can be turned off with <verbatim|make fangle_sources
781   indent=>
783   <\nf-chunk|Makefile.inc-vars>
784     <item>indent_options=-npro -kr -i8 -ts8 -sob -l80 -ss -ncs
786     <item>indent=$(call if_extension,$(1),$(C_EXTENSIONS), \| indent
787     $(indent_options))
788   </nf-chunk||>
790   We now define the pattern for extracting a file. The files are written
791   using noweb's <verbatim|cpif> so that the file timestamp will not be
792   touched if the contents haven't changed. This avoids the need to rebuild
793   the entire project because of a typographical change in the documentation,
794   or if none or a few C source files have changed.
796   <\nf-chunk|Makefile.inc-vars>
797     <item>fangle_extract=@mkdir -p $(dir $(1)) && \\
799     <item> \ $(call fangle,$(2),$(1)) \<gtr\> "$(1).tmp" && \\
801     <item> \ cat "$(1).tmp" $(indent) \| cpif "$(1)" \\
803     <item> \ && rm -- "$(1).tmp" \|\| \\
805     <item> \ (echo error newfangling $(1) from $(2) ; exit 1)
806   </nf-chunk||>
808   We define a target which will extract or update all sources. To do this we
809   first defined a makefile template that can do this for any source file in
810   the <LaTeX> document.
812   <\nf-chunk|Makefile.inc-vars>
813     <item>define FANGLE_template
815     <item> \ $(1): $(2)
817     <item><nf-tab>$$(call fangle_extract,$(1),$(2))
819     <item> \ FANGLE_TARGETS+=$(1)
821     <item>endef
822   </nf-chunk||>
824   We then enumerate the discovered <verbatim|FANGLE_SOURCES> to generate a
825   makefile rule for each one using the makefile template we defined above.
827   <\nf-chunk|Makefile.inc-targets>
828     <item>$(foreach source,$(FANGLE_SOURCES),\\
830     <item> \ $(eval $(call FANGLE_template,$(source),$(FANGLE_SOURCE))) \\
832     <item>)
833   </nf-chunk||>
835   These will all be built with <verbatim|FANGLE_SOURCE_STAMP>.
837   We also remove the generated sources on a make distclean.
839   <\nf-chunk|Makefile.inc-targets>
840     <item>_distclean: clean_fangle_sources
841   </nf-chunk||>
843   <section|Extracting Documentation>
845   We then identify the intermediate stages of the documentation and their
846   build and clean targets.
848   <subsection|Formatting <TeX>>
850   <subsubsection|Running pdflatex>
852   We produce a pdf file from the tex file.
854   <\nf-chunk|Makefile.inc-vars>
855     <item>FANGLE_PDF=$(TEX_SOURCE:.tex=.pdf)
856   </nf-chunk||>
858   We run pdflatex twice to be sure that the contents and aux files are up to
859   date. We certainly are <em|required> to run pdflatex at least twice if
860   these files do not exist.
862   <\nf-chunk|Makefile.inc-targets>
863     <item>$(FANGLE_PDF): $(TEX_SOURCE)
865     <item><nf-tab>pdflatex $\<less\> && pdflatex $\<less\>
867     <item>
869     <item>clean_pdf:
871     <item><nf-tab>rm -f -- $(FANGLE_PDF) $(TEX_SOURCE:.tex=.toc) \\
873     <item><nf-tab> \ $(TEX_SOURCE:.tex=.log) $(TEX_SOURCE:.tex=.aux)
874   </nf-chunk||>
876   <subsection|Formatting <TeXmacs>>
878   <TeXmacs> can produce a PDF file directly.
880   <\nf-chunk|Makefile.inc-vars>
881     <item>FANGLE_PDF=$(TEX_SOURCE:.tm=.pdf)
882   </nf-chunk||>
884   <\todo>
885     Outputting the PDF may not be enough to update the links and page
886     references. I think
888     we need to update twice, generate a pdf, update twice mode and generate a
889     new PDF.
891     Basically the PDF export of <TeXmacs> is pretty rotten and doesn't work
892     properly from the CLI
893   </todo>
895   <\nf-chunk|Makefile.inc-targets>
896     <item>$(FANGLE_PDF): $(TEXMACS_SOURCE)
898     <item><nf-tab>texmacs -c $(TEXMACS_SOURCE) $\<less\> -q
900     <item>
902     <item>clean_pdf:
904     <item><nf-tab>rm -f -- $(FANGLE_PDF)
905   </nf-chunk||>
907   <subsection|Building the Documentation as a Whole>
909   Currently we only build pdf as a final format, but <verbatim|FANGLE_DOCS>
910   may later hold other output formats.
912   <\nf-chunk|Makefile.inc-vars>
913     <item>FANGLE_DOCS=$(FANGLE_PDF)
914   </nf-chunk||>
916   We also define <verbatim|fangle_docs> as a convenient phony target.
918   <\nf-chunk|Makefile.inc-targets>
919     <item>.PHONY: fangle_docs
921     <item>fangle_docs: $(FANGLE_DOCS)
923     <item>docs: fangle_docs
924   </nf-chunk||>
926   And define a convenient <verbatim|clean_fangle_docs> which we add to the
927   regular clean target
929   <\nf-chunk|Makefile.inc-targets>
930     <item>.PHONEY: clean_fangle_docs
932     <item>clean_fangle_docs: clean_tex clean_pdf
934     <item>clean: clean_fangle_docs
936     <item>
938     <item>distclean_fangle_docs: clean_tex clean_fangle_docs
940     <item>distclean: clean distclean_fangle_docs
941   </nf-chunk||>
943   <section|Other helpers>
945   If <filename|Makefile.inc> is included into <filename|Makefile>, then
946   extracted files can be updated with this command:
948   <verbatim|make fangle_sources>
950   otherwise, with:
952   <verbatim|make -f Makefile.inc fangle_sources>
954   <section|Boot-strapping the extraction>
956   As well as having the makefile extract or update the source files as part
957   of it's operation, it also seems convenient to have the makefile
958   re-extracted itself from <em|this> document.
960   It would also be convenient to have the code that extracts the makefile
961   from this document to also be part of this document, however we have to
962   start somewhere and this unfortunately requires us to type at least a few
963   words by hand to start things off.
965   Therefore we will have a minimal root fragment, which, when extracted, can
966   cope with extracting the rest of the source. This shell script fragment can
967   do that. It's name is <verbatim|*> <emdash> out of regard for <name|Noweb>,
968   but when extracted might better be called <verbatim|autoupdate>.
970   <todo|De-lyxify>
972   <\nf-chunk|*>
973     <item>#! /bin/sh
975     <item>
977     <item>MAKE_SRC="${1:-${NW_LYX:-../../noweb-lyx/noweb-lyx3.lyx}}"
979     <item>MAKE_SRC=`dirname "$MAKE_SRC"`/`basename "$MAKE_SRC" .lyx`
981     <item>NOWEB_SRC="${2:-${NOWEB_SRC:-$MAKE_SRC.lyx}}"
983     <item>lyx -e latex $MAKE_SRC
985     <item>
987     <item>fangle -R./Makefile.inc ${MAKE_SRC}.tex \\
989     <item> \ \| sed "/FANGLE_SOURCE=/s/^/#/;T;aNOWEB_SOURCE=$FANGLE_SRC" \\
991     <item> \ \| cpif ./Makefile.inc
993     <item>
995     <item>make -f ./Makefile.inc fangle_sources
996   </nf-chunk|sh|>
998   The general Makefile can be invoked with <filename|./autoboot> and can also
999   be included into any automake file to automatically re-generate the source
1000   files.
1002   The <em|autoboot> can be extracted with this command:
1004   <\verbatim>
1005     lyx -e latex fangle.lyx && \\
1007     \ \ fangle fangle.lyx \<gtr\> ./autoboot
1008   </verbatim>
1010   This looks simple enough, but as mentioned, fangle has to be had from
1011   somewhere before it can be extracted.
1013   On a unix system this will extract <filename|fangle.module> and the
1014   <filename|fangle> awk script, and run some basic tests.\ 
1016   <todo|cross-ref to test chapter when it is a chapter all on its own>
1018   <section|Incorporating Makefile.inc into existing projects>
1020   If you are writing a literate module of an existing non-literate program
1021   you may find it easier to use a slight recursive make instead of directly
1022   including <verbatim|Makefile.inc> in the projects makefile.\ 
1024   This way there is less chance of definitions in <verbatim|Makefile.inc>
1025   interfering with definitions in the main makefile, or with definitions in
1026   other <verbatim|Makefile.inc> from other literate modules of the same
1027   project.
1029   To do this we add some <em|glue> to the project makefile that invokes
1030   Makefile.inc in the right way. The glue works by adding a <verbatim|.PHONY>
1031   target to call the recursive make, and adding this target as an additional
1032   pre-requisite to the existing targets.
1034   <paragraph|Example>Sub-module of existing system
1036   In this example, we are building <verbatim|module.so> as a literate module
1037   of a larger project.
1039   We will show the sort glue that can be inserted into the projects Makefile
1040   <emdash> or more likely <emdash> a regular Makefile included in or invoked
1041   by the projects Makefile.
1043   <\nf-chunk|makefile-glue>
1044     <item>module_srcdir=modules/module
1046     <item>MODULE_SOURCE=module.tm
1048     <item>MODULE_STAMP=$(MODULE_SOURCE).stamp
1049   </nf-chunk||>
1051   The existing build system may already have a build target for
1052   <filename|module.o>, but we just add another pre-requisite to that. In this
1053   case we use <filename|module.tm.stamp> as a pre-requisite, the stamp file's
1054   modified time indicating when all sources were extracted<\footnote>
1055     If the projects build system does not know how to build the module from
1056     the extracted sources, then just add build actions here as normal.
1057   </footnote>.
1059   <\nf-chunk|makefile-glue>
1060     <item>$(module_srcdir)/module.o: $(module_srcdir)/$(MODULE_STAMP)
1061   </nf-chunk|make|>
1063   The target for this new pre-requisite will be generated by a recursive make
1064   using <filename|Makefile.inc> which will make sure that the source is up to
1065   date, before it is built by the main projects makefile.
1067   <\nf-chunk|makefile-glue>
1068     <item>$(module_srcdir)/$(MODULE_STAMP): $(module_srcdir)/$(MODULE_SOURCE)
1070     <item><nf-tab>$(MAKE) -C $(module_srcdir) -f Makefile.inc fangle_sources
1071     LITERATE_SOURCE=$(MODULE_SOURCE)
1072   </nf-chunk||>
1074   We can do similar glue for the docs, clean and distclean targets. In this
1075   example the main prject was using a double colon for these targets, so we
1076   must use the same in our glue.
1078   <\nf-chunk|makefile-glue>
1079     <item>docs:: docs_module
1081     <item>.PHONY: docs_module
1083     <item>docs_module:
1085     <item><nf-tab>$(MAKE) -C $(module_srcdir) -f Makefile.inc docs
1086     LITERATE_SOURCE=$(MODULE_SOURCE)
1088     <item>
1090     <item>clean:: clean_module
1092     <item>.PHONEY: clean_module
1094     <item>clean_module:
1096     <item><nf-tab>$(MAKE) -C $(module_srcdir) -f Makefile.inc clean
1097     LITERATE_SOURCE=$(MODULE_SOURCE)
1099     <item>
1101     <item>distclean:: distclean_module
1103     <item>.PHONY: distclean_module
1105     <item>distclean_module:
1107     <item><nf-tab>$(MAKE) -C $(module_srcdir) -f Makefile.inc distclean
1108     LITERATE_SOURCE=$(MODULE_SOURCE)
1109   </nf-chunk||>
1111   We could do similarly for install targets to install the generated docs.
1113   <part|Source Code>
1115   <chapter|Fangle awk source code>
1117   We use the copyright notice from chapter <reference|License>.
1119   <\nf-chunk|./fangle>
1120     <item>#! /usr/bin/awk -f
1122     <item># <nf-ref|gpl3-copyright|>
1123   </nf-chunk|awk|>
1125   We also use code from <person|Arnold Robbins> public domain getopt (1993
1126   revision) defined in <reference|getopt>, and naturally want to attribute
1127   this appropriately.
1129   <\nf-chunk|./fangle>
1130     <item># NOTE: Arnold Robbins public domain getopt for awk is also used:
1132     <item><nf-ref|getopt.awk-header|>
1134     <item><nf-ref|getopt.awk-getopt()|>
1136     <item>
1137   </nf-chunk||>
1139   And include the following chunks (which are explained further on) to make
1140   up the program:
1142   <\nf-chunk|./fangle>
1143     <item><nf-ref|helper-functions|>
1145     <item><nf-ref|mode-tracker|>
1147     <item><nf-ref|parse_chunk_args|>
1149     <item><nf-ref|chunk-storage-functions|>
1151     <item><nf-ref|output_chunk_names()|>
1153     <item><nf-ref|output_chunks()|>
1155     <item><nf-ref|write_chunk()|>
1157     <item><nf-ref|expand_chunk_args()|>
1159     <item>
1161     <item><nf-ref|begin|>
1163     <item><nf-ref|recognize-chunk|>
1165     <item><nf-ref|end|>
1166   </nf-chunk||>
1168   <section|AWK tricks>
1170   The portable way to erase an array in awk is to split the empty string, so
1171   we define a fangle macro that can split an array, like this:
1173   <\nf-chunk|awk-delete-array>
1174     <item>split("", <nf-arg|ARRAY>);
1175   </nf-chunk|awk|<tuple|ARRAY>>
1177   For debugging it is sometimes convenient to be able to dump the contents of
1178   an array to <verbatim|stderr>, and so this macro is also useful.
1180   <\nf-chunk|dump-array>
1181     <item>print "\\nDump: <nf-arg|ARRAY>\\n--------\\n" \<gtr\>
1182     "/dev/stderr";
1184     <item>for (_x in <nf-arg|ARRAY>) {
1186     <item> \ print _x "=" <nf-arg|ARRAY>[_x] "\\n" \<gtr\> "/dev/stderr";
1188     <item>}
1190     <item>print "========\\n" \<gtr\> "/dev/stderr";
1191   </nf-chunk|awk|<tuple|ARRAY>>
1193   <section|Catching errors>
1195   Fatal errors are issued with the error function:
1197   <\nf-chunk|error()>
1198     <item>function error(message)
1200     <item>{
1202     <item> \ print "ERROR: " FILENAME ":" FNR " " message \<gtr\>
1203     "/dev/stderr";
1205     <item> \ exit 1;
1207     <item>}
1208   </nf-chunk|awk|>
1210   and likewise for non-fatal warnings:
1212   <\nf-chunk|error()>
1213     <item>function warning(message)
1215     <item>{
1217     <item> \ print "WARNING: " FILENAME ":" FNR " " message \<gtr\>
1218     "/dev/stderr";
1220     <item> \ warnings++;
1222     <item>}
1223   </nf-chunk|awk|>
1225   and debug output too:
1227   <\nf-chunk|error()>
1228     <item>function debug_log(message)
1230     <item>{
1232     <item> \ print "DEBUG: " FILENAME ":" FNR " " message \<gtr\>
1233     "/dev/stderr";
1235     <item>}
1236   </nf-chunk|awk|>
1238   <todo|append=helper-functions>
1240   <\nf-chunk|helper-functions>
1241     <item><nf-ref|error()|>
1242   </nf-chunk||>
1244   <chapter|<TeXmacs> args>
1246   <TeXmacs> functions with arguments<\footnote>
1247     or function declarations with parameters
1248   </footnote> appear like this:
1250   <math|<math-tt|blah(><wide*|<wide|<math-tt|I came, I saw, I
1251   conquered>|\<wide-overbrace\>><rsup|argument 1><wide|<math-tt|<key|^K>>,
1252   |\<wide-overbrace\>><rsup|sep.><wide|and then went home
1253   asd|\<wide-overbrace\>><rsup|argument 3><wide|<math-tt|<key|^K>><math-tt|)>|\<wide-overbrace\>><rsup|term.>|\<wide-underbrace\>><rsub|arguments>>
1255   Arguments commence after the opening parenthesis. The first argument runs
1256   up till the next <key|^K>.\ 
1258   If the following character is a <key|,> then another argument follows. If
1259   the next character after the <key|,> is a space character, then it is also
1260   eaten. The fangle stylesheet emits <key|^K><key|,><key|space> as
1261   separators, but the fangle untangler will forgive a missing space.
1263   If the following character is <key|)> then this is a terminator and there
1264   are no more arguments.
1266   <\nf-chunk|constants>
1267     <item>ARG_SEPARATOR=sprintf("%c", 11);
1268   </nf-chunk||>
1270   To process the <verbatim|text> in this fashion, we split the string on
1271   <key|^K>
1273   \;
1275   <\nf-chunk|get_chunk_args>
1276     <item>function get_texmacs_chunk_args(text, args, \ \ a, done) {
1278     <item> \ split(text, args, ARG_SEPARATOR);
1280     <item>
1282     <item> \ done=0
1284     <item> \ for (a=1; (a in args); a++) if (a\<gtr\>1) {
1286     <item> \ \ \ if (args[a] == "" \|\| substr(args[a], 1, 1) == ")") done=1;
1288     <item> \ \ \ if (done) {
1290     <item> \ \ \ \ \ delete args[a];
1292     <item> \ \ \ \ \ break;
1294     <item> \ \ \ }
1296     <item>
1298     <item> \ \ \ if (substr(args[a], 1, 2) == ", ") args[a]=substr(args[a],
1299     3);
1301     <item> \ \ \ else if (substr(args[a], 1, 1) == ",")
1302     args[a]=substr(args[a], 2); \ 
1304     <item> \ }
1306     <item>}
1307   </nf-chunk||>
1309   <chapter|<LaTeX> and lstlistings>
1311   <todo|Split LyX and TeXmacs parts>
1313   For <LyX> and <LaTeX>, the <verbatim|lstlistings> package is used to format
1314   the lines of code chunks. You may recal from chapter XXX that arguments to
1315   a chunk definition are pure <LaTeX> code. This means that fangle needs to
1316   be able to parse <LaTeX> a little.
1318   <LaTeX> arguments to <verbatim|lstlistings> macros are a comma seperated
1319   list of key-value pairs, and values containing commas are enclosed in
1320   <verbatim|{> braces <verbatim|}> (which is to be expected for <LaTeX>).
1322   A sample expressions is:
1324   <verbatim|name=thomas, params={a, b}, something, something-else>
1326   but we see that this is just a simpler form of this expression:
1328   <verbatim|name=freddie, foo={bar=baz, quux={quirk, a=fleeg}}, etc>
1330   We may consider that we need a function that can parse such <LaTeX>
1331   expressions and assign the values to an AWK associated array, perhaps using
1332   a recursive parser into a multi-dimensional hash<\footnote>
1333     as AWK doesn't have nested-hash support
1334   </footnote>, resulting in:
1336   <tabular|<tformat|<cwith|2|6|1|2|cell-lborder|0.5pt>|<cwith|2|6|1|2|cell-rborder|0.5pt>|<cwith|2|6|1|2|cell-bborder|0.5pt>|<cwith|2|6|1|2|cell-tborder|0.5pt>|<cwith|1|1|1|2|cell-lborder|0.5pt>|<cwith|1|1|1|2|cell-rborder|0.5pt>|<cwith|1|1|1|2|cell-bborder|0.5pt>|<cwith|1|1|1|2|cell-tborder|0.5pt>|<table|<row|<cell|key>|<cell|value>>|<row|<cell|a[name]>|<cell|freddie>>|<row|<cell|a[foo,
1337   bar]>|<cell|baz>>|<row|<cell|a[foo, quux,
1338   quirk]>|<cell|>>|<row|<cell|a[foo, quux,
1339   a]>|<cell|fleeg>>|<row|<cell|a[etc]>|<cell|>>>>>
1341   Yet, also, on reflection it seems that sometimes such nesting is not
1342   desirable, as the braces are also used to delimit values that contain
1343   commas --- we may consider that
1345   <verbatim|name={williamson, freddie}>
1347   should assign <verbatim|williamson, freddie> to <verbatim|name>.
1349   In fact we are not so interested in the detail so as to be bothered by
1350   this, which turns out to be a good thing for two reasons. Firstly <TeX> has
1351   a malleable parser with no strict syntax, and secondly whether or not
1352   <verbatim|williamson> and <verbatim|freddie> should count as two items will
1353   be context dependant anyway.
1355   We need to parse this latex for only one reason; which is that we are
1356   extending lstlistings to add some additional arguments which will be used
1357   to express chunk parameters and other chunk options.
1359   <section|Additional lstlstings parameters>
1361   Further on we define a <verbatim|\\Chunk> <LaTeX> macro whose arguments
1362   will consist of a the chunk name, optionally followed by a comma and then a
1363   comma separated list of arguments. In fact we will just need to prefix
1364   <verbatim|name=> to the arguments to in order to create valid lstlistings
1365   arguments.\ 
1367   There will be other arguments supported too;\ 
1369   <\description-long>
1370     <item*|params>As an extension to many literate-programming styles, fangle
1371     permits code chunks to take parameters and thus operate somewhat like C
1372     pre-processor macros, or like C++ templates. Chunk parameters are
1373     declared with a chunk argument called params, which holds a semi-colon
1374     separated list of parameters, like this:
1376     <verbatim|achunk,language=C,params=name;address>
1378     <item*|addto>a named chunk that this chunk is to be included into. This
1379     saves the effort of having to declare another listing of the named chunk
1380     merely to include this one.
1381   </description-long>
1383   Function get_chunk_args() will accept two paramters, text being the text to
1384   parse, and values being an array to receive the parsed values as described
1385   above. The optional parameter path is used during recursion to build up the
1386   multi-dimensional array path.
1388   <\nf-chunk|./fangle>
1389     <item>=\<less\>\\chunkref{get_chunk_args()}\<gtr\>
1390   </nf-chunk||>
1392   <\nf-chunk|get_chunk_args()>
1393     <item>function get_tex_chunk_args(text, values,
1395     <item> \ # optional parameters
1397     <item> \ path, # hierarchical precursors
1399     <item> \ # local vars
1401     <item> \ a, name)
1402   </nf-chunk||>
1404   The strategy is to parse the name, and then look for a value. If the value
1405   begins with a brace <verbatim|{>, then we recurse and consume as much of
1406   the text as necessary, returning the remaining text when we encounter a
1407   leading close-brace <verbatim|}>. This being the strategy --- and executed
1408   in a loop --- we realise that we must first look for the closing brace
1409   (perhaps preceded by white space) in order to terminate the recursion, and
1410   returning remaining text.
1412   <\nf-chunk|get_chunk_args()>
1413     <item>{
1415     <item> \ split("", values);
1417     <item> \ while(length(text)) {
1419     <item> \ \ \ if (match(text, "^ *}(.*)", a)) {
1421     <item> \ \ \ \ \ return a[1];
1423     <item> \ \ \ }
1425     <item> \ \ \ =\<less\>\\chunkref{parse-chunk-args}\<gtr\>
1427     <item> \ }
1429     <item> \ return text;
1431     <item>}
1432   </nf-chunk||>
1434   We can see that the text could be inspected with this regex:
1436   <\nf-chunk|parse-chunk-args>
1437     <item>if (! match(text, " *([^,=]*[^,= ]) *(([,=]) *(([^,}]*) *,*
1438     *(.*))\|)$", a)) {
1440     <item> \ return text;
1442     <item>}
1443   </nf-chunk||>
1445   and that <verbatim|a> will have the following values:
1447   <tabular|<tformat|<cwith|2|7|1|2|cell-lborder|0.5pt>|<cwith|2|7|1|2|cell-rborder|0.5pt>|<cwith|2|7|1|2|cell-bborder|0.5pt>|<cwith|2|7|1|2|cell-tborder|0.5pt>|<cwith|1|1|1|2|cell-lborder|0.5pt>|<cwith|1|1|1|2|cell-rborder|0.5pt>|<cwith|1|1|1|2|cell-bborder|0.5pt>|<cwith|1|1|1|2|cell-tborder|0.5pt>|<table|<row|<cell|a[n]>|<cell|assigned
1448   text>>|<row|<cell|1>|<cell|freddie>>|<row|<cell|2>|<cell|=freddie,
1449   foo={bar=baz, quux={quirk, a=fleeg}}, etc>>|<row|<cell|3>|<cell|=>>|<row|<cell|4>|<cell|freddie,
1450   foo={bar=baz, quux={quirk, a=fleeg}}, etc>>|<row|<cell|5>|<cell|freddie>>|<row|<cell|6>|<cell|,
1451   foo={bar=baz, quux={quirk, a=fleeg}}, etc>>>>>
1453   <verbatim|a[3]> will be either <verbatim|=> or <verbatim|,> and signify
1454   whether the option named in <verbatim|a[1]> has a value or not
1455   (respectively).
1457   If the option does have a value, then if the expression
1458   <verbatim|substr(a[4],1,1)> returns a brace <verbatim|{> it will signify
1459   that we need to recurse:
1461   <\nf-chunk|parse-chunk-args>
1462     <item>name=a[1];
1464     <item>if (a[3] == "=") {
1466     <item> \ if (substr(a[4],1,1) == "{") {
1468     <item> \ \ \ text = get_tex_chunk_args(substr(a[4],2), values, path name
1469     SUBSEP);
1471     <item> \ } else {
1473     <item> \ \ \ values[path name]=a[5];
1475     <item> \ \ \ text = a[6];
1477     <item> \ }
1479     <item>} else {
1481     <item> \ values[path name]="";
1483     <item> \ text = a[2];
1485     <item>}
1486   </nf-chunk||>
1488   We can test this function like this:
1490   <\nf-chunk|gca-test.awk>
1491     <item>=\<less\>\\chunkref{get_chunk_args()}\<gtr\>
1493     <item>BEGIN {
1495     <item> \ SUBSEP=".";
1497     <item>
1499     <item> \ print get_tex_chunk_args("name=freddie, foo={bar=baz,
1500     quux={quirk, a=fleeg}}, etc", a);
1502     <item> \ for (b in a) {
1504     <item> \ \ \ print "a[" b "] =\<gtr\> " a[b];
1506     <item> \ }
1508     <item>}
1509   </nf-chunk||>
1511   which should give this output:
1513   <\nf-chunk|gca-test.awk-results>
1514     <item>a[foo.quux.quirk] =\<gtr\>\ 
1516     <item>a[foo.quux.a] =\<gtr\> fleeg
1518     <item>a[foo.bar] =\<gtr\> baz
1520     <item>a[etc] =\<gtr\>\ 
1522     <item>a[name] =\<gtr\> freddie
1523   </nf-chunk||>
1525   <section|Parsing chunk arguments><label|Chunk Arguments>
1527   Arguments to paramterized chunks are expressed in round brackets as a comma
1528   separated list of optional arguments. For example, a chunk that is defined
1529   with:
1531   <verbatim|\\Chunk{achunk, params=name ; address}>
1533   could be invoked as:
1535   <verbatim|\\chunkref{achunk}(John Jones, jones@example.com)>
1537   An argument list may be as simple as in <verbatim|\\chunkref{pull}(thing,
1538   otherthing)> or as complex as:
1540   <verbatim|\\chunkref{pull}(things[x, y], get_other_things(a, "(all)"))>
1542   --- which for all it's commas and quotes and parenthesis represents only
1543   two parameters: <verbatim|things[x, y]> and <verbatim|get_other_things(a,
1544   "(all)")>.
1546   If we simply split parameter list on commas, then the comma in
1547   <verbatim|things[x,y]> would split into two seperate arguments:
1548   <verbatim|things[x> and <verbatim|y]>--- neither of which make sense on
1549   their own.
1551   One way to prevent this would be by refusing to split text between matching
1552   delimiters, such as <verbatim|[>, <verbatim|]>, <verbatim|(>, <verbatim|)>,
1553   <verbatim|{>, <verbatim|}> and most likely also <verbatim|">, <verbatim|">
1554   and <verbatim|'>, <verbatim|'>. Of course this also makes it impossible to
1555   pass such mis-matched code fragments as parameters, but I think that it
1556   would be hard for readers to cope with authors who would pass such code
1557   unbalanced fragments as chunk parameters<\footnote>
1558     I know that I couldn't cope with users doing such things, and although
1559     the GPL3 license prevents me from actually forbidding anyone from trying,
1560     if they want it to work they'll have to write the code themselves and not
1561     expect any support from me.
1562   </footnote>.
1564   Unfortunately, the full set of matching delimiters may vary from language
1565   to language. In certain C++ template contexts, <verbatim|\<less\>> and
1566   <verbatim|\<gtr\>> would count as delimiters, and yet in other contexts
1567   they would not.
1569   This puts me in the unfortunate position of having to parse-somewhat all
1570   programming languages without knowing what they are!
1572   However, if this universal mode-tracking is possible, then parsing the
1573   arguments would be trivial. Such a mode tracker is described in chapter
1574   <reference|modes> and used here with simplicity.
1576   <\nf-chunk|parse_chunk_args>
1577     <item>function parse_chunk_args(language, text, values, mode,
1579     <item> \ # local vars
1581     <item> \ c, context, rest)
1583     <item>{
1585     <item> \ =\<less\>\\chunkref{new-mode-tracker}(context, language,
1586     mode)\<gtr\>
1588     <item> \ rest = mode_tracker(context, text, values);
1590     <item> \ # extract values
1592     <item> \ for(c=1; c \<less\>= context[0, "values"]; c++) {
1594     <item> \ \ \ values[c] = context[0, "values", c];
1596     <item> \ }
1598     <item> \ return rest;
1600     <item>}
1601   </nf-chunk||>
1603   <section|Expanding parameters in the text>
1605   Within the body of the chunk, the parameters are referred to with:
1606   <verbatim|${name}> and <verbatim|${address}>. There is a strong case that a
1607   <LaTeX> style notation should be used, like <verbatim|\\param{name}> which
1608   would be expressed in the listing as <verbatim|=\<less\>\\param{name}\<gtr\>>
1609   and be rendered as <verbatim|<nf-arg|name>>. Such notation would make me go
1610   blind, but I do intend to adopt it.
1612   We therefore need a function <verbatim|expand_chunk_args> which will take a
1613   block of text, a list of permitted parameters, and the arguments which must
1614   substitute for the parameters.\ 
1616   Here we split the text on <verbatim|${> which means that all parts except
1617   the first will begin with a parameter name which will be terminated by
1618   <verbatim|}>. The split function will consume the literal <verbatim|${> in
1619   each case.
1621   <\nf-chunk|expand_chunk_args()>
1622     <item>function expand_chunk_args(text, params, args, \ 
1624     <item> \ p, text_array, next_text, v, t, l)
1626     <item>{
1628     <item> \ if (split(text, text_array, "\\\\${")) {
1630     <item> \ \ \ <nf-ref|substitute-chunk-args|>
1632     <item> \ }
1634     <item>
1636     <item> \ return text;
1638     <item>}
1639   </nf-chunk||>
1641   First, we produce an associative array of substitution values indexed by
1642   parameter names. This will serve as a cache, allowing us to look up the
1643   replacement values as we extract each name.
1645   <\nf-chunk|substitute-chunk-args>
1646     <item>for(p in params) {
1648     <item> \ v[params[p]]=args[p];
1650     <item>}
1651   </nf-chunk||>
1653   We accumulate substituted text in the variable text. As the first part of
1654   the split function is the part before the delimiter --- which is
1655   <verbatim|${> in our case --- this part will never contain a parameter
1656   reference, so we assign this directly to the result kept in
1657   <verbatim|$text>.
1659   <\nf-chunk|substitute-chunk-args>
1660     <item>text=text_array[1];
1661   </nf-chunk||>
1663   We then iterate over the remaining values in the array<\footnote>
1664     I don't know why I think that it will enumerate the array in order, but
1665     it seems to work
1666   </footnote><todo|fix or prove it>, and substitute each reference for it's
1667   argument.
1669   <\nf-chunk|substitute-chunk-args>
1670     <item>for(t=2; t in text_array; t++) {
1672     <item> \ =\<less\>\\chunkref{substitute-chunk-arg}\<gtr\>
1674     <item>}
1675   </nf-chunk||>
1677   After the split on <verbatim|${> a valid parameter reference will consist
1678   of valid parameter name terminated by a close-brace <verbatim|}>. A valid
1679   character name begins with the underscore or a letter, and may contain
1680   letters, digits or underscores.
1682   A valid looking reference that is not actually the name of a parameter will
1683   be and not substituted. This is good because there is nothing to substitute
1684   anyway, and it avoids clashes when writing code for languages where
1685   <verbatim|${...}> is a valid construct --- such constructs will not be
1686   interfered with unless the parameter name also matches.
1688   <\nf-chunk|substitute-chunk-arg>
1689     <item>if (match(text_array[t], "^([a-zA-Z_][a-zA-Z0-9_]*)}", l) &&
1691     <item> \ \ \ l[1] in v)\ 
1693     <item>{
1695     <item> \ text = text v[l[1]] substr(text_array[t], length(l[1])+2);
1697     <item>} else {
1699     <item> \ text = text "${" text_array[t];
1701     <item>}
1702   </nf-chunk||>
1704   <chapter|Language Modes & Quoting><label|modes>
1706   <section|Modes>
1708   <verbatim|lstlistings> and <verbatim|fangle> both recognize source
1709   languages, and perform some basic parsing. <verbatim|lstlistings> can
1710   detect strings and comments within a language definition and perform
1711   suitable rendering, such as italics for comments, and visible-spaces within
1712   strings.
1714   Fangle similarly can recognize strings, and comments, etc, within a
1715   language, so that any chunks included with <verbatim|\\chunkref> can be
1716   suitably escape or quoted.
1718   <subsection|Modes to keep code together>
1720   As an example, in the C language there are a few parse modes, affecting the
1721   interpretation of characters.
1723   One parse mode is the strings mode. The string mode is commenced by an
1724   un-escaped quotation mark <verbatim|"> and terminated by the same. Within
1725   the string mode, only one additional mode can be commenced, it is the
1726   backslash mode <verbatim|\\>, which is always terminated after the folloing
1727   character.
1729   Another mode is <verbatim|[> which is terminated by a <verbatim|]> (unless
1730   it occurs in a string).
1732   Consider this fragment of C code:
1734   \;
1736   <math|things<wide|<around|[|x, y|]>|\<wide-overbrace\>><rsup|1. [ mode>,
1737   get_other_things<wide|<around|(|a, <wide*|<text|"><around|(|all|)><text|">|\<wide-underbrace\>><rsub|3.
1738   " mode>|)>|\<wide-overbrace\>><rsup|2. ( mode>>
1740   \;
1742   Mode nesting prevents the close parenthesis in the quoted string (part 3)
1743   from terminating the parenthesis mode (part 2).
1745   Each language has a set of modes, the default mode being the null mode.
1746   Each mode can lead to other modes.
1748   <subsection|Modes affect included chunks>
1750   For instance, consider this chunk with language=perl:
1752   <nf-chunk|example-perl|print "hello world $0\\n";|perl|>
1754   If it were included in a chunk with <verbatim|language=sh>, like this:
1756   <nf-chunk|example-sh|perl -e "=\<less\>\\chunkref{example-perl}\<gtr\>"|sh|>
1758   fangle would <em|want> to generate output like this:
1760   <verbatim|perl -e "print \\"hello world \\$0\\\\n\\";" >
1762   See that the double quote <verbatim|">, back-slash <verbatim|\\> and
1763   <verbatim|$> have been quoted with a back-slash to protect them from shell
1764   interpretation.
1766   If that were then included in a chunk with language=make, like this:
1768   <\nf-chunk|example-makefile>
1769     <item>target: pre-req
1771     <item><htab|5mm>=\<less\>\\chunkref{example-sh}\<gtr\>
1772   </nf-chunk|make|>
1774   We would need the output to look like this --- note the <verbatim|$$>:
1776   <\verbatim>
1777     target: pre-req
1779     \ \ \ \ \ \ \ \ perl -e "print \\"hello world \\$$0\\\\n\\";"
1780   </verbatim>
1782   In order to make this work, we need to define a mode-tracker supporting
1783   each language, that can detect the various quoting modes, and provide a
1784   transformation that must be applied to any included text so that included
1785   text will be interpreted correctly after any interpolation that it may be
1786   subject to at run-time.
1788   For example, the sed transformation for text to be inserted into shell
1789   double-quoted strings would be something like:
1791   <verbatim|s/\\\\/\\\\\\\\/g;s/$/\\\\$/g;s/"/\\\\"/g;>
1793   which protects <verbatim|\\ $ ">.
1795   <todo|I don't think this example is true>The mode tracker must also track
1796   nested mode-changes, as in this sh example.
1798   <verbatim|echo "hello `id ...`">
1800   <phantom|<verbatim|echo "hello `id >><math|\<uparrow\>>
1802   Any characters inserted at the point marked <math|\<uparrow\>> would need
1803   to be escaped, including <verbatim|`> <verbatim|\|> <verbatim|*> among
1804   others. First it would need escaping for the back-ticks <verbatim|`>, and
1805   then for the double-quotes <verbatim|">.
1807   <todo|MAYBE>Escaping need not occur if the format and mode of the included
1808   chunk matches that of the including chunk.
1810   As each chunk is output a new mode tracker for that language is initialized
1811   in it's normal state. As text is output for that chunk the output mode is
1812   tracked. When a new chunk is included, a transformation appropriate to that
1813   mode is selected and pushed onto a stack of transformations. Any text to be
1814   output is first passed through this stack of transformations.
1816   It remains to consider if the chunk-include function should return it's
1817   generated text so that the caller can apply any transformations (and
1818   formatting), or if it should apply the stack of transformations itself.
1820   Note that the transformed text should have the property of not being able
1821   to change the mode in the current chunk.
1823   <todo|Note chunk parameters should probably also be transformed>
1825   <section|Language Mode Definitions>
1827   All modes are stored in a single multi-dimensional hash. The first index is
1828   the language, and the second index is the mode-identifier. The third
1829   indexes are terminators, and optionally, submodes, and delimiters.
1831   A useful set of mode definitions for a nameless general C-type language is
1832   shown here. (Don't be confused by the double backslash escaping needed in
1833   awk. One set of escaping is for the string, and the second set of escaping
1834   is for the regex).
1836   <\todo>
1837     TODO: Add =\<less\>\\mode{}\<gtr\> command which will allow us to signify
1838     that a string is
1840     \ regex and thus fangle will quote it for us.
1841   </todo>
1843   Submodes are entered by the characters \ <verbatim|"> <verbatim|'>
1844   <verbatim|{> <verbatim|(> <verbatim|[> <verbatim|/*>
1846   <\nf-chunk|common-mode-definitions>
1847     <item>modes[${language}, "", \ "submodes"]="\\\\\\\\\|\\"\|'\|{\|\\\\(\|\\\\[";
1848   </nf-chunk||<tuple|language>>
1850   In the default mode, a comma surrounded by un-important white space is a
1851   delimiter of language items<\footnote>
1852     whatever a <em|language item> might be
1853   </footnote>.
1855   <\nf-chunk|common-mode-definitions>
1856     <item>modes[${language}, "", \ "delimiters"]=" *, *";
1857   </nf-chunk||language>
1859   and should pass this test:<todo|Why do the tests run in ?(? mode and not ??
1860   mode>
1862   <\nf-chunk|test:mode-definitions>
1863     <item>parse_chunk_args("c-like", "1,2,3", a, "");
1865     <item>if (a[1] != "1") e++;
1867     <item>if (a[2] != "2") e++;
1869     <item>if (a[3] != "3") e++;
1871     <item>if (length(a) != 3) e++;
1873     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
1875     <item>
1877     <item>parse_chunk_args("c-like", "joe, red", a, "");
1879     <item>if (a[1] != "joe") e++;
1881     <item>if (a[2] != "red") e++;
1883     <item>if (length(a) != 2) e++;
1885     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
1887     <item>
1889     <item>parse_chunk_args("c-like", "${colour}", a, "");
1891     <item>if (a[1] != "${colour}") e++;
1893     <item>if (length(a) != 1) e++;
1895     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
1896   </nf-chunk||>
1898   Nested modes are identified by a backslash, a double or single quote,
1899   various bracket styles or a <verbatim|/*> comment.
1901   For each of these sub-modes modes we must also identify at a mode
1902   terminator, and any sub-modes or delimiters that may be entered<\footnote>
1903     Because we are using the sub-mode characters as the mode identifier it
1904     means we can't currently have a mode character dependant on it's context;
1905     i.e. <verbatim|{> can't behave differently when it is inside
1906     <verbatim|[>.
1907   </footnote>.
1909   <subsection|Backslash>
1911   The backslash mode has no submodes or delimiters, and is terminated by any
1912   character. Note that we are not so much interested in evaluating or
1913   interpolating content as we are in delineating content. It is no matter
1914   that a double backslash (<verbatim|\\\\>) may represent a single backslash
1915   while a backslash-newline may represent white space, but it does matter
1916   that the newline in a backslash newline should not be able to terminate a C
1917   pre-processor statement; and so the newline will be consumed by the
1918   backslash however it is to be interpreted.
1920   <\nf-chunk|common-mode-definitions>
1921     <item>modes[${language}, "\\\\", "terminators"]=".";
1922   </nf-chunk||>
1924   <subsection|Strings>
1926   Common languages support two kinds of strings quoting, double quotes and
1927   single quotes.
1929   In a string we have one special mode, which is the backslash. This may
1930   escape an embedded quote and prevent us thinking that it should terminate
1931   the string.
1933   <\nf-chunk|mode:common-string>
1934     <item>modes[${language}, ${quote}, "submodes"]="\\\\\\\\";
1935   </nf-chunk||<tuple|language|quote>>
1937   Otherwise, the string will be terminated by the same character that
1938   commenced it.
1940   <\nf-chunk|mode:common-string>
1941     <item>modes[${language}, ${quote}, "terminators"]=${quote};
1942   </nf-chunk||language>
1944   In C type languages, certain escape sequences exist in strings. We need to
1945   define mechanism to enclode any chunks included in this mode using those
1946   escape sequences. These are expressed in two parts, s meaning search, and r
1947   meaning replace.
1949   The first substitution is to replace a backslash with a double backslash.
1950   We do this first as other substitutions may introduce a backslash which we
1951   would not then want to escape again here.
1953   Note: Backslashes need double-escaping in the search pattern but not in the
1954   replacement string, hence we are replacing a literal <verbatim|\\> with a
1955   literal <verbatim|\\\\>.
1957   <\nf-chunk|mode:common-string>
1958     <item>escapes[${language}, ${quote}, ++escapes[${language}, ${quote}],
1959     "s"]="\\\\\\\\";
1961     <item>escapes[${language}, ${quote}, \ \ escapes[${language}, ${quote}],
1962     "r"]="\\\\\\\\";
1963   </nf-chunk||language>
1965   If the quote character occurs in the text, it should be preceded by a
1966   backslash, otherwise it would terminate the string unexpectedly.
1968   <\nf-chunk|mode:common-string>
1969     <item>escapes[${language}, ${quote}, ++escapes[${language}, ${quote}],
1970     "s"]=${quote};
1972     <item>escapes[${language}, ${quote}, \ \ escapes[${language}, ${quote}],
1973     "r"]="\\\\" ${quote};
1974   </nf-chunk||language>
1976   Any newlines in the string, must be replaced by <verbatim|\\n>.
1978   <\nf-chunk|mode:common-string>
1979     <item>escapes[${language}, ${quote}, ++escapes[${language}, ${quote}],
1980     "s"]="\\n";
1982     <item>escapes[${language}, ${quote}, \ \ escapes[${language}, ${quote}],
1983     "r"]="\\\\n";
1984   </nf-chunk||language>
1986   For the common modes, we define this string handling for double and single
1987   quotes.
1989   <\nf-chunk|common-mode-definitions>
1990     <item>=\<less\>\\chunkref{mode:common-string}(${language},
1991     "\\textbackslash{}"")\<gtr\>
1993     <item>=\<less\>\\chunkref{mode:common-string}(${language}, "'")\<gtr\>
1994   </nf-chunk||>
1996   Working strings should pass this test:
1998   <\nf-chunk|test:mode-definitions>
1999     <item>parse_chunk_args("c-like", "say \\"I said, \\\\\\"Hello, how are
2000     you\\\\\\".\\", for me", a, "");
2002     <item>if (a[1] != "say \\"I said, \\\\\\"Hello, how are you\\\\\\".\\"")
2003     e++;
2005     <item>if (a[2] != "for me") e++;
2007     <item>if (length(a) != 2) e++;
2009     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
2010   </nf-chunk||>
2012   <subsection|Parentheses, Braces and Brackets>
2014   Where quotes are closed by the same character, parentheses, brackets and
2015   braces are closed by an alternate character.
2017   <\nf-chunk|mode:common-brackets>
2018     <item>modes[<nf-arg|language>, <nf-arg|open>, \ "submodes"
2019     ]="\\\\\\\\\|\\"\|{\|\\\\(\|\\\\[\|'\|/\\\\*";
2021     <item>modes[<nf-arg|language>, <nf-arg|open>, \ "delimiters"]=" *, *";
2023     <item>modes[<nf-arg|language>, <nf-arg|open>,
2024     \ "terminators"]=<nf-arg|close>;
2025   </nf-chunk||<tuple|language|open|close>>
2027   Note that the open is NOT a regex but the close token IS. <todo|When we can
2028   quote regex we won't have to put the slashes in here>
2030   <\nf-chunk|common-mode-definitions>
2031     <item>=\<less\>\\chunkref{mode:common-brackets}(${language}, "{",
2032     "}")\<gtr\>
2034     <item>=\<less\>\\chunkref{mode:common-brackets}(${language}, "[",
2035     "\\textbackslash{}\\textbackslash{}]")\<gtr\>
2037     <item>=\<less\>\\chunkref{mode:common-brackets}(${language}, "(",
2038     "\\textbackslash{}\\textbackslash{})")\<gtr\>
2039   </nf-chunk||>
2041   <subsection|Customizing Standard Modes>
2043   <\nf-chunk|mode:add-submode>
2044     <item>modes[${language}, ${mode}, "submodes"] = modes[${language},
2045     ${mode}, "submodes"] "\|" ${submode};
2046   </nf-chunk||<tuple|language|mode|submode>>
2048   <\nf-chunk|mode:add-escapes>
2049     <item>escapes[${language}, ${mode}, ++escapes[${language}, ${mode}],
2050     "s"]=${search};
2052     <item>escapes[${language}, ${mode}, \ \ escapes[${language}, ${mode}],
2053     "r"]=${replace};
2054   </nf-chunk||<tuple|language|mode|search|replace>>
2056   \;
2058   <subsection|Comments>
2060   We can define <verbatim|/* comment */> style comments and
2061   <verbatim|//comment> style comments to be added to any language:
2063   <\nf-chunk|mode:multi-line-comments>
2064     <item>=\<less\>\\chunkref{mode:add-submode}(${language}, "",
2065     "/\\textbackslash{}\\textbackslash{}*")\<gtr\>
2067     <item>modes[${language}, "/*", "terminators"]="\\\\*/";
2068   </nf-chunk||<tuple|language>>
2070   <\nf-chunk|mode:single-line-slash-comments>
2071     <item>=\<less\>\\chunkref{mode:add-submode}(${language}, "", "//")\<gtr\>
2073     <item>modes[${language}, "//", "terminators"]="\\n";
2075     <item>=\<less\>\\chunkref{mode:add-escapes}(${language}, "//",
2076     "\\textbackslash{}n", "\\textbackslash{}n//")\<gtr\>
2077   </nf-chunk||language>
2079   We can also define <verbatim|# comment> style comments (as used in awk and
2080   shell scripts) in a similar manner.
2082   <todo|I'm having to use # for hash and \textbackslash{} for \ and have
2083   hacky work-arounds in the parser for now>
2085   <\nf-chunk|mode:add-hash-comments>
2086     <item>=\<less\>\\chunkref{mode:add-submode}(${language}, "",
2087     "\\#")\<gtr\>
2089     <item>modes[${language}, "#", "terminators"]="\\n";
2091     <item>=\<less\>\\chunkref{mode:add-escapes}(${language}, "\\#",
2092     "\\textbackslash{}n", "\\textbackslash{}n\\#")\<gtr\>
2093   </nf-chunk||<tuple|language>>
2095   In C, the <verbatim|#> denotes pre-processor directives which can be
2096   multi-line
2098   <\nf-chunk|mode:add-hash-defines>
2099     <item>=\<less\>\\chunkref{mode:add-submode}(${language}, "",
2100     "\\#")\<gtr\>
2102     <item>modes[${language}, "#", "submodes" ]="\\\\\\\\";
2104     <item>modes[${language}, "#", "terminators"]="\\n";
2106     <item>=\<less\>\\chunkref{mode:add-escapes}(${language}, "\\#",
2107     "\\textbackslash{}n", "\\textbackslash{}\\textbackslash{}\\textbackslash{}\\textbackslash{}\\textbackslash{}n")\<gtr\>
2108   </nf-chunk||<tuple|language>>
2110   <\nf-chunk|mode:quote-dollar-escape>
2111     <item>escapes[${language}, ${quote}, ++escapes[${language}, ${quote}],
2112     "s"]="\\\\$";
2114     <item>escapes[${language}, ${quote}, \ \ escapes[${language}, ${quote}],
2115     "r"]="\\\\$";
2116   </nf-chunk||<tuple|language|quote>>
2118   We can add these definitions to various languages
2120   <\nf-chunk|mode-definitions>
2121     <item><nf-ref|common-mode-definitions|<tuple|"c-like">>
2123     <item>
2125     <item><nf-ref|common-mode-definitions|<tuple|"c">>
2127     <item>=\<less\>\\chunkref{mode:multi-line-comments}("c")\<gtr\>
2129     <item>=\<less\>\\chunkref{mode:single-line-slash-comments}("c")\<gtr\>
2131     <item>=\<less\>\\chunkref{mode:add-hash-defines}("c")\<gtr\>
2133     <item>
2135     <item>=\<less\>\\chunkref{common-mode-definitions}("awk")\<gtr\>
2137     <item>=\<less\>\\chunkref{mode:add-hash-comments}("awk")\<gtr\>
2139     <item>=\<less\>\\chunkref{mode:add-naked-regex}("awk")\<gtr\>
2140   </nf-chunk||>
2142   The awk definitions should allow a comment block like this:
2144   <nf-chunk|test:comment-quote|<item># Comment:
2145   =\<less\>\\chunkref{test:comment-text}\<gtr\>|awk|>
2147   <\nf-chunk|test:comment-text>
2148     <item>Now is the time for
2150     <item>the quick brown fox to bring lemonade
2152     <item>to the party
2153   </nf-chunk||>
2155   to come out like this:
2157   <\nf-chunk|test:comment-quote:result>
2158     <item># Comment: Now is the time for
2160     <item>#the quick brown fox to bring lemonade
2162     <item>#to the party
2163   </nf-chunk||>
2165   The C definition for such a block should have it come out like this:
2167   <\nf-chunk|test:comment-quote:C-result>
2168     <item># Comment: Now is the time for\\
2170     <item>the quick brown fox to bring lemonade\\
2172     <item>to the party
2173   </nf-chunk||>
2175   <subsection|Regex>
2177   This pattern is incomplete, but meant to detect naked regular expressions
2178   in awk and perl; e.g. <verbatim|/.*$/>, however required capabilities are
2179   not present.
2181   Current it only detects regexes anchored with ^ as used in fangle.
2183   For full regex support, modes need to be named not after their starting
2184   character, but some other more fully qualified name.
2186   <\nf-chunk|mode:add-naked-regex>
2187     <item>=\<less\>\\chunkref{mode:add-submode}(${language}, "",
2188     "/\\textbackslash{}\\textbackslash{}\\^")\<gtr\>
2190     <item>modes[${language}, "/^", "terminators"]="/";
2191   </nf-chunk||<tuple|language>>
2193   <subsection|Perl>
2195   <\nf-chunk|mode-definitions>
2196     <item>=\<less\>\\chunkref{common-mode-definitions}("perl")\<gtr\>
2198     <item>=\<less\>\\chunkref{mode:multi-line-comments}("perl")\<gtr\>
2200     <item>=\<less\>\\chunkref{mode:add-hash-comments}("perl")\<gtr\>
2201   </nf-chunk||>
2203   Still need to add add <verbatim|s/>, submode <verbatim|/>, terminate both
2204   with <verbatim|//>. This is likely to be impossible as perl regexes can
2205   contain perl.
2207   <subsection|sh>
2209   <\nf-chunk|mode-definitions>
2210     <item>=\<less\>\\chunkref{common-mode-definitions}("sh")\<gtr\>
2212     <item>#\<less\>\\chunkref{mode:common-string}("sh",
2213     "\\textbackslash{}"")\<gtr\>
2215     <item>#\<less\>\\chunkref{mode:common-string}("sh", "'")\<gtr\>
2217     <item>=\<less\>\\chunkref{mode:add-hash-comments}("sh")\<gtr\>
2219     <item>=\<less\>\\chunkref{mode:quote-dollar-escape}("sh", "\\"")\<gtr\>
2220   </nf-chunk||>
2222   <section|Some tests>
2224   Also, the parser must return any spare text at the end that has not been
2225   processed due to a mode terminator being found.
2227   <\nf-chunk|test:mode-definitions>
2228     <item>rest = parse_chunk_args("c-like", "1, 2, 3) spare", a, "(");
2230     <item>if (a[1] != 1) e++;
2232     <item>if (a[2] != 2) e++;
2234     <item>if (a[3] != 3) e++;
2236     <item>if (length(a) != 3) e++;
2238     <item>if (rest != " spare") e++;
2240     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
2241   </nf-chunk||>
2243   We must also be able to parse the example given earlier.
2245   <\nf-chunk|test:mode-definitions>
2246     <item>parse_chunk_args("c-like", "things[x, y], get_other_things(a,
2247     \\"(all)\\"), 99", a, "(");
2249     <item>if (a[1] != "things[x, y]") e++;
2251     <item>if (a[2] != "get_other_things(a, \\"(all)\\")") e++;
2253     <item>if (a[3] != "99") e++;
2255     <item>if (length(a) != 3) e++;
2257     <item>=\<less\>\\chunkref{pca-test.awk:summary}\<gtr\>
2258   </nf-chunk||>
2260   <section|A non-recursive mode tracker>
2262   <subsection|Constructor>
2264   The mode tracker holds its state in a stack based on a numerically indexed
2265   hash. This function, when passed an empty hash, will intialize it.
2267   <\nf-chunk|new_mode_tracker()>
2268     <item>function new_mode_tracker(context, language, mode) {
2270     <item> \ context[""] = 0;
2272     <item> \ context[0, "language"] = language;
2274     <item> \ context[0, "mode"] = mode;
2276     <item>}
2277   </nf-chunk||>
2279   Because awk functions cannot return an array, we must create the array
2280   first and pass it in, so we have a fangle macro to do this:
2282   <\nf-chunk|new-mode-tracker>
2283     <item><nf-ref|awk-delete-array|<tuple|context>>
2285     <item>new_mode_tracker(${context}, ${language}, ${mode});
2286   </nf-chunk|awk|<tuple|context|language|mode>>
2288   <subsection|Management>
2290   And for tracking modes, we dispatch to a mode-tracker action based on the
2291   current language
2293   <\nf-chunk|mode_tracker>
2294     <item>function push_mode_tracker(context, language, mode,
2296     <item> \ # local vars
2298     <item> \ top)
2300     <item>{
2302     <item> \ if (! ("" in context)) {
2304     <item> \ \ \ <nf-ref|new-mode-tracker|<tuple|context|language|mode>>
2306     <item> \ } else {
2308     <item> \ \ \ top = context[""];
2310     <item> \ \ \ if (context[top, "language"] == language && mode=="") mode =
2311     context[top, "mode"];
2313     <item> \ \ \ top++;
2315     <item> \ \ \ context[top, "language"] = language;
2317     <item> \ \ \ context[top, "mode"] = mode;
2319     <item> \ \ \ context[""] = top;
2321     <item> \ }
2323     <item>}
2324   </nf-chunk|awk|>
2326   <\nf-chunk|mode_tracker>
2327     <item>function dump_mode_tracker(context, \ 
2329     <item> \ c, d)
2331     <item>{
2333     <item> \ for(c=0; c \<less\>= context[""]; c++) {
2335     <item> \ \ \ printf(" %2d \ \ %s:%s\\n", c, context[c, "language"],
2336     context[c, "mode"]) \<gtr\> "/dev/stderr";
2338     <item> \ \ \ for(d=1; ( (c, "values", d) in context); d++) {
2340     <item> \ \ \ \ \ printf(" \ \ %2d %s\\n", d, context[c, "values", d])
2341     \<gtr\> "/dev/stderr";
2343     <item> \ \ \ }
2345     <item> \ }
2347     <item>}
2348   </nf-chunk||>
2350   <\nf-chunk|mode_tracker>
2351     <item>function finalize_mode_tracker(context)
2353     <item>{
2355     <item> \ if ( ("" in context) && context[""] != 0) return 0;
2357     <item> \ return 1;
2359     <item>}
2360   </nf-chunk||>
2362   This implies that any chunk must be syntactically whole; for instance, this
2363   is fine:
2365   <\nf-chunk|test:whole-chunk>
2366     <item>if (1) {
2368     <item> \ =\<less\>\\chunkref{test:say-hello}\<gtr\>
2370     <item>}
2371   </nf-chunk||>
2373   <\nf-chunk|test:say-hello>
2374     <item>print "hello";
2375   </nf-chunk||>
2377   But this is not fine; the chunk <nf-ref|test:hidden-else|> is not properly
2378   cromulent.
2380   <\nf-chunk|test:partial-chunk>
2381     <item>if (1) {
2383     <item> \ =\<less\>\\chunkref{test:hidden-else}\<gtr\>
2385     <item>}
2386   </nf-chunk||>
2388   <\nf-chunk|test:hidden-else>
2389     <item> \ print "I'm fine";
2391     <item>} else {
2393     <item> \ print "I'm not";
2394   </nf-chunk||>
2396   These tests will check for correct behaviour:
2398   <\nf-chunk|test:cromulence>
2399     <item>echo Cromulence test
2401     <item>passtest $FANGLE -Rtest:whole-chunk $TEX_SRC &\<gtr\>/dev/null \|\|
2402     ( echo "Whole chunk failed" && exit 1 )
2404     <item>failtest $FANGLE -Rtest:partial-chunk $TEX_SRC &\<gtr\>/dev/null
2405     \|\| ( echo "Partial chunk failed" && exit 1 )
2406   </nf-chunk||>
2408   <subsection|Tracker>
2410   We must avoid recursion as a language construct because we intend to employ
2411   mode-tracking to track language mode of emitted code, and the code is
2412   emitted from a function which is itself recursive, so instead we implement
2413   psuedo-recursion using our own stack based on a hash.
2415   <\nf-chunk|mode_tracker()>
2416     <item>function mode_tracker(context, text, values,\ 
2418     <item> \ # optional parameters
2420     <item> \ # local vars
2422     <item> \ mode, submodes, language,
2424     <item> \ cindex, c, a, part, item, name, result, new_values, new_mode,\ 
2426     <item> \ delimiters, terminators)
2428     <item>{
2429   </nf-chunk|awk|>
2431   We could be re-commencing with a valid context, so we need to setup the
2432   state according to the last context.
2434   <\nf-chunk|mode_tracker()>
2435     <item> \ cindex = context[""] + 0;
2437     <item> \ mode = context[cindex, "mode"];
2439     <item> \ language = context[cindex, "language" ];
2440   </nf-chunk||>
2442   First we construct a single large regex combining the possible sub-modes
2443   for the current mode along with the terminators for the current mode.
2445   <\nf-chunk|parse_chunk_args-reset-modes>
2446     <item> \ submodes=modes[language, mode, "submodes"];
2448     <item>
2450     <item> \ if ((language, mode, "delimiters") in modes) {
2452     <item> \ \ \ delimiters = modes[language, mode, "delimiters"];
2454     <item> \ \ \ if (length(submodes)\<gtr\>0) submodes = submodes "\|";
2456     <item> \ \ \ submodes=submodes delimiters;
2458     <item> \ } else delimiters="";
2460     <item> \ if ((language, mode, "terminators") in modes) {
2462     <item> \ \ \ terminators = modes[language, mode, "terminators"];
2464     <item> \ \ \ if (length(submodes)\<gtr\>0) submodes = submodes "\|";
2466     <item> \ \ \ submodes=submodes terminators;
2468     <item> \ } else terminators="";
2469   </nf-chunk||>
2471   If we don't find anything to match on --- probably because the language is
2472   not supported --- then we return the entire text without matching anything.
2474   <\nf-chunk|parse_chunk_args-reset-modes>
2475     <item> if (! length(submodes)) return text;
2476   </nf-chunk||>
2478   <\nf-chunk|mode_tracker()>
2479     <item>=\<less\>\\chunkref{parse_chunk_args-reset-modes}\<gtr\>
2480   </nf-chunk||>
2482   We then iterate the text (until there is none left) looking for sub-modes
2483   or terminators in the regex.
2485   <\nf-chunk|mode_tracker()>
2486     <item> \ while((cindex \<gtr\>= 0) && length(text)) {
2488     <item> \ \ \ if (match(text, "(" submodes ")", a)) {
2489   </nf-chunk||>
2491   A bug that creeps in regularly during development is bad regexes of zero
2492   length which result in an infinite loop (as no text is consumed), so I
2493   catch that right away with this test.
2495   <\nf-chunk|mode_tracker()>
2496     <item> \ \ \ \ \ if (RLENGTH\<less\>1) {
2498     <item> \ \ \ \ \ \ \ error(sprintf("Internal error, matched zero length
2499     submode, should be impossible - likely regex computation error\\n" \\
2501     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "Language=%s\\nmode=%s\\nmatch=%s\\n",
2502     language, mode, submodes));
2504     <item> \ \ \ \ \ }
2505   </nf-chunk||>
2507   part is defined as the text up to the sub-mode or terminator, and this is
2508   appended to item --- which is the current text being gathered. If a mode
2509   has a delimiter, then item is reset each time a delimiter is found.
2511   <math|<wide|<with|mode|prog|"><wide*|hello|\<wide-underbrace\>><rsub|item>,
2512   <wide*|there|\<wide-underbrace\>><rsub|item><with|mode|prog|">|\<wide-overbrace\>><rsup|item>,
2513   \ <wide|he said.|\<wide-overbrace\>><rsup|item>>
2515   <\nf-chunk|mode_tracker()>
2516     <item> \ \ \ \ \ part = substr(text, 1, RSTART -1);
2518     <item> \ \ \ \ \ item = item part;
2519   </nf-chunk||>
2521   We must now determine what was matched. If it was a terminator, then we
2522   must restore the previous mode.
2524   <\nf-chunk|mode_tracker()>
2525     <item> \ \ \ \ \ if (match(a[1], "^" terminators "$")) {
2527     <item>#printf("%2d EXIT \ MODE [%s] by [%s] [%s]\\n", cindex, mode, a[1],
2528     text) \<gtr\> "/dev/stderr"
2530     <item> \ \ \ \ \ \ \ context[cindex, "values", ++context[cindex,
2531     "values"]] = item;
2533     <item> \ \ \ \ \ \ \ delete context[cindex];
2535     <item> \ \ \ \ \ \ \ context[""] = --cindex;
2537     <item> \ \ \ \ \ \ \ if (cindex\<gtr\>=0) {
2539     <item> \ \ \ \ \ \ \ \ \ mode = context[cindex, "mode"];
2541     <item> \ \ \ \ \ \ \ \ \ language = context[cindex, "language"];
2543     <item> \ \ \ \ \ \ \ \ \ =\<less\>\\chunkref{parse_chunk_args-reset-modes}\<gtr\>
2545     <item> \ \ \ \ \ \ \ }
2547     <item> \ \ \ \ \ \ \ item = item a[1];
2549     <item> \ \ \ \ \ \ \ text = substr(text, 1 + length(part) +
2550     length(a[1]));
2552     <item> \ \ \ \ \ }
2553   </nf-chunk||>
2555   If a delimiter was matched, then we must store the current item in the
2556   parsed values array, and reset the item.
2558   <\nf-chunk|mode_tracker()>
2559     <item> \ \ \ \ \ else if (match(a[1], "^" delimiters "$")) {
2561     <item> \ \ \ \ \ \ \ if (cindex==0) {
2563     <item> \ \ \ \ \ \ \ \ \ context[cindex, "values", ++context[cindex,
2564     "values"]] = item;
2566     <item> \ \ \ \ \ \ \ \ \ item = "";
2568     <item> \ \ \ \ \ \ \ } else {
2570     <item> \ \ \ \ \ \ \ \ \ item = item a[1];
2572     <item> \ \ \ \ \ \ \ }
2574     <item> \ \ \ \ \ \ \ text = substr(text, 1 + length(part) +
2575     length(a[1]));
2577     <item> \ \ \ \ \ }
2578   </nf-chunk||>
2580   otherwise, if a new submode is detected (all submodes have terminators), we
2581   must create a nested parse context until we find the terminator for this
2582   mode.
2584   <\nf-chunk|mode_tracker()>
2585     <item> else if ((language, a[1], "terminators") in modes) {
2587     <item> \ \ \ \ \ \ \ #check if new_mode is defined
2589     <item> \ \ \ \ \ \ \ item = item a[1];
2591     <item>#printf("%2d ENTER MODE [%s] in [%s]\\n", cindex, a[1], text)
2592     \<gtr\> "/dev/stderr"
2594     <item> \ \ \ \ \ \ \ text = substr(text, 1 + length(part) +
2595     length(a[1]));
2597     <item> \ \ \ \ \ \ \ context[""] = ++cindex;
2599     <item> \ \ \ \ \ \ \ context[cindex, "mode"] = a[1];
2601     <item> \ \ \ \ \ \ \ context[cindex, "language"] = language;
2603     <item> \ \ \ \ \ \ \ mode = a[1];
2605     <item> \ \ \ \ \ \ \ =\<less\>\\chunkref{parse_chunk_args-reset-modes}\<gtr\>
2607     <item> \ \ \ \ \ } else {
2609     <item> \ \ \ \ \ \ \ error(sprintf("Submode '%s' set unknown mode in
2610     text: %s\\nLanguage %s Mode %s\\n", a[1], text, language, mode));
2612     <item> \ \ \ \ \ \ \ text = substr(text, 1 + length(part) +
2613     length(a[1]));
2615     <item> \ \ \ \ \ }
2617     <item> \ \ \ }
2618   </nf-chunk||>
2620   In the final case, we parsed to the end of the string. If the string was
2621   entire, then we should have no nested mode context, but if the string was
2622   just a fragment we may have a mode context which must be preserved for the
2623   next fragment. Todo: Consideration ought to be given if sub-mode strings
2624   are split over two fragments.
2626   <\nf-chunk|mode_tracker()>
2627     <item>else {
2629     <item> \ \ \ \ \ context[cindex, "values", ++context[cindex, "values"]] =
2630     item text;
2632     <item> \ \ \ \ \ text = "";
2634     <item> \ \ \ \ \ item = "";
2636     <item> \ \ \ }
2638     <item> \ }
2640     <item>
2642     <item> \ context["item"] = item;
2644     <item>
2646     <item> \ if (length(item)) context[cindex, "values", ++context[cindex,
2647     "values"]] = item;
2649     <item> \ return text;
2651     <item>}
2652   </nf-chunk||>
2654   <subsubsection|One happy chunk>
2656   All the mode tracker chunks are referred to here:
2658   <\nf-chunk|mode-tracker>
2659     <item><nf-ref|new_mode_tracker()|>
2661     <item><nf-ref|mode_tracker()|>
2662   </nf-chunk||>
2664   <subsubsection|Tests>
2666   We can test this function like this:
2668   <\nf-chunk|pca-test.awk>
2669     <item>=\<less\>\\chunkref{error()}\<gtr\>
2671     <item>=\<less\>\\chunkref{mode-tracker}\<gtr\>
2673     <item>=\<less\>\\chunkref{parse_chunk_args()}\<gtr\>
2675     <item>BEGIN {
2677     <item> \ SUBSEP=".";
2679     <item> \ =\<less\>\\chunkref{mode-definitions}\<gtr\>
2681     <item>
2683     <item> \ =\<less\>\\chunkref{test:mode-definitions}\<gtr\>
2685     <item>}
2686   </nf-chunk|awk|>
2688   <\nf-chunk|pca-test.awk:summary>
2689     <item>if (e) {
2691     <item> \ printf "Failed " e
2693     <item> \ for (b in a) {
2695     <item> \ \ \ print "a[" b "] =\<gtr\> " a[b];
2697     <item> \ }
2699     <item>} else {
2701     <item> \ print "Passed"
2703     <item>}
2705     <item>split("", a);
2707     <item>e=0;
2708   </nf-chunk|awk|>
2710   which should give this output:
2712   <\nf-chunk|pca-test.awk-results>
2713     <item>a[foo.quux.quirk] =\<gtr\>\ 
2715     <item>a[foo.quux.a] =\<gtr\> fleeg
2717     <item>a[foo.bar] =\<gtr\> baz
2719     <item>a[etc] =\<gtr\>\ 
2721     <item>a[name] =\<gtr\> freddie
2722   </nf-chunk||>
2724   <section|Escaping and Quoting>
2726   For the time being and to get around <TeXmacs> inability to export a
2727   <kbd|TAB> character, the right arrow <with|mode|math|\<mapsto\>> whose
2728   UTF-8 sequence is ...
2730   <todo|complete>
2732   Another special character is used, the left-arrow
2733   <with|mode|math|\<mapsfrom\>> with UTF-8 sequence 0xE2 0x86 0xA4 is used to
2734   strip any preceding white space as a way of un-tabbing and removing indent
2735   that has been applied <emdash> this is important for bash here documents,
2736   and the like. It's a filthy hack.
2738   <todo|remove the hack>
2740   <\nf-chunk|mode_tracker>
2741     \;
2743     <item>function untab(text) {
2745     <item> \ gsub("[[:space:]]*\\xE2\\x86\\xA4","", text);
2747     <item> \ return text;
2749     <item>}
2750   </nf-chunk||>
2752   Each nested mode can optionally define a set of transforms to be applied to
2753   any text that is included from another language.
2755   This code can perform transforms
2757   <\nf-chunk|mode_tracker>
2758     <item>function transform_escape(s, r, text,
2760     <item> \ \ \ # optional
2762     <item> \ \ \ max,\ 
2764     <item> \ \ \ \ \ \ \ # local vars
2766     <item> \ \ \ \ \ \ \ c)
2768     <item>{
2770     <item> \ for(c=1; c \<less\>= max && (c in s); c++) {
2772     <item> \ \ \ gsub(s[c], r[c], text);
2774     <item> \ }
2776     <item> \ return text;
2778     <item>}
2779   </nf-chunk|awk|>
2781   This function must append from index c onwards, and escape transforms from
2782   the supplied context, and return c + number of new transforms.
2784   <\nf-chunk|mode_tracker>
2785     <item>function mode_escaper(context, s, r, src,
2787     <item> \ c, cp, cpl)
2789     <item>{
2791     <item> \ for(c = context[""]; c \<gtr\>= 0; c--) {
2793     <item> \ \ \ if ( (context[c, "language"], context[c, "mode"]) in
2794     escapes) {
2796     <item> \ \ \ \ \ cpl = escapes[context[c, "language"], context[c,
2797     "mode"]];
2799     <item> \ \ \ \ \ for (cp = 1; cp \<less\>= cpl; cp ++) {
2801     <item> \ \ \ \ \ \ \ ++src;
2803     <item> \ \ \ \ \ \ \ s[src] = escapes[context[c, "language"], context[c,
2804     "mode"], cp, "s"];
2806     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ r[src]
2807     = escapes[context[c, "language"], context[c, "mode"], cp, "r"];
2809     <item> \ \ \ \ \ }
2811     <item> \ \ \ }
2813     <item> \ }
2815     <item> \ return src;
2817     <item>}
2819     <item>function dump_escaper(c, s, r, cc) {
2821     <item> \ for(cc=1; cc\<less\>=c; cc++) {
2823     <item> \ \ \ printf("%2d s[%s] r[%s]\\n", cc, s[cc], r[cc]) \<gtr\>
2824     "/dev/stderr"
2826     <item> \ }
2828     <item>}
2829   </nf-chunk|awk|>
2831   <\nf-chunk|test:escapes>
2832     <item>echo escapes test
2834     <item>passtest $FANGLE -Rtest:comment-quote $TEX_SRC &\<gtr\>/dev/null
2835     \|\| ( echo "Comment-quote failed" && exit 1 )
2836   </nf-chunk|sh|>
2838   <chapter|Recognizing Chunks>
2840   Fangle recognizes noweb chunks, but as we also want better <LaTeX>
2841   integration we will recognize any of these:
2843   <\itemize>
2844     <item>notangle chunks matching the pattern
2845     <verbatim|^\<less\>\<less\>.*?\<gtr\>\<gtr\>=>
2847     <item>chunks beginning with <verbatim|\\begin{lstlistings}>, possibly
2848     with <verbatim|\\Chunk{...}> on the previous line
2850     <item>an older form I have used, beginning with
2851     <verbatim|\\begin{Chunk}[options]> --- also more suitable for plain
2852     <LaTeX> users<\footnote>
2853       Is there such a thing as plain <LaTeX>?
2854     </footnote>.
2855   </itemize>
2857   <section|Chunk start>
2859   The variable chunking is used to signify that we are processing a code
2860   chunk and not document. In such a state, input lines will be assigned to
2861   the current chunk; otherwise they are ignored.
2863   <subsection|<TeXmacs>>
2865   We don't handle <TeXmacs> files natively yet, but rather instead emit
2866   unicode character sequences to mark up the text-export file which we do
2867   process.
2869   These hacks detect the unicode character sequences and retro-fit in the old
2870   <TeX> parsing.
2872   We convert <math|\<mapsto\>> into a tab character.
2874   <\nf-chunk|recognize-chunk>
2875     \;
2877     <item>#/\\n/ {
2879     <item># \ gsub("\\n*$","");
2881     <item># \ gsub("\\n", " ");
2883     <item>#}
2885     <item>#===
2887     <item>/\\xE2\\x86\\xA6/ {
2889     <item> \ gsub("\\\\xE2\\\\x86\\\\xA6", "\\x09");
2891     <item>}
2892   </nf-chunk||>
2894   <TeXmacs> back-tick handling is obscure, and a cut-n-paste back-tick from a
2895   shell window comes out as a unicode sequence<\footnote>
2896     that won't export to html, except as a NULL character (literal 0x00)
2897   </footnote> that is fixed-up here.
2899   <\nf-chunk|recognize-chunk>
2900     <item>
2902     <item>/\\xE2\\x80\\x98/ {
2904     <item> \ gsub("\\\\xE2\\\\x80\\\\x98", "`");
2906     <item>}
2907   </nf-chunk||>
2909   In the <TeXmacs> output, the start of a chunk will appear like this:
2911   <verbatim| \ 5b\<less\>example-chunk<key|^K>[1](arg1,<key|^K>
2912   arg2<key|^K><key|^K>), lang=C\<gtr\> <math|\<equiv\>>>
2914   We detect the the start of a <TeXmacs> chunk by detecting the
2915   <math|\<equiv\>> symbol which occurs near the end of the line. We obtain
2916   the chunk name, the chunk parameters, and the chunk language.
2918   <\nf-chunk|recognize-chunk>
2919     <item>
2921     <item>/\\xE2\\x89\\xA1/ {
2923     <item> \ if (match($0, "^ *([^[ ]* \|)\<less\>([^[
2924     ]*)\\\\[[0-9]*\\\\][(](.*)[)].*, lang=([^ ]*)\<gtr\>", line)) {
2926     <item> \ \ \ next_chunk_name=line[2];
2928     <item> \ \ \ get_texmacs_chunk_args(line[3], next_chunk_params);
2930     <item> \ \ \ gsub(ARG_SEPARATOR ",? ?", ";", line[3]);
2932     <item> \ \ \ params = "params=" line[3];
2934     <item> \ \ \ if ((line[4])) {
2936     <item> \ \ \ \ \ params = params ",language=" line[4]
2938     <item> \ \ \ }
2940     <item> \ \ \ get_tex_chunk_args(params, next_chunk_opts);
2942     <item> \ \ \ new_chunk(next_chunk_name, next_chunk_opts,
2943     next_chunk_params);
2945     <item> \ \ \ texmacs_chunking = 1;
2947     <item> \ } else {
2949     <item> \ \ \ warning(sprintf("Unexpected chunk match: %s\\n", $_))
2951     <item> \ }
2953     <item> \ next;
2955     <item>}
2956   </nf-chunk||>
2958   <subsection|lstlistings>
2960   Our current scheme is to recognize the new lstlisting chunks, but these may
2961   be preceded by a <verbatim|\\Chunk> command which in <LyX> is a more
2962   convenient way to pass the chunk name to the
2963   <verbatim|\\begin{lstlistings}> command, and a more visible way to specify
2964   other <verbatim|lstset> settings.
2966   The arguments to the <verbatim|\\Chunk> command are a name, and then a
2967   comma-seperated list of key-value pairs after the manner of
2968   <verbatim|\\lstset>. (In fact within the <LaTeX> <verbatim|\\Chunk> macro
2969   (section <reference|sub:The-chunk-command>) the text <verbatim|name=> is
2970   prefixed to the argument which is then literally passed to
2971   <verbatim|\\lstset>).
2973   <\nf-chunk|recognize-chunk>
2974     <item>/^\\\\Chunk{/ {
2976     <item> \ if (match($0, "^\\\\\\\\Chunk{ *([^ ,}]*),?(.*)}", line)) {
2978     <item> \ \ \ next_chunk_name = line[1];
2980     <item> \ \ \ get_tex_chunk_args(line[2], next_chunk_opts);
2982     <item> \ }
2984     <item> \ next;
2986     <item>}
2987   </nf-chunk|awk|>
2989   We also make a basic attempt to parse the name out of the
2990   <verbatim|\\lstlistings[name=chunk-name]> text, otherwise we fall back to
2991   the name found in the previous chunk command. This attempt is very basic
2992   and doesn't support commas or spaces or square brackets as part of the
2993   chunkname. We also recognize <verbatim|\\begin{Chunk}> which is convenient
2994   for some users<\footnote>
2995     but not yet supported in the <LaTeX> macros
2996   </footnote>.
2998   <\nf-chunk|recognize-chunk>
2999     <item>/^\\\\begin{lstlisting}\|^\\\\begin{Chunk}/ {
3001     <item> \ if (match($0, "}.*[[,] *name= *{? *([^], }]*)", line)) {
3003     <item> \ \ \ new_chunk(line[1]);
3005     <item> \ } else {
3007     <item> \ \ \ new_chunk(next_chunk_name, next_chunk_opts);
3009     <item> \ }
3011     <item> \ chunking=1;
3013     <item> \ next;
3015     <item>}
3016   </nf-chunk||>
3018   <section|Chunk Body>
3020   <subsection|<TeXmacs>>
3022   A chunk body in <TeXmacs> ends with <verbatim|\|________>... if it is the
3023   final chunklet of a chunk, or if there are further chunklets it ends with
3024   <verbatim|\|\\/\\/\\/>... which is a depiction of a jagged line of torn
3025   paper.
3027   <\nf-chunk|recognize-chunk>
3028     <item>/^ *\\\|____________*/ && texmacs_chunking {
3030     <item> \ active_chunk="";
3032     <item> \ texmacs_chunking=0;
3034     <item> \ chunking=0;
3036     <item>}
3038     <item>/^ *\\\|\\/\\\\/ && texmacs_chunking {
3040     <item> \ texmacs_chunking=0;
3042     <item> \ chunking=0;
3044     <item> \ active_chunk="";
3046     <item>}
3047   </nf-chunk||>
3049   It has been observed that not every line of output when a <TeXmacs> chunk
3050   is active is a line of chunk. This may no longer be true, but we set a
3051   variable <verbatim|texmacs_chunk> if the current line is a chunk line.
3053   Initially we set this to zero...
3055   <\nf-chunk|recognize-chunk>
3056     <item>texmacs_chunk=0;
3057   </nf-chunk||>
3059   ...and then we look to see if the current line is a chunk line.
3061   <TeXmacs> lines look like this: <verbatim| \ 3 \| main() {> so we detect
3062   the lines by leading white space, digits, more whiter space and a vertical
3063   bar followed by at least once space.
3065   If we find such a line, we remove this line-header and set
3066   <verbatim|texmacs_chunk=1> as well as <verbatim|chunking=1>
3068   <\nf-chunk|recognize-chunk>
3069     <item>/^ *[1-9][0-9]* *\\\| / {
3071     <item> \ if (texmacs_chunking) {
3073     <item> \ \ \ chunking=1;
3075     <item> \ \ \ texmacs_chunk=1;
3077     <item> \ \ \ gsub("^ *[1-9][0-9]* *\\\\\| ", "")
3079     <item> \ }
3081     <item>}
3082   </nf-chunk||>
3084   When <TeXmacs> chunking, lines that commence with <verbatim|\\/> or
3085   <verbatim|__> are not chunk content but visual framing, and are skipped.
3087   <\nf-chunk|recognize-chunk>
3088     <item>/^ *\\.\\/\\\\/ && texmacs_chunking {
3090     <item> \ next;
3092     <item>}
3094     <item>/^ *__*$/ && texmacs_chunking {
3096     <item> \ next;
3098     <item>}
3099   </nf-chunk||>
3101   Any other line when <TeXmacs> chunking is considered to be a line-wrapped
3102   line.
3104   <\nf-chunk|recognize-chunk>
3105     <item>texmacs_chunking {
3107     <item> \ if (! texmacs_chunk) {
3109     <item> \ \ \ # must be a texmacs continued line
3111     <item> \ \ \ chunking=1;
3113     <item> \ \ \ texmacs_chunk=1;
3115     <item> \ }
3117     <item>}
3118   </nf-chunk||>
3120   This final chunklet seems bogus and probably stops <LyX> working.
3122   <\nf-chunk|recognize-chunk>
3123     <item>! texmacs_chunk {
3125     <item># \ texmacs_chunking=0;
3127     <item> \ chunking=0;
3129     <item>}
3130   </nf-chunk||>
3132   <subsection|Noweb>
3134   We recognize notangle style chunks too:
3136   <\nf-chunk|recognize-chunk>
3137     <item>/^[\<less\>]\<less\>.*[\<gtr\>]\<gtr\>=/ {
3139     <item> \ if (match($0, "^[\<less\>]\<less\>(.*)[\<gtr\>]\<gtr\>= *$",
3140     line)) {
3142     <item> \ \ \ chunking=1;
3144     <item> \ \ \ notangle_mode=1;
3146     <item> \ \ \ new_chunk(line[1]);
3148     <item> \ \ \ next;
3150     <item> \ }
3152     <item>}
3153   </nf-chunk|awk|>
3155   <section|Chunk end>
3157   Likewise, we need to recognize when a chunk ends.
3159   <subsection|lstlistings>
3161   The <verbatim|e> in <verbatim|[e]nd{lislisting}> is surrounded by square
3162   brackets so that when this document is processed, this chunk doesn't
3163   terminate early when the lstlistings package recognizes it's own
3164   end-string!<\footnote>
3165     This doesn't make sense as the regex is anchored with ^, which this line
3166     does not begin with!
3167   </footnote>
3169   <\nf-chunk|recognize-chunk>
3170     <item>/^\\\\[e]nd{lstlisting}\|^\\\\[e]nd{Chunk}/ {
3172     <item> \ chunking=0;
3174     <item> \ active_chunk="";
3176     <item> \ next;
3178     <item>}
3179   </nf-chunk||>
3181   <subsection|noweb>
3183   <\nf-chunk|recognize-chunk>
3184     <item>/^@ *$/ {
3186     <item> \ chunking=0;
3188     <item> \ active_chunk="";
3190     <item>}
3191   </nf-chunk||>
3193   All other recognizers are only of effect if we are chunking; there's no
3194   point in looking at lines if they aren't part of a chunk, so we just ignore
3195   them as efficiently as we can.
3197   <\nf-chunk|recognize-chunk>
3198     <item>! chunking { next; }
3199   </nf-chunk||>
3201   <section|Chunk contents>
3203   Chunk contents are any lines read while <verbatim|chunking> is true. Some
3204   chunk contents are special in that they refer to other chunks, and will be
3205   replaced by the contents of these chunks when the file is generated.
3207   <label|sub:ORS-chunk-text>We add the output record separator <verbatim|ORS>
3208   to the line now, because we will set <verbatim|ORS> to the empty string
3209   when we generate the output<\footnote>
3210     So that we can partial print lines using <verbatim|print> instead of
3211     <verbatim|printf>. <todo|This does't make sense>
3212   </footnote>.
3214   <\nf-chunk|recognize-chunk>
3215     <item>length(active_chunk) {
3217     <item> \ <nf-ref|process-chunk-tabs|>
3219     <item> \ <nf-ref|process-chunk|>
3221     <item>}
3222   </nf-chunk||>
3224   If a chunk just consisted of plain text, we could handle the chunk like
3225   this:
3227   <\nf-chunk|process-chunk-simple>
3228     <item>chunk_line(active_chunk, $0 ORS);
3229   </nf-chunk||>
3231   but in fact a chunk can include references to other chunks. Chunk includes
3232   are traditionally written as <verbatim|\<less\>\<less\>chunk-name\<gtr\>\<gtr\>>
3233   but we support other variations, some of which are more suitable for
3234   particular editing systems.
3236   However, we also process tabs at this point. A tab at input can be replaced
3237   by a number of spaces defined by the <verbatim|tabs> variable, set by the
3238   <verbatim|-T> option. Of course this is poor tab behaviour, we should
3239   probably have the option to use proper counted tab-stops and process this
3240   on output.
3242   <\nf-chunk|process-chunk-tabs>
3243     <item>if (length(tabs)) {
3245     <item> \ gsub("\\t", tabs);
3247     <item>}
3248   </nf-chunk||>
3250   <subsection|lstlistings><label|sub:lst-listings-includes>
3252   If <verbatim|\\lstset{escapeinside={=\<less\>}{\<gtr\>}}> is set, then we
3253   can use <verbatim|=\<less\>\\chunkref{chunk-name}\<gtr\>> in listings. The
3254   sequence <verbatim|=\<less\>> was chosen because:
3256   <\enumerate>
3257     <item>it is a better mnemonic than <verbatim|\<less\>\<less\>chunk-name\<gtr\>\<gtr\>>
3258     in that the <verbatim|=> sign signifies equivalence or substitutability.
3260     <item>and because <verbatim|=\<less\>> is not valid in C or any language
3261     I can think of.
3263     <item>and also because lstlistings doesn't like <verbatim|\<gtr\>\<gtr\>>
3264     as an end delimiter for the <em|texcl> escape, so we must make do with a
3265     single <verbatim|\<gtr\>> which is better complemented by
3266     <verbatim|=\<less\>> than by <verbatim|\<less\>\<less\>>.
3267   </enumerate>
3269   Unfortunately the <verbatim|=\<less\>...\<gtr\>> that we use re-enters a
3270   <LaTeX> parsing mode in which some characters are special, e.g. <verbatim|#
3271   \\> and so these cause trouble if used in arguments to
3272   <verbatim|\\chunkref>. At some point I must fix the <LaTeX> command
3273   <verbatim|\\chunkref> so that it can accept these literally, but until
3274   then, when writing chunkref argumemts that need these characters, I must
3275   use the forms <verbatim|\\textbackslash{}> and <verbatim|\\#>; so I also
3276   define a hacky chunk <verbatim|delatex> to be used further on whose purpose
3277   it is to remove these from any arguments parsed by fangle.
3279   <\nf-chunk|delatex>
3280     <item># FILTHY HACK
3282     <item>gsub("\\\\\\\\#", "#", ${text});
3284     <item>gsub("\\\\\\\\textbackslash{}", "\\\\", ${text});
3286     <item>gsub("\\\\\\\\\\\\^", "^", ${text});
3287   </nf-chunk||<tuple|text>>
3289   As each chunk line may contain more than one chunk include, we will split
3290   out chunk includes in an iterative fashion<\footnote>
3291     Contrary to our use of split when substituting parameters in chapter
3292     <reference|Here-we-split>
3293   </footnote>.
3295   First, as long as the chunk contains a <verbatim|\\chunkref> command we
3296   take as much as we can up to the first <verbatim|\\chunkref> command.
3298   <TeXmacs> text output uses <math|\<langle\>>...<math|\<rangle\>> which
3299   comes out as unicode sequences <verbatim|0xC2> <verbatim|0xAB> ...
3300   <verbatim|0xC2> <verbatim|0xBB>. Modern awk will interpret
3301   <verbatim|[^\\xC2\\xBB]> as a single unicode character if <verbatim|LANG>
3302   is set correctly to the sub-type <verbatim|UTF-8>, e.g.
3303   <verbatim|LANG=en_GB.UTF-8>, otherwise <verbatim|[^\\xC2\\xBB]> will be
3304   treated as a two character negated match <emdash> but this should not
3305   interfere with the function.
3307   <\nf-chunk|process-chunk>
3308     <item>chunk = $0;
3310     <item>indent = 0;
3312     <item>while(match(chunk,"(\\xC2\\xAB)([^\\xC2\\xBB]*)
3313     [^\\xC2\\xBB]*\\xC2\\xBB", line) \|\|
3315     <item> \ \ \ \ \ match(chunk,\ 
3317     <item> \ \ \ \ \ \ \ \ \ \ \ "([=]\<less\>\\\\\\\\chunkref{([^}\<gtr\>]*)}(\\\\(.*\\\\)\|)\<gtr\>\|\<less\>\<less\>([a-zA-Z_][-a-zA-Z0-9_]*)\<gtr\>\<gtr\>)",\ 
3319     <item> \ \ \ \ \ \ \ \ \ \ \ line)\\
3321     <item>) {
3323     <item> \ chunklet = substr(chunk, 1, RSTART - 1);
3324   </nf-chunk||>
3326   We keep track of the indent count, by counting the number of literal
3327   characters found. We can then preserve this indent on each output line when
3328   multi-line chunks are expanded.
3330   We then process this first part literal text, and set the chunk which is
3331   still to be processed to be the text after the <verbatim|\\chunkref>
3332   command, which we will process next as we continue around the loop.
3334   <\nf-chunk|process-chunk>
3335     <item> \ indent += length(chunklet);
3337     <item> \ chunk_line(active_chunk, chunklet);
3339     <item> \ chunk = substr(chunk, RSTART + RLENGTH);
3340   </nf-chunk||>
3342   We then consider the type of chunk command we have found, whether it is the
3343   fangle style command beginning with <verbatim|=\<less\>> the older notangle
3344   style beginning with <verbatim|\<less\>\<less\>>.
3346   Fangle chunks may have parameters contained within square brackets. These
3347   will be matched in <verbatim|line[3]> and are considered at this stage of
3348   processing to be part of the name of the chunk to be included.
3350   <\nf-chunk|process-chunk>
3351     <item> \ if (substr(line[1], 1, 1) == "=") {
3353     <item> \ \ \ # chunk name up to }
3355     <item> \ \ \ \ \ \ \ =\<less\>\\chunkref{delatex}(line[3])\<gtr\>
3357     <item> \ \ \ chunk_include(active_chunk, line[2] line[3], indent);
3359     <item> \ } else if (substr(line[1], 1, 1) == "\<less\>") {
3361     <item> \ \ \ chunk_include(active_chunk, line[4], indent);
3363     <item> \ } else if (line[1] == "\\xC2\\xAB") {
3365     <item> \ \ \ chunk_include(active_chunk, line[2], indent);
3367     <item> \ } else {
3369     <item> \ \ \ error("Unknown chunk fragment: " line[1]);
3371     <item> \ }
3372   <|nf-chunk>
3373     \;
3374   </nf-chunk|>
3376   The loop will continue until there are no more chunkref statements in the
3377   text, at which point we process the final part of the chunk.
3379   <\nf-chunk|process-chunk>
3380     <item>}
3382     <item>chunk_line(active_chunk, chunk);
3383   </nf-chunk||>
3385   <label|lone-newline>We add the newline character as a chunklet on it's own,
3386   to make it easier to detect new lines and thus manage indentation when
3387   processing the output.
3389   <\nf-chunk|process-chunk>
3390     <item>chunk_line(active_chunk, "\\n");
3391   <|nf-chunk>
3392     \;
3393   </nf-chunk|>
3395   We will also permit a chunk-part number to follow in square brackets, so
3396   that <verbatim|=\<less\>\\chunkref{chunk-name[1]}\<gtr\>> will refer to the
3397   first part only. This can make it easy to include a C function prototype in
3398   a header file, if the first part of the chunk is just the function
3399   prototype without the trailing semi-colon. The header file would include
3400   the prototype with the trailing semi-colon, like this:
3402   <verbatim|=\<less\>\\chunkref{chunk-name[1]}\<gtr\>>
3404   This is handled in section <reference|sub:Chunk-parts>
3406   We should perhaps introduce a notion of language specific chunk options; so
3407   that perhaps we could specify:
3409   <verbatim|=\<less\>\\chunkref{chunk-name[function-declaration]}>
3411   which applies a transform <verbatim|function-declaration> to the chunk ---
3412   which in this case would extract a function prototype from a function.
3413   <todo|Do it>
3415   <chapter|Processing Options>
3417   At the start, first we set the default options.
3419   <\nf-chunk|default-options>
3420     <item>debug=0;
3422     <item>linenos=0;
3424     <item>notangle_mode=0;
3426     <item>root="*";
3428     <item>tabs = "";
3429   </nf-chunk||>
3431   Then we use getopt the standard way, and null out ARGV afterwards in the
3432   normal AWK fashion.
3434   <\nf-chunk|read-options>
3435     <item>Optind = 1 \ \ \ # skip ARGV[0]
3437     <item>while(getopt(ARGC, ARGV, "R:LdT:hr")!=-1) {
3439     <item> \ =\<less\>\\chunkref{handle-options}\<gtr\>
3441     <item>}
3443     <item>for (i=1; i\<less\>Optind; i++) { ARGV[i]=""; }
3444   </nf-chunk||>
3446   This is how we handle our options:
3448   <\nf-chunk|handle-options>
3449     <item>if (Optopt == "R") root = Optarg;
3451     <item>else if (Optopt == "r") root="";
3453     <item>else if (Optopt == "L") linenos = 1;
3455     <item>else if (Optopt == "d") debug = 1;
3457     <item>else if (Optopt == "T") tabs = indent_string(Optarg+0);
3459     <item>else if (Optopt == "h") help();
3461     <item>else if (Optopt == "?") help();
3462   </nf-chunk||>
3464   We do all of this at the beginning of the program
3466   <\nf-chunk|begin>
3467     <item>BEGIN {
3469     <item> \ =\<less\>\\chunkref{constants}\<gtr\>
3471     <item> \ =\<less\>\\chunkref{mode-definitions}\<gtr\>
3473     <item> \ =\<less\>\\chunkref{default-options}\<gtr\>
3475     <item>
3477     <item> \ =\<less\>\\chunkref{read-options}\<gtr\>
3479     <item>}
3480   </nf-chunk||>
3482   And have a simple help function
3484   <\nf-chunk|help()>
3485     <item>function help() {
3487     <item> \ print "Usage:"
3489     <item> \ print " \ fangle [-L] -R\<less\>rootname\<gtr\> [source.tex
3490     ...]"
3492     <item> \ print " \ fangle -r [source.tex ...]"
3494     <item> \ print " \ If the filename, source.tex is not specified then
3495     stdin is used"
3497     <item> \ print
3499     <item> \ print "-L causes the C statement: #line \<less\>lineno\<gtr\>
3500     \\"filename\\"" to be issued"
3502     <item> \ print "-R causes the named root to be written to stdout"
3504     <item> \ print "-r lists all roots in the file (even those used
3505     elsewhere)"
3507     <item> \ exit 1;
3509     <item>}
3510   </nf-chunk||>
3512   <chapter|Generating the Output>
3514   We generate output by calling output_chunk, or listing the chunk names.
3516   <\nf-chunk|generate-output>
3517     <item>if (length(root)) output_chunk(root);
3519     <item>else output_chunk_names();
3520   </nf-chunk||>
3522   We also have some other output debugging:
3524   <\nf-chunk|debug-output>
3525     <item>if (debug) {
3527     <item> \ print "------ chunk names "
3529     <item> \ output_chunk_names();
3531     <item> \ print "====== chunks"
3533     <item> \ output_chunks();
3535     <item> \ print "++++++ debug"
3537     <item> \ for (a in chunks) {
3539     <item> \ \ \ print a "=" chunks[a];
3541     <item> \ }
3543     <item>}
3544   </nf-chunk||>
3546   We do both of these at the end. We also set <verbatim|ORS=""> because each
3547   chunklet is not necessarily a complete line, and we already added
3548   <verbatim|ORS> to each input line in section
3549   <reference|sub:ORS-chunk-text>.
3551   <\nf-chunk|end>
3552     <item>END {
3554     <item> \ =\<less\>\\chunkref{debug-output}\<gtr\>
3556     <item> \ ORS="";
3558     <item> \ =\<less\>\\chunkref{generate-output}\<gtr\>
3560     <item>}
3561   </nf-chunk||>
3563   We write chunk names like this. If we seem to be running in notangle
3564   compatibility mode, then we enclose the name like this
3565   <verbatim|\<less\>\<less\>name\<gtr\>\<gtr\>> the same way notangle does:
3567   <\nf-chunk|output_chunk_names()>
3568     <item>function output_chunk_names( \ \ c, prefix, suffix)\ 
3570     <item>{
3572     <item> \ if (notangle_mode) {
3574     <item> \ \ \ prefix="\<less\>\<less\>";
3576     <item> \ \ \ suffix="\<gtr\>\<gtr\>";
3578     <item> \ }
3580     <item> \ for (c in chunk_names) {
3582     <item> \ \ \ print prefix c suffix "\\n";
3584     <item> \ }
3586     <item>}
3587   </nf-chunk||>
3589   This function would write out all chunks
3591   <\nf-chunk|output_chunks()>
3592     <item>function output_chunks( \ a)\ 
3594     <item>{
3596     <item> \ for (a in chunk_names) {
3598     <item> \ \ \ output_chunk(a);
3600     <item> \ }
3602     <item>}
3604     <item>
3606     <item>function output_chunk(chunk) {
3608     <item> \ newline = 1;
3610     <item> \ lineno_needed = linenos;
3612     <item>
3614     <item> \ write_chunk(chunk);
3616     <item>}
3618     <item>
3619   </nf-chunk||>
3621   <section|Assembling the Chunks>
3623   <verbatim|chunk_path> holds a string consisting of the names of all the
3624   chunks that resulted in this chunk being output. It should probably also
3625   contain the source line numbers at which each inclusion also occured.
3627   We first initialize the mode tracker for this chunk.
3629   <\nf-chunk|write_chunk()>
3630     <item>function write_chunk(chunk_name) {
3632     <item> \ =\<less\>\\chunkref{awk-delete-array}(context)\<gtr\>
3634     <item> \ return write_chunk_r(chunk_name, context);
3636     <item>}
3638     <item>
3640     <item>function write_chunk_r(chunk_name, context, indent, tail,
3642     <item> \ # optional vars
3644     <item> \ <with|font-shape|italic|chunk_path>, chunk_args,\ 
3646     <item> \ s, r, src, new_src,\ 
3648     <item> \ # local vars
3650     <item> \ chunk_params, part, max_part, part_line, frag, max_frag, text,\ 
3652     <item> \ chunklet, only_part, call_chunk_args, new_context)
3654     <item>{
3656     <item> \ if (debug) debug_log("write_chunk_r(" chunk_name ")");
3657   </nf-chunk||>
3659   <subsection|Chunk Parts><label|sub:Chunk-parts>
3661   As mentioned in section <reference|sub:lstlistings-includes>, a chunk name
3662   may contain a part specifier in square brackets, limiting the parts that
3663   should be emitted.
3665   <\nf-chunk|write_chunk()>
3666     <item> \ if (match(chunk_name, "^(.*)\\\\[([0-9]*)\\\\]$",
3667     chunk_name_parts)) {
3669     <item> \ \ \ chunk_name = chunk_name_parts[1];
3671     <item> \ \ \ only_part = chunk_name_parts[2];
3673     <item> \ }
3674   </nf-chunk||>
3676   We then create a mode tracker
3678   <\nf-chunk|write_chunk()>
3679     <item> =\<less\>\\chunkref{new-mode-tracker}(context, chunks[chunk_name,
3680     "language"], "")\<gtr\>
3681   </nf-chunk||>
3683   We extract into <verbatim|chunk_params> the names of the parameters that
3684   this chunk accepts, whose values were (optionally) passed in
3685   <verbatim|chunk_args>.
3687   <\nf-chunk|write_chunk()>
3688     <item> split(chunks[chunk_name, "params"], chunk_params, " *; *");
3689   </nf-chunk||>
3691   To assemble a chunk, we write out each part.
3693   <\nf-chunk|write_chunk()>
3694     <item> \ if (! (chunk_name in chunk_names)) {
3696     <item> \ \ \ error(sprintf(_"The root module
3697     \<less\>\<less\>%s\<gtr\>\<gtr\> was not defined.\\nUsed by: %s",\\
3699     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ chunk_name, chunk_path));
3701     <item> \ }
3703     <item>
3705     <item> \ max_part = chunks[chunk_name, "part"];
3707     <item> \ for(part = 1; part \<less\>= max_part; part++) {
3709     <item> \ \ \ if (! only_part \|\| part == only_part) {
3711     <item> \ \ \ \ \ =\<less\>\\chunkref{write-part}\<gtr\>
3713     <item> \ \ \ }
3715     <item> \ }
3717     <item> \ if (! finalize_mode_tracker(context)) {
3719     <item> \ \ \ dump_mode_tracker(context);
3721     <item> \ \ \ error(sprintf(_"Module %s did not close context
3722     properly.\\nUsed by: %s\\n", chunk_name, chunk_path));
3724     <item> \ }
3726     <item>}
3727   </nf-chunk||>
3729   A part can either be a chunklet of lines, or an include of another chunk.
3731   Chunks may also have parameters, specified in LaTeX style with braces after
3732   the chunk name --- looking like this in the document: chunkname{param1,
3733   param2}. Arguments are passed in square brackets:
3734   <verbatim|\\chunkref{chunkname}[arg1, arg2]>.
3736   Before we process each part, we check that the source position hasn't
3737   changed unexpectedly, so that we can know if we need to output a new
3738   file-line directive.
3740   <\nf-chunk|write-part>
3741     <item>=\<less\>\\chunkref{check-source-jump}\<gtr\>
3743     <item>
3745     <item>chunklet = chunks[chunk_name, "part", part];
3747     <item>if (chunks[chunk_name, "part", part, "type"] == part_type_chunk) {
3749     <item> \ =\<less\>\\chunkref{write-included-chunk}\<gtr\>
3751     <item>} else if (chunklet SUBSEP "line" in chunks) {
3753     <item> \ =\<less\>\\chunkref{write-chunklets}\<gtr\>
3755     <item>} else {
3757     <item> \ # empty last chunklet
3759     <item>}
3760   </nf-chunk||>
3762   To write an included chunk, we must detect any optional chunk arguments in
3763   parenthesis. Then we recurse calling <verbatim|write_chunk()>.
3765   <\nf-chunk|write-included-chunk>
3766     <item>if (match(chunklet, "^([^\\\\[\\\\(]*)\\\\((.*)\\\\)$",
3767     chunklet_parts)) {
3769     <item> \ chunklet = chunklet_parts[1];
3771     <item># hack
3773     <item>gsub(sprintf("%c",11), "", chunklet);
3775     <item>gsub(sprintf("%c",11), "", chunklet_parts[2]);
3777     <item> \ parse_chunk_args("c-like", chunklet_parts[2], call_chunk_args,
3778     "(");
3780     <item> \ for (c in call_chunk_args) {
3782     <item> \ \ \ call_chunk_args[c] = expand_chunk_args(call_chunk_args[c],
3783     chunk_params, chunk_args);
3785     <item> \ }
3787     <item>} else {
3789     <item> \ split("", call_chunk_args);
3791     <item>}
3793     <item># update the transforms arrays
3795     <item>new_src = mode_escaper(context, s, r, src);
3797     <item>=\<less\>\\chunkref{awk-delete-array}(new_context)\<gtr\>
3799     <item>write_chunk_r(chunklet, new_context,
3801     <item> \ \ \ \ \ \ \ \ \ \ \ chunks[chunk_name, "part", part, "indent"]
3802     indent,
3804     <item> \ \ \ \ \ \ \ \ \ \ \ chunks[chunk_name, "part", part, "tail"],
3806     <item> \ \ \ \ \ \ \ \ \ \ \ chunk_path "\\n \ \ \ \ \ \ \ \ "
3807     chunk_name,
3809     <item> \ \ \ \ \ \ \ \ \ \ \ call_chunk_args,
3811     <item> \ \ \ \ \ \ \ \ \ \ \ s, r, new_src);
3812   </nf-chunk||>
3814   Before we output a chunklet of lines, we first emit the file and line
3815   number if we have one, and if it is safe to do so.
3817   Chunklets are generally broken up by includes, so the start of a chunklet
3818   is a good place to do this. Then we output each line of the chunklet.
3820   When it is not safe, such as in the middle of a multi-line macro
3821   definition, <verbatim|lineno_suppressed> is set to true, and in such a case
3822   we note that we want to emit the line statement when it is next safe.
3824   <\nf-chunk|write-chunklets>
3825     <item>max_frag = chunks[chunklet, "line"];
3827     <item>for(frag = 1; frag \<less\>= max_frag; frag++) {
3829     <item> \ =\<less\>\\chunkref{write-file-line}\<gtr\>
3830   </nf-chunk||>
3832   We then extract the chunklet text and expand any arguments.
3834   <\nf-chunk|write-chunklets>
3835     <item>
3837     <item> \ text = chunks[chunklet, frag];
3839     <item>\ 
3841     <item> \ /* check params */
3843     <item> \ text = expand_chunk_args(text, chunk_params, chunk_args);
3844   </nf-chunk||>
3846   If the text is a single newline (which we keep separate - see
3847   <reference|lone-newline>) then we increment the line number. In the case
3848   where this is the last line of a chunk and it is not a top-level chunk we
3849   replace the newline with an empty string --- because the chunk that
3850   included this chunk will have the newline at the end of the line that
3851   included this chunk.
3853   We also note by <verbatim|newline = 1> that we have started a new line, so
3854   that indentation can be managed with the following piece of text.
3856   <\nf-chunk|write-chunklets>
3857     <item>
3859     <item> if (text == "\\n") {
3861     <item> \ \ \ lineno++;
3863     <item> \ \ \ if (part == max_part && frag == max_frag &&
3864     length(chunk_path)) {
3866     <item> \ \ \ \ \ text = "";
3868     <item> \ \ \ \ \ break;
3870     <item> \ \ \ } else {
3872     <item> \ \ \ \ \ newline = 1;
3874     <item> \ \ \ }
3875   </nf-chunk||>
3877   If this text does not represent a newline, but we see that we are the first
3878   piece of text on a newline, then we prefix our text with the current
3879   indent.\ 
3881   <\note>
3882     <verbatim|newline> is a global output-state variable, but the
3883     <verbatim|indent> is not.
3884   </note>
3886   <\nf-chunk|write-chunklets>
3887     <item> \ } else if (length(text) \|\| length(tail)) {
3889     <item> \ \ \ if (newline) text = indent text;
3891     <item> \ \ \ newline = 0;
3893     <item> \ }
3895     <item>
3896   </nf-chunk||>
3898   Tail will soon no longer be relevant once mode-detection is in place.
3900   <\nf-chunk|write-chunklets>
3901     <item> \ text = text tail;
3903     <item> \ mode_tracker(context, text);
3905     <item> \ print untab(transform_escape(s, r, text, src));
3906   </nf-chunk||>
3908   If a line ends in a backslash --- suggesting continuation --- then we
3909   supress outputting file-line as it would probably break the continued
3910   lines.
3912   <\nf-chunk|write-chunklets>
3913     <item> \ if (linenos) {
3915     <item> \ \ \ lineno_suppressed = substr(lastline, length(lastline)) ==
3916     "\\\\";
3918     <item> \ }
3920     <item>}
3921   </nf-chunk||>
3923   Of course there is no point in actually outputting the source filename and
3924   line number (file-line) if they don't say anything new! We only need to
3925   emit them if they aren't what is expected, or if we we not able to emit one
3926   when they had changed.
3928   <\nf-chunk|write-file-line>
3929     <item>if (newline && lineno_needed && ! lineno_suppressed) {
3931     <item> \ filename = a_filename;
3933     <item> \ lineno = a_lineno;
3935     <item> \ print "#line " lineno " \\"" filename "\\"\\n"
3937     <item> \ lineno_needed = 0;
3939     <item>}
3940   </nf-chunk||>
3942   We check if a new file-line is needed by checking if the source line
3943   matches what we (or a compiler) would expect.
3945   <\nf-chunk|check-source-jump>
3946     <item>if (linenos && (chunk_name SUBSEP "part" SUBSEP part SUBSEP
3947     "FILENAME" in chunks)) {
3949     <item> \ a_filename = chunks[chunk_name, "part", part, "FILENAME"];
3951     <item> \ a_lineno = chunks[chunk_name, "part", part, "LINENO"];
3953     <item> \ if (a_filename != filename \|\| a_lineno != lineno) {
3955     <item> \ \ \ lineno_needed++;
3957     <item> \ }
3959     <item>}
3960   </nf-chunk||>
3962   <chapter|Storing Chunks>
3964   Awk has pretty limited data structures, so we will use two main hashes.
3965   Uninterrupted sequences of a chunk will be stored in chunklets and the
3966   chunklets used in a chunk will be stored in <verbatim|chunks>.
3968   <\nf-chunk|constants>
3969     <item>part_type_chunk=1;
3971     <item>SUBSEP=",";
3972   </nf-chunk||>
3974   The params mentioned are not chunk parameters for parameterized chunks, as
3975   mentioned in <reference|Chunk Arguments>, but the lstlistings style
3976   parameters used in the <verbatim|\\Chunk> command<\footnote>
3977     The <verbatim|params> parameter is used to hold the parameters for
3978     parameterized chunks
3979   </footnote>.
3981   <\nf-chunk|chunk-storage-functions>
3982     <item>function new_chunk(chunk_name, opts, args,
3984     <item> \ # local vars
3986     <item> \ p, append )
3988     <item>{
3990     <item> \ # HACK WHILE WE CHANGE TO ( ) for PARAM CHUNKS
3992     <item> \ gsub("\\\\(\\\\)$", "", chunk_name);
3994     <item> \ if (! (chunk_name in chunk_names)) {
3996     <item> \ \ \ if (debug) print "New chunk " chunk_name;
3998     <item> \ \ \ chunk_names[chunk_name];
4000     <item> \ \ \ for (p in opts) {
4002     <item> \ \ \ \ \ chunks[chunk_name, p] = opts[p];
4004     <item> \ \ \ \ \ if (debug) print "chunks[" chunk_name "," p "] = "
4005     opts[p];
4007     <item> \ \ \ }
4009     <item> \ \ \ for (p in args) {
4011     <item> \ \ \ \ \ chunks[chunk_name, "params", p] = args[p];
4013     <item> \ \ \ }
4015     <item> \ \ \ if ("append" in opts) {
4017     <item> \ \ \ \ \ append=opts["append"];
4019     <item> \ \ \ \ \ if (! (append in chunk_names)) {
4021     <item> \ \ \ \ \ \ \ warning("Chunk " chunk_name " is appended to chunk "
4022     append " which is not defined yet");
4024     <item> \ \ \ \ \ \ \ new_chunk(append);
4026     <item> \ \ \ \ \ }
4028     <item> \ \ \ \ \ chunk_include(append, chunk_name);
4030     <item> \ \ \ \ \ chunk_line(append, ORS);
4032     <item> \ \ \ }
4034     <item> \ }
4036     <item> \ active_chunk = chunk_name;
4038     <item> \ prime_chunk(chunk_name);
4040     <item>}
4041   </nf-chunk||>
4043   <\nf-chunk|chunk-storage-functions>
4044     <item>
4046     <item>function prime_chunk(chunk_name)
4048     <item>{
4050     <item> \ chunks[chunk_name, "part", ++chunks[chunk_name, "part"] ] = \\
4052     <item> \ \ \ \ \ \ \ \ chunk_name SUBSEP "chunklet" SUBSEP ""
4053     ++chunks[chunk_name, "chunklet"];
4055     <item> \ chunks[chunk_name, "part", chunks[chunk_name, "part"],
4056     "FILENAME"] = FILENAME;
4058     <item> \ chunks[chunk_name, "part", chunks[chunk_name, "part"], "LINENO"]
4059     = FNR + 1;
4061     <item>}
4063     <item>
4065     <item>function chunk_line(chunk_name, line){
4067     <item> \ chunks[chunk_name, "chunklet", chunks[chunk_name, "chunklet"],
4069     <item> \ \ \ \ \ \ \ \ ++chunks[chunk_name, "chunklet",
4070     chunks[chunk_name, "chunklet"], "line"] \ ] = line;
4072     <item>}
4074     <item>
4075   </nf-chunk||>
4077   Chunk include represents a <em|chunkref> statement, and stores the
4078   requirement to include another chunk. The parameter indent represents the
4079   quanity of literal text characters that preceded this <em|chunkref>
4080   statement and therefore by how much additional lines of the included chunk
4081   should be indented.
4083   <\nf-chunk|chunk-storage-functions>
4084     <item>function chunk_include(chunk_name, chunk_ref, indent, tail)
4086     <item>{
4088     <item> \ chunks[chunk_name, "part", ++chunks[chunk_name, "part"] ] =
4089     chunk_ref;
4091     <item> \ chunks[chunk_name, "part", chunks[chunk_name, "part"], "type" ]
4092     = part_type_chunk;
4094     <item> \ chunks[chunk_name, "part", chunks[chunk_name, "part"], "indent"
4095     ] = indent_string(indent);
4097     <item> \ chunks[chunk_name, "part", chunks[chunk_name, "part"], "tail" ]
4098     = tail;
4100     <item> \ prime_chunk(chunk_name);
4102     <item>}
4104     <item>
4105   </nf-chunk||>
4107   The indent is calculated by indent_string, which may in future convert some
4108   spaces into tab characters. This function works by generating a printf
4109   padded format string, like <verbatim|%22s> for an indent of 22, and then
4110   printing an empty string using that format.
4112   <\nf-chunk|chunk-storage-functions>
4113     <item>function indent_string(indent) {
4115     <item> \ return sprintf("%" indent "s", "");
4117     <item>}
4118   </nf-chunk||>
4120   <chapter|getopt><label|cha:getopt>
4122   I use Arnold Robbins public domain getopt (1993 revision). This is probably
4123   the same one that is covered in chapter 12 of “Edition 3 of GAWK:
4124   Effective AWK Programming: A User's Guide for GNU Awk” but as that is
4125   licensed under the GNU Free Documentation License, Version 1.3, which
4126   conflicts with the GPL3, I can't use it from there (or it's accompanying
4127   explanations), so I do my best to explain how it works here.
4129   The getopt.awk header is:
4131   <\nf-chunk|getopt.awk-header>
4132     <item># getopt.awk --- do C library getopt(3) function in awk
4134     <item>#
4136     <item># Arnold Robbins, arnold@skeeve.com, Public Domain
4138     <item>#
4140     <item># Initial version: March, 1991
4142     <item># Revised: May, 1993
4144     <item>
4145   </nf-chunk||>
4147   The provided explanation is:
4149   <\nf-chunk|getopt.awk-notes>
4150     <item># External variables:
4152     <item># \ \ \ Optind -- index in ARGV of first nonoption argument
4154     <item># \ \ \ Optarg -- string value of argument to current option
4156     <item># \ \ \ Opterr -- if nonzero, print our own diagnostic
4158     <item># \ \ \ Optopt -- current option letter
4160     <item>
4162     <item># Returns:
4164     <item># \ \ \ -1 \ \ \ \ at end of options
4166     <item># \ \ \ ? \ \ \ \ \ for unrecognized option
4168     <item># \ \ \ \<less\>c\<gtr\> \ \ \ a character representing the current
4169     option
4171     <item>
4173     <item># Private Data:
4175     <item># \ \ \ _opti \ -- index in multi-flag option, e.g., -abc
4177     <item>
4178   </nf-chunk||>
4180   The function follows. The final two parameters, <verbatim|thisopt> and
4181   <verbatim|i> are local variables and not parameters --- as indicated by the
4182   multiple spaces preceding them. Awk doesn't care, the multiple spaces are a
4183   convention to help us humans.
4185   <\nf-chunk|getopt.awk-getopt()>
4186     <item>function getopt(argc, argv, options, \ \ \ thisopt, i)
4188     <item>{
4190     <item> \ \ \ if (length(options) == 0) \ \ \ # no options given
4192     <item> \ \ \ \ \ \ \ return -1
4194     <item> \ \ \ if (argv[Optind] == "--") { \ # all done
4196     <item> \ \ \ \ \ \ \ Optind++
4198     <item> \ \ \ \ \ \ \ _opti = 0
4200     <item> \ \ \ \ \ \ \ return -1
4202     <item> \ \ \ } else if (argv[Optind] !~ /^-[^: \\t\\n\\f\\r\\v\\b]/) {
4204     <item> \ \ \ \ \ \ \ _opti = 0
4206     <item> \ \ \ \ \ \ \ return -1
4208     <item> \ \ \ }
4210     <item> \ \ \ if (_opti == 0)
4212     <item> \ \ \ \ \ \ \ _opti = 2
4214     <item> \ \ \ thisopt = substr(argv[Optind], _opti, 1)
4216     <item> \ \ \ Optopt = thisopt
4218     <item> \ \ \ i = index(options, thisopt)
4220     <item> \ \ \ if (i == 0) {
4222     <item> \ \ \ \ \ \ \ if (Opterr)
4224     <item> \ \ \ \ \ \ \ \ \ \ \ printf("%c -- invalid option\\n",
4226     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ thisopt)
4227     \<gtr\> "/dev/stderr"
4229     <item> \ \ \ \ \ \ \ if (_opti \<gtr\>= length(argv[Optind])) {
4231     <item> \ \ \ \ \ \ \ \ \ \ \ Optind++
4233     <item> \ \ \ \ \ \ \ \ \ \ \ _opti = 0
4235     <item> \ \ \ \ \ \ \ } else
4237     <item> \ \ \ \ \ \ \ \ \ \ \ _opti++
4239     <item> \ \ \ \ \ \ \ return "?"
4241     <item> \ \ \ }
4242   </nf-chunk||>
4244   At this point, the option has been found and we need to know if it takes
4245   any arguments.
4247   <\nf-chunk|getopt.awk-getopt()>
4248     <item> \ \ \ if (substr(options, i + 1, 1) == ":") {
4250     <item> \ \ \ \ \ \ \ # get option argument
4252     <item> \ \ \ \ \ \ \ if (length(substr(argv[Optind], _opti + 1)) \<gtr\>
4253     0)
4255     <item> \ \ \ \ \ \ \ \ \ \ \ Optarg = substr(argv[Optind], _opti + 1)
4257     <item> \ \ \ \ \ \ \ else
4259     <item> \ \ \ \ \ \ \ \ \ \ \ Optarg = argv[++Optind]
4261     <item> \ \ \ \ \ \ \ _opti = 0
4263     <item> \ \ \ } else
4265     <item> \ \ \ \ \ \ \ Optarg = ""
4267     <item> \ \ \ if (_opti == 0 \|\| _opti \<gtr\>= length(argv[Optind])) {
4269     <item> \ \ \ \ \ \ \ Optind++
4271     <item> \ \ \ \ \ \ \ _opti = 0
4273     <item> \ \ \ } else
4275     <item> \ \ \ \ \ \ \ _opti++
4277     <item> \ \ \ return thisopt
4279     <item>}
4280   </nf-chunk||>
4282   A test program is built in, too
4284   <\nf-chunk|getopt.awk-begin>
4285     <item>BEGIN {
4287     <item> \ \ \ Opterr = 1 \ \ \ # default is to diagnose
4289     <item> \ \ \ Optind = 1 \ \ \ # skip ARGV[0]
4291     <item> \ \ \ # test program
4293     <item> \ \ \ if (_getopt_test) {
4295     <item> \ \ \ \ \ \ \ while ((_go_c = getopt(ARGC, ARGV, "ab:cd")) != -1)
4297     <item> \ \ \ \ \ \ \ \ \ \ \ printf("c = \<less\>%c\<gtr\>, optarg =
4298     \<less\>%s\<gtr\>\\n",
4300     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ _go_c,
4301     Optarg)
4303     <item> \ \ \ \ \ \ \ printf("non-option arguments:\\n")
4305     <item> \ \ \ \ \ \ \ for (; Optind \<less\> ARGC; Optind++)
4307     <item> \ \ \ \ \ \ \ \ \ \ \ printf("\\tARGV[%d] = \<less\>%s\<gtr\>\\n",
4309     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Optind,
4310     ARGV[Optind])
4312     <item> \ \ \ }
4314     <item>}
4315   </nf-chunk||>
4317   The entire getopt.awk is made out of these chunks in order
4319   <\nf-chunk|getopt.awk>
4320     <item>=\<less\>\\chunkref{getopt.awk-header}\<gtr\>
4322     <item>
4324     <item>=\<less\>\\chunkref{getopt.awk-notes}\<gtr\>
4326     <item>=\<less\>\\chunkref{getopt.awk-getopt()}\<gtr\>
4328     <item>=\<less\>\\chunkref{getopt.awk-begin}\<gtr\>
4329   </nf-chunk||>
4331   Although we only want the header and function:
4333   <\nf-chunk|getopt>
4334     <item># try: locate getopt.awk for the full original file
4336     <item># as part of your standard awk installation
4338     <item>=\<less\>\\chunkref{getopt.awk-header}\<gtr\>
4340     <item>
4342     <item>=\<less\>\\chunkref{getopt.awk-getopt()}\<gtr\>
4343   </nf-chunk||>
4345   <chapter|Fangle LaTeX source code><label|latex-source>
4347   <section|fangle module>
4349   Here we define a <LyX> <verbatim|.module> file that makes it convenient to
4350   use <LyX> for writing such literate programs.
4352   This file <verbatim|./fangle.module> can be installed in your personal
4353   <verbatim|.lyx/layouts> folder. You will need to Tools Reconfigure so that
4354   <LyX> notices it. It adds a new format Chunk, which should precede every
4355   listing and contain the chunk name.
4357   <\nf-chunk|./fangle.module>
4358     <item>#\\DeclareLyXModule{Fangle Literate Listings}
4360     <item>#DescriptionBegin
4362     <item># \ Fangle literate listings allow one to write
4364     <item># \ \ literate programs after the fashion of noweb, but without
4365     having
4367     <item># \ \ to use noweave to generate the documentation. Instead the
4368     listings
4370     <item># \ \ package is extended in conjunction with the noweb package to
4371     implement
4373     <item># \ \ to code formating directly as latex.
4375     <item># \ The fangle awk script
4377     <item>#DescriptionEnd
4379     <item>
4381     <item>=\<less\>\\chunkref{gpl3-copyright.hashed}\<gtr\>
4383     <item>
4385     <item>Format 11
4387     <item>
4389     <item>AddToPreamble
4391     <item>=\<less\>\\chunkref{./fangle.sty}\<gtr\>
4393     <item>EndPreamble
4395     <item>
4397     <item>=\<less\>\\chunkref{chunkstyle}\<gtr\>
4399     <item>
4401     <item>=\<less\>\\chunkref{chunkref}\<gtr\>
4402   </nf-chunk|lyx-module|>
4404   Because <LyX> modules are not yet a language supported by fangle or
4405   lstlistings, we resort to this fake awk chunk below in order to have each
4406   line of the GPL3 license commence with a #
4408   <\nf-chunk|gpl3-copyright.hashed>
4409     <item>#=\<less\>\\chunkref{gpl3-copyright}\<gtr\>
4411     <item>
4412   </nf-chunk|awk|>
4414   <subsection|The Chunk style>
4416   The purpose of the <name|chunk> style is to make it easier for <LyX> users
4417   to provide the name to <verbatim|lstlistings>. Normally this requires
4418   right-clicking on the listing, choosing settings, advanced, and then typing
4419   <verbatim|name=chunk-name>. This has the further disadvantage that the name
4420   (and other options) are not generally visible during document editing.
4422   The chunk style is defined as a <LaTeX> command, so that all text on the
4423   same line is passed to the <verbatim|LaTeX> command <verbatim|Chunk>. This
4424   makes it easy to parse using <verbatim|fangle>, and easy to pass these
4425   options on to the listings package. The first word in a chunk section
4426   should be the chunk name, and will have <verbatim|name=> prepended to it.
4427   Any other words are accepted arguments to <verbatim|lstset>.
4429   We set PassThru to 1 because the user is actually entering raw latex.
4431   <\nf-chunk|chunkstyle>
4432     <item>Style Chunk
4434     <item> \ LatexType \ \ \ \ \ \ \ \ \ \ \ \ Command
4436     <item> \ LatexName \ \ \ \ \ \ \ \ \ \ \ \ Chunk
4438     <item> \ Margin \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ First_Dynamic
4440     <item> \ LeftMargin \ \ \ \ \ \ \ \ \ \ \ Chunk:xxx
4442     <item> \ LabelSep \ \ \ \ \ \ \ \ \ \ \ \ \ xx
4444     <item> \ LabelType \ \ \ \ \ \ \ \ \ \ \ \ Static
4446     <item> \ LabelString \ \ \ \ \ \ \ \ \ \ "Chunk:"
4448     <item> \ Align \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Left
4450     <item> \ PassThru \ \ \ \ \ \ \ \ \ \ \ \ \ 1
4452     <item>
4453   </nf-chunk||>
4455   To make the label very visible we choose a larger font coloured red.
4457   <\nf-chunk|chunkstyle>
4458     <item> \ LabelFont
4460     <item> \ \ \ Family \ \ \ \ \ \ \ \ \ \ \ \ \ Sans
4462     <item> \ \ \ Size \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Large
4464     <item> \ \ \ Series \ \ \ \ \ \ \ \ \ \ \ \ \ Bold
4466     <item> \ \ \ Shape \ \ \ \ \ \ \ \ \ \ \ \ \ \ Italic
4468     <item> \ \ \ Color \ \ \ \ \ \ \ \ \ \ \ \ \ \ red
4470     <item> \ EndFont
4472     <item>End
4473   </nf-chunk||>
4475   <subsection|The chunkref style>
4477   We also define the Chunkref style which can be used to express cross
4478   references to chunks.
4480   <\nf-chunk|chunkref>
4481     <item>InsetLayout Chunkref
4483     <item> \ LyxType \ \ \ \ \ \ \ \ \ \ \ \ \ \ charstyle
4485     <item> \ LatexType \ \ \ \ \ \ \ \ \ \ \ \ Command
4487     <item> \ LatexName \ \ \ \ \ \ \ \ \ \ \ \ chunkref
4489     <item> \ PassThru \ \ \ \ \ \ \ \ \ \ \ \ \ 1
4491     <item> \ LabelFont \ \ \ \ \ \ \ \ \ \ \ \ 
4493     <item> \ \ \ Shape \ \ \ \ \ \ \ \ \ \ \ \ \ \ Italic
4495     <item> \ \ \ Color \ \ \ \ \ \ \ \ \ \ \ \ \ \ red
4497     <item> \ EndFont
4499     <item>End
4500   </nf-chunk||>
4502   <section|Latex Macros><label|sec:Latex-Macros>
4504   We require the listings, noweb and xargs packages. As noweb defines it's
4505   own <verbatim|\\code> environment, we re-define the one that <LyX> logical
4506   markup module expects here.
4508   <\nf-chunk|./fangle.sty>
4509     <item>\\usepackage{listings}%
4511     <item>\\usepackage{noweb}%
4513     <item>\\usepackage{xargs}%
4515     <item>\\renewcommand{\\code}[1]{\\texttt{#1}}%
4516   </nf-chunk|tex|>
4518   We also define a <verbatim|CChunk> macro, for use as:
4519   <verbatim|\\begin{CChunk}> which will need renaming to
4520   <verbatim|\\begin{Chunk}> when I can do this without clashing with
4521   <verbatim|\\Chunk>.
4523   <\nf-chunk|./fangle.sty>
4524     <item>\\lstnewenvironment{Chunk}{\\relax}{\\relax}%
4525   </nf-chunk||>
4527   We also define a suitable <verbatim|\\lstset> of parameters that suit the
4528   literate programming style after the fashion of <name|noweave>.
4530   <\nf-chunk|./fangle.sty>
4531     <item>\\lstset{numbers=left, stepnumber=5, numbersep=5pt,
4533     <item> \ \ \ \ \ \ \ breaklines=false,basicstyle=\\ttfamily,
4535     <item> \ \ \ \ \ \ \ numberstyle=\\tiny, language=C}%
4536   </nf-chunk||>
4538   We also define a notangle-like mechanism for escaping to <LaTeX> from the
4539   listing, and by which we can refer to other listings. We declare the
4540   <verbatim|=\<less\>...\<gtr\>> sequence to contain <LaTeX> code, and
4541   include another like this chunk: <verbatim|=\<less\>\\chunkref{chunkname}\<gtr\>>.
4542   However, because <verbatim|=\<less\>...\<gtr\>> is already defined to
4543   contain <LaTeX> code for this document --- this is a fangle document after
4544   all --- the code fragment below effectively contains the <LaTeX> code:
4545   <verbatim|}{>. To avoid problems with document generation, I had to declare
4546   an lstlistings property: <verbatim|escapeinside={}> for this listing only;
4547   which in <LyX> was done by right-clicking the listings inset, choosing
4548   settings-\<gtr\>advanced. Therefore <verbatim|=\<less\>> isn't interpreted
4549   literally here, in a listing when the escape sequence is already defined as
4550   shown... we need to somehow escape this representation...
4552   <\nf-chunk|./fangle.sty>
4553     <item>\\lstset{escapeinside={=\<less\>}{\<gtr\>}}%
4554   </nf-chunk||>
4556   Although our macros will contain the <verbatim|@> symbol, they will be
4557   included in a <verbatim|\\makeatletter> section by <LyX>; however we keep
4558   the commented out <verbatim|\\makeatletter> as a reminder. The listings
4559   package likes to centre the titles, but noweb titles are specially
4560   formatted and must be left aligned. The simplest way to do this turned out
4561   to be by removing the definition of <verbatim|\\lst@maketitle>. This may
4562   interact badly if other listings want a regular title or caption. We
4563   remember the old maketitle in case we need it.
4565   <\nf-chunk|./fangle.sty>
4566     <item>%\\makeatletter
4568     <item>%somehow re-defining maketitle gives us a left-aligned title
4570     <item>%which is extactly what our specially formatted title needs!
4572     <item>\\global\\let\\fangle@lst@maketitle\\lst@maketitle%
4574     <item>\\global\\def\\lst@maketitle{}%
4575   </nf-chunk||>
4577   <subsection|The chunk command><label|sub:The-chunk-command>
4579   Our chunk command accepts one argument, and calls <verbatim|\\ltset>.
4580   Although <verbatim|\\ltset> will note the name, this is erased when the
4581   next <verbatim|\\lstlisting> starts, so we make a note of this in
4582   <verbatim|\\lst@chunkname> and restore in in lstlistings Init hook.
4584   <\nf-chunk|./fangle.sty>
4585     <item>\\def\\Chunk#1{%
4587     <item> \ \\lstset{title={\\fanglecaption},name=#1}%
4589     <item> \ \\global\\edef\\lst@chunkname{\\lst@intname}%
4591     <item>}%
4593     <item>\\def\\lst@chunkname{\\empty}%
4594   </nf-chunk||>
4596   <subsubsection|Chunk parameters>
4598   Fangle permits parameterized chunks, and requires the paramters to be
4599   specified as listings options. The fangle script uses this, and although we
4600   don't do anything with these in the <LaTeX> code right now, we need to stop
4601   the listings package complaining.
4603   <\nf-chunk|./fangle.sty>
4604     <item>\\lst@Key{params}\\relax{\\def\\fangle@chunk@params{#1}}%
4605   </nf-chunk||>
4607   As it is common to define a chunk which then needs appending to another
4608   chunk, and annoying to have to declare a single line chunk to manage the
4609   include, we support an append= option.
4611   <\nf-chunk|./fangle.sty>
4612     <item>\\lst@Key{append}\\relax{\\def\\fangle@chunk@append{#1}}%
4613   </nf-chunk||>
4615   <subsection|The noweb styled caption>
4617   We define a public macro <verbatim|\\fanglecaption> which can be set as a
4618   regular title. By means of <verbatim|\\protect>, It expands to
4619   <verbatim|\\fangle@caption> at the appopriate time when the caption is
4620   emitted.
4622   <nf-chunk|./fangle.sty|\\def\\fanglecaption{\\protect\\fangle@caption}%||>
4624   <\big-figure>
4625     22c <math|\<langle\>>some-chunk 19b<math|\<rangle\>><math|\<equiv\>>+
4626     \ \ <math|\<vartriangleleft\>>22b 24d<math|\<vartriangleright\>>
4628     \;
4630     In this example, the current chunk is 22c, and therefore the third chunk
4631     on page 22.
4633     It's name is some-chunk.\ 
4635     The first chunk with this name (19b) occurs as the second chunk on page
4636     19.
4638     The previous chunk (22d) with the same name is the second chunk on page
4639     22.
4641     The next chunk (24d) is the fourth chunk on page 24.
4642   </big-figure|Noweb Heading<label|noweb heading>>
4644   The general noweb output format compactly identifies the current chunk, and
4645   references to the first chunk, and the previous and next chunks that have
4646   the same name.
4648   This means that we need to keep a counter for each chunk-name, that we use
4649   to count chunks of the same name.
4651   <subsection|The chunk counter>
4653   It would be natural to have a counter for each chunk name, but TeX would
4654   soon run out of counters<\footnote>
4655     ...soon did run out of counters and so I had to re-write the LaTeX macros
4656     to share a counter as described here.
4657   </footnote>, so we have one counter which we save at the end of a chunk and
4658   restore at the beginning of a chunk.
4660   <\nf-chunk|./fangle.sty>
4661     <item>\\newcounter{fangle@chunkcounter}%
4662   </nf-chunk||>
4664   We construct the name of this variable to store the counter to be the text
4665   <verbatim|lst-chunk-> prefixed onto the chunks own name, and store it in
4666   <verbatim|\\chunkcount>.\ 
4668   We save the counter like this:
4670   <nf-chunk|save-counter|\\global\\expandafter\\edef\\csname
4671   \\chunkcount\\endcsname{\\arabic{fangle@chunkcounter}}%||>
4673   and restore the counter like this:
4675   <nf-chunk|restore-counter|\\setcounter{fangle@chunkcounter}{\\csname
4676   \\chunkcount\\endcsname}%||>
4678   If there does not already exist a variable whose name is stored in
4679   <verbatim|\\chunkcount>, then we know we are the first chunk with this
4680   name, and then define a counter.\ 
4682   Although chunks of the same name share a common counter, they must still be
4683   distinguished. We use is the internal name of the listing, suffixed by the
4684   counter value. So the first chunk might be <verbatim|something-1> and the
4685   second chunk be <verbatim|something-2>, etc.
4687   We also calculate the name of the previous chunk if we can (before we
4688   increment the chunk counter). If this is the first chunk of that name, then
4689   <verbatim|\\prevchunkname> is set to <verbatim|\\relax> which the noweb
4690   package will interpret as not existing.
4692   <\nf-chunk|./fangle.sty>
4693     <item>\\def\\fangle@caption{%
4695     <item> \ \\edef\\chunkcount{lst-chunk-\\lst@intname}%
4697     <item> \ \\@ifundefined{\\chunkcount}{%
4699     <item> \ \ \ \\expandafter\\gdef\\csname \\chunkcount\\endcsname{0}%
4701     <item> \ \ \ \\setcounter{fangle@chunkcounter}{\\csname
4702     \\chunkcount\\endcsname}%
4704     <item> \ \ \ \\let\\prevchunkname\\relax%
4706     <item> \ }{%
4708     <item> \ \ \ \\setcounter{fangle@chunkcounter}{\\csname
4709     \\chunkcount\\endcsname}%
4711     <item> \ \ \ \\edef\\prevchunkname{\\lst@intname-\\arabic{fangle@chunkcounter}}%
4713     <item> \ }%
4714   </nf-chunk||>
4716   After incrementing the chunk counter, we then define the name of this
4717   chunk, as well as the name of the first chunk.
4719   <\nf-chunk|./fangle.sty>
4720     <item> \ \\addtocounter{fangle@chunkcounter}{1}%
4722     <item> \ \\global\\expandafter\\edef\\csname
4723     \\chunkcount\\endcsname{\\arabic{fangle@chunkcounter}}%
4725     <item> \ \\edef\\chunkname{\\lst@intname-\\arabic{fangle@chunkcounter}}%
4727     <item> \ \\edef\\firstchunkname{\\lst@intname-1}%
4728   </nf-chunk||>
4730   We now need to calculate the name of the next chunk. We do this by
4731   temporarily skipping the counter on by one; however there may not actually
4732   be another chunk with this name! We detect this by also defining a label
4733   for each chunk based on the chunkname. If there is a next chunkname then it
4734   will define a label with that name. As labels are persistent, we can at
4735   least tell the second time <LaTeX> is run. If we don't find such a defined
4736   label then we define <verbatim|\\nextchunkname> to <verbatim|\\relax>.
4738   <\nf-chunk|./fangle.sty>
4739     <item> \ \\addtocounter{fangle@chunkcounter}{1}%
4741     <item> \ \\edef\\nextchunkname{\\lst@intname-\\arabic{fangle@chunkcounter}}%
4743     <item> \ \\@ifundefined{r@label-\\nextchunkname}{\\let\\nextchunkname\\relax}{}%
4744   </nf-chunk||>
4746   The noweb package requires that we define a <verbatim|\\sublabel> for every
4747   chunk, with a unique name, which is then used to print out it's navigation
4748   hints.
4750   We also define a regular label for this chunk, as was mentioned above when
4751   we calculated <verbatim|\\nextchunkname>. This requires <LaTeX> to be run
4752   at least twice after new chunk sections are added --- but noweb requried
4753   that anyway.
4755   <\nf-chunk|./fangle.sty>
4756     <item> \ \\sublabel{\\chunkname}%
4758     <item>% define this label for every chunk instance, so we
4760     <item>% can tell when we are the last chunk of this name
4762     <item> \ \\label{label-\\chunkname}%
4763   </nf-chunk||>
4765   We also try and add the chunk to the list of listings, but I'm afraid we
4766   don't do very well. We want each chunk name listing once, with all of it's
4767   references.
4769   <\nf-chunk|./fangle.sty>
4770     <item> \ \\addcontentsline{lol}{lstlisting}{\\lst@name~[\\protect\\subpageref{\\chunkname}]}%
4771   </nf-chunk||>
4773   We then call the noweb output macros in the same way that noweave generates
4774   them, except that we don't need to call <verbatim|\\nwstartdeflinemarkup>
4775   or <verbatim|\\nwenddeflinemarkup> <emdash> and if we do, it messes up the
4776   output somewhat.
4778   <\nf-chunk|./fangle.sty>
4779     <item> \ \\nwmargintag{%
4781     <item> \ \ \ {%
4783     <item> \ \ \ \ \ \\nwtagstyle{}%
4785     <item> \ \ \ \ \ \\subpageref{\\chunkname}%
4787     <item> \ \ \ }%
4789     <item> \ }%
4791     <item>%
4793     <item> \ \\moddef{%
4795     <item> \ \ \ {\\lst@name}%
4797     <item> \ \ \ {%
4799     <item> \ \ \ \ \ \\nwtagstyle{}\\/%
4801     <item> \ \ \ \ \ \\@ifundefined{fangle@chunk@params}{}{%
4803     <item> \ \ \ \ \ \ \ (\\fangle@chunk@params)%
4805     <item> \ \ \ \ \ }%
4807     <item> \ \ \ \ \ [\\csname \\chunkcount\\endcsname]~%
4809     <item> \ \ \ \ \ \\subpageref{\\firstchunkname}%
4811     <item> \ \ \ }%
4813     <item> \ \ \ \\@ifundefined{fangle@chunk@append}{}{%
4815     <item> \ \ \ \\ifx{}\\fangle@chunk@append{x}\\else%
4817     <item> \ \ \ \ \ \ \ ,~add~to~\\fangle@chunk@append%
4819     <item> \ \ \ \\fi%
4821     <item> \ \ \ }%
4823     <item>\\global\\def\\fangle@chunk@append{}%
4825     <item>\\lstset{append=x}%
4827     <item> \ }%
4829     <item>%
4831     <item> \ \\ifx\\relax\\prevchunkname\\endmoddef\\else\\plusendmoddef\\fi%
4833     <item>% \ \\nwstartdeflinemarkup%
4835     <item> \ \\nwprevnextdefs{\\prevchunkname}{\\nextchunkname}%
4837     <item>% \ \\nwenddeflinemarkup%
4839     <item>}%
4840   </nf-chunk||>
4842   Originally this was developed as a <verbatim|listings> aspect, in the Init
4843   hook, but it was found easier to affect the title without using a hook
4844   <emdash> <verbatim|\\lst@AddToHookExe{PreSet}> is still required to set the
4845   listings name to the name passed to the <verbatim|\\Chunk> command, though.
4847   <\nf-chunk|./fangle.sty>
4848     <item>%\\lst@BeginAspect{fangle}
4850     <item>%\\lst@Key{fangle}{true}[t]{\\lstKV@SetIf{#1}{true}}
4852     <item>\\lst@AddToHookExe{PreSet}{\\global\\let\\lst@intname\\lst@chunkname}
4854     <item>\\lst@AddToHook{Init}{}%\\fangle@caption}
4856     <item>%\\lst@EndAspect
4857   </nf-chunk||>
4859   <subsection|Cross references>
4861   We define the <verbatim|\\chunkref> command which makes it easy to generate
4862   visual references to different code chunks, e.g.
4864   <block|<tformat|<table|<row|<cell|Macro>|<cell|Appearance>>|<row|<cell|<verbatim|\\chunkref{preamble}>>|<cell|>>|<row|<cell|<verbatim|\\chunkref[3]{preamble}>>|<cell|>>|<row|<cell|<verbatim|\\chunkref{preamble}[arg1,
4865   arg2]>>|<cell|>>>>>
4867   Chunkref can also be used within a code chunk to include another code
4868   chunk. The third optional parameter to chunkref is a comma sepatarated list
4869   of arguments, which will replace defined parameters in the chunkref.
4871   <\note>
4872     Darn it, if I have: <verbatim|=\<less\>\\chunkref{new-mode-tracker}[{chunks[chunk_name,
4873     "language"]},{mode}]\<gtr\>> the inner braces (inside [ ]) cause _ to
4874     signify subscript even though we have <verbatim|lst@ReplaceIn>
4875   </note>
4877   <\nf-chunk|./fangle.sty>
4878     <item>\\def\\chunkref@args#1,{%
4880     <item> \ \\def\\arg{#1}%
4882     <item> \ \\lst@ReplaceIn\\arg\\lst@filenamerpl%
4884     <item> \ \\arg%
4886     <item> \ \\@ifnextchar){\\relax}{, \\chunkref@args}%
4888     <item>}%
4890     <item>\\newcommand\\chunkref[2][0]{%
4892     <item> \ \\@ifnextchar({\\chunkref@i{#1}{#2}}{\\chunkref@i{#1}{#2}()}%
4894     <item>}%
4896     <item>\\def\\chunkref@i#1#2(#3){%
4898     <item> \ \\def\\zero{0}%
4900     <item> \ \\def\\chunk{#2}%
4902     <item> \ \\def\\chunkno{#1}%
4904     <item> \ \\def\\chunkargs{#3}%
4906     <item> \ \\ifx\\chunkno\\zero%
4908     <item> \ \ \ \\def\\chunkname{#2-1}%
4910     <item> \ \\else%
4912     <item> \ \ \ \\def\\chunkname{#2-\\chunkno}%
4914     <item> \ \\fi%
4916     <item> \ \\let\\lst@arg\\chunk%
4918     <item> \ \\lst@ReplaceIn\\chunk\\lst@filenamerpl%
4920     <item> \ \\LA{%\\moddef{%
4922     <item> \ \ \ {\\chunk}%
4924     <item> \ \ \ {%
4926     <item> \ \ \ \ \ \\nwtagstyle{}\\/%
4928     <item> \ \ \ \ \ \\ifx\\chunkno\\zero%
4930     <item> \ \ \ \ \ \\else%
4932     <item> \ \ \ \ \ [\\chunkno]%
4934     <item> \ \ \ \ \ \\fi%
4936     <item> \ \ \ \ \ \\ifx\\chunkargs\\empty%
4938     <item> \ \ \ \ \ \\else%
4940     <item> \ \ \ \ \ \ \ (\\chunkref@args #3,)%
4942     <item> \ \ \ \ \ \\fi%
4944     <item> \ \ \ \ \ ~\\subpageref{\\chunkname}%
4946     <item> \ \ \ }%
4948     <item> \ }%
4950     <item> \ \\RA%\\endmoddef%
4952     <item>}%
4953   </nf-chunk||>
4955   <subsection|The end>
4957   <\nf-chunk|./fangle.sty>
4958     <item>%
4960     <item>%\\makeatother
4961   </nf-chunk||>
4963   <chapter|Extracting fangle>
4965   <section|Extracting from Lyx>
4967   To extract from <LyX>, you will need to configure <LyX> as explained in
4968   section <reference|Configuring-the-build>.
4970   <label|lyx-build-script>And this lyx-build scrap will extract fangle for
4971   me.
4973   <\nf-chunk|lyx-build>
4974     <item>#! /bin/sh
4976     <item>set -x
4978     <item>
4980     <item>=\<less\>\\chunkref{lyx-build-helper}\<gtr\>
4982     <item>cd $PROJECT_DIR \|\| exit 1
4984     <item>
4986     <item>/usr/local/bin/fangle -R./fangle $TEX_SRC \<gtr\> ./fangle
4988     <item>/usr/local/bin/fangle -R./fangle.module $TEX_SRC \<gtr\>
4989     ./fangle.module
4991     <item>
4993     <item>=\<less\>\\chunkref{test:helpers}\<gtr\>
4995     <item>export FANGLE=./fangle
4997     <item>export TMP=${TMP:-/tmp}
4999     <item>=\<less\>\\chunkref{test:run-tests}\<gtr\>
5001     <item># Now check that we can extract a fangle that also passes the
5002     tests!
5004     <item>$FANGLE -R./fangle $TEX_SRC \<gtr\> ./new-fangle
5006     <item>export FANGLE=./new-fangle
5008     <item>=\<less\>\\chunkref{test:run-tests}\<gtr\>
5009   </nf-chunk|sh|>
5011   <\nf-chunk|test:run-tests>
5012     <item># run tests
5014     <item>$FANGLE -Rpca-test.awk $TEX_SRC \| awk -f - \|\| exit 1
5016     <item>=\<less\>\\chunkref{test:cromulence}\<gtr\>
5018     <item>=\<less\>\\chunkref{test:escapes}\<gtr\>
5020     <item>=\<less\>\\chunkref{test:chunk-params}\<gtr\>
5021   </nf-chunk|sh|>
5023   With a lyx-build-helper
5025   <\nf-chunk|lyx-build-helper>
5026     <item>PROJECT_DIR="$LYX_r"
5028     <item>LYX_SRC="$PROJECT_DIR/${LYX_i%.tex}.lyx"
5030     <item>TEX_DIR="$LYX_p"
5032     <item>TEX_SRC="$TEX_DIR/$LYX_i"
5033   </nf-chunk|sh|>
5035   <section|Extracting documentation>
5037   <\nf-chunk|./gen-www>
5038     <item>#python -m elyxer --css lyx.css $LYX_SRC \| \\
5040     <item># \ iconv -c -f utf-8 -t ISO-8859-1//TRANSLIT \| \\
5042     <item># \ sed 's/UTF-8"\\(.\\)\<gtr\>/ISO-8859-1"\\1\<gtr\>/' \<gtr\>
5043     www/docs/fangle.html
5045     <item>
5047     <item>python -m elyxer --css lyx.css --iso885915 --html --destdirectory
5048     www/docs/fangle.e \\
5050     <item> \ \ \ \ \ \ fangle.lyx \<gtr\> www/docs/fangle.e/fangle.html
5052     <item>
5054     <item>( mkdir -p www/docs/fangle && cd www/docs/fangle && \\
5056     <item> \ lyx -e latex ../../../fangle.lyx && \\
5058     <item> \ htlatex ../../../fangle.tex "xhtml,fn-in" && \\
5060     <item> \ sed -i -e 's/\<less\>!--l\\. [0-9][0-9]* *--\<gtr\>//g'
5061     fangle.html
5063     <item>)
5065     <item>
5067     <item>( mkdir -p www/docs/literate && cd www/docs/literate && \\
5069     <item> \ lyx -e latex ../../../literate.lyx && \\
5071     <item> \ htlatex ../../../literate.tex "xhtml,fn-in" && \\
5073     <item> \ sed -i -e 's/\<less\>!--l\\. [0-9][0-9]* *--\<gtr\>$//g'
5074     literate.html
5076     <item>)
5077   </nf-chunk||>
5079   <section|Extracting from the command line>
5081   First you will need the tex output, then you can extract:
5083   <\nf-chunk|lyx-build-manual>
5084     <item>lyx -e latex fangle.lyx
5086     <item>fangle -R./fangle fangle.tex \<gtr\> ./fangle
5088     <item>fangle -R./fangle.module fangle.tex \<gtr\> ./fangle.module
5089   </nf-chunk|sh|>
5091   <section|Testing>
5093   <\nf-chunk|test:helpers>
5094     <item>passtest() {
5096     <item> \ if "$@"
5098     <item> \ then echo "Passed"
5100     <item> \ else echo "Failed"
5102     <item> \ \ \ \ \ \ return 1
5104     <item> \ fi
5106     <item>}
5108     <item>
5110     <item>failtest() {
5112     <item> \ if ! "$@"
5114     <item> \ then echo "Passed"
5116     <item> \ else echo "Failed"
5118     <item> \ \ \ \ \ \ return 1
5120     <item> \ fi
5122     <item>}
5123   </nf-chunk||>
5125   <part|Tests>
5127   <chapter|Chunk Parameters>
5129   <\nf-chunk|test:chunk-params:sub>
5130     <item>I see a ${THING},
5132     <item>a ${THING} of colour ${colour},\ 
5134     <item>and looking closer =\<less\>\\chunkref{test:chunk-params:sub:sub}(${colour})\<gtr\>
5135   </nf-chunk||<tuple|THING|colour>>
5137   <\nf-chunk|test:chunk-params:sub:sub>
5138     <item>a funny shade of ${colour}
5139   </nf-chunk||<tuple|colour>>
5141   <\nf-chunk|test:chunk-params:text>
5142     <item>What do you see? "=\<less\>\\chunkref{test:chunk-params:sub}(joe,
5143     red)\<gtr\>"
5145     <item>Well, fancy!
5146   </nf-chunk||>
5148   Should generate output:
5150   <\nf-chunk|test:chunk-params:result>
5151     <item>What do you see? "I see a joe,
5153     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ a joe of colour red,\ 
5155     <item> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ and looking closer a funny shade
5156     of red"
5158     <item>Well, fancy!
5159   </nf-chunk||>
5161   And this chunk will perform the test:
5163   <\nf-chunk|test:chunk-params>
5164     <item>$FANGLE -Rtest:chunk-params:result $TEX_SRC \<gtr\> $TMP/answer
5165     \|\| exit 1
5167     <item>$FANGLE -Rtest:chunk-params:text $TEX_SRC \<gtr\> $TMP/result \|\|
5168     exit 1
5170     <item>passtest diff $TMP/answer $TMP/result \|\| (echo
5171     test:chunk-params:text failed ; exit 1)
5172   </nf-chunk||>
5174   <chapter|Compile-log-lyx><label|Compile-log-lyx>
5176   <\nf-chunk|Chunk:./compile-log-lyx>
5177     <item>#! /bin/sh
5179     <item># can't use gtkdialog -i, cos it uses the "source" command which
5180     ubuntu sh doesn't have
5182     <item>
5184     <item>main() {
5186     <item> \ errors="/tmp/compile.log.$$"
5188     <item># \ if grep '^[^ ]*:\\( In \\\|[0-9][0-9]*: [^ ]*:\\)' \<gtr\>
5189     $errors
5191     <item>if grep '^[^ ]*(\\([0-9][0-9]*\\)) *: *\\(error\\\|warning\\)'
5192     \<gtr\> $errors
5194     <item> \ then
5196     <item> \ \ \ sed -i -e 's/^[^ ]*[/\\\\]\\([^/\\\\]*\\)(\\([ 0-9][
5197     0-9]*\\)) *: */\\1:\\2\|\\2\|/' $errors
5199     <item> \ \ \ COMPILE_DIALOG='
5201     <item> \<less\>vbox\<gtr\>
5203     <item> \ \<less\>text\<gtr\>
5205     <item> \ \ \ \<less\>label\<gtr\>Compiler errors:\<less\>/label\<gtr\>
5207     <item> \ \<less\>/text\<gtr\>
5209     <item> \ \<less\>tree exported_column="0"\<gtr\>
5211     <item> \ \ \ \<less\>variable\<gtr\>LINE\<less\>/variable\<gtr\>
5213     <item> \ \ \ \<less\>height\<gtr\>400\<less\>/height\<gtr\>\<less\>width\<gtr\>800\<less\>/width\<gtr\>
5215     <item> \ \ \ \<less\>label\<gtr\>File \| Line \|
5216     Message\<less\>/label\<gtr\>
5218     <item> \ \ \ \<less\>action\<gtr\>'". $SELF ; "'lyxgoto
5219     $LINE\<less\>/action\<gtr\>
5221     <item> \ \ \ \<less\>input\<gtr\>'"cat $errors"'\<less\>/input\<gtr\>
5223     <item> \ \<less\>/tree\<gtr\>
5225     <item> \ \<less\>hbox\<gtr\>
5227     <item> \ \ \<less\>button\<gtr\>\<less\>label\<gtr\>Build\<less\>/label\<gtr\>
5229     <item> \ \ \ \ \<less\>action\<gtr\>lyxclient -c "LYXCMD:build-program"
5230     &\<less\>/action\<gtr\>
5232     <item> \ \ \<less\>/button\<gtr\>
5234     <item> \ \ \<less\>button ok\<gtr\>\<less\>/button\<gtr\>
5236     <item> \ \<less\>/hbox\<gtr\>
5238     <item> \<less\>/vbox\<gtr\>
5240     <item>'
5242     <item> \ \ \ export COMPILE_DIALOG
5244     <item> \ \ \ ( gtkdialog --program=COMPILE_DIALOG ; rm $errors ) &
5246     <item> \ else
5248     <item> \ \ \ rm $errors
5250     <item> \ fi
5252     <item>}
5254     <item>
5256     <item>lyxgoto() {
5258     <item> \ file="${LINE%:*}"
5260     <item> \ line="${LINE##*:}"
5262     <item> \ extraline=`cat $file \| head -n $line \| tac \| sed
5263     '/^\\\\\\\\begin{lstlisting}/q' \| wc -l`
5265     <item> \ extraline=`expr $extraline - 1`
5267     <item> \ lyxclient -c "LYXCMD:command-sequence server-goto-file-row $file
5268     $line ; char-forward ; repeat $extraline paragraph-down ;
5269     paragraph-up-select"
5271     <item>}
5273     <item>
5275     <item>SELF="$0"
5277     <item>if test -z "$COMPILE_DIALOG"
5279     <item>then main "$@"\ 
5281     <item>fi
5282   </nf-chunk|sh|>
5284   \;
5285 </body>
5287 <\initial>
5288   <\collection>
5289     <associate|info-flag|short>
5290     <associate|page-medium|paper>
5291     <associate|page-screen-height|982016tmpt>
5292     <associate|page-screen-margin|false>
5293     <associate|page-screen-width|1686528tmpt>
5294     <associate|page-show-hf|true>
5295     <associate|preamble|false>
5296     <associate|sfactor|5>
5297   </collection>
5298 </initial>
5300 <\references>
5301 </references>
5303 <\auxiliary>
5304 </auxiliary>