Update copies following NeedCProtect documentation

[wiki-uploads.git] / noweb / noweb-lyx.lyx

#LyX 1.6.2 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass literate-article
\begin_preamble
\usepackage{noweb}
\end_preamble
\use_default_options true
\begin_modules
logicalmkup
\end_modules
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize a4paper
\use_geometry false
\use_amsmath 1
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle fancy
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Title
Using Lyx and Noweb
\end_layout

\begin_layout Author
Sam Liddicott <sam@liddicott.com>
\end_layout

\begin_layout Date
9 July 2009
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Section*
Introduction
\end_layout

\begin_layout aphorism
noweb 2.11b and lyx 2.6.2 nearly play together nicely.
\end_layout

\begin_layout Standard
This document talks about finishing the job.
 To run these examples you will need Lyx 2.6.2 and noweb 2.11b, and a copy
 of notanglefix in the same folder as this document noweb-lyx.lyx
\end_layout

\begin_layout Part
\begin_inset CommandInset label
LatexCommand label
name "cha:noweb"

\end_inset

Fixing Lyx and Noweb
\end_layout

\begin_layout Standard
According to the Extended Lyx Features 
\begin_inset CommandInset citation
LatexCommand cite
key "lyx-noweb"

\end_inset

 which you should read, we use notangle to derive the 
\emph on
source files
\emph default
, and Lyx automatically uses noweave to generate the 
\emph on
output document
\emph default
.
\end_layout

\begin_layout Standard
There are, sadly, some serious problems with noweb and Lyx.
\end_layout

\begin_layout Section
<
\begin_inset space \hspace*{}
\length 0in
\end_inset

< in document chunks
\end_layout

\begin_layout Standard
notangle complains when a double chevron <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< occurs in non code chunk portions of the input document.
 These are supposed to be escaped with @, requiring me to enter @
\begin_inset space \hspace*{}
\length 0in
\end_inset

<
\begin_inset space \hspace*{}
\length 0in
\end_inset

<, however the @ is not being removed by noweave when it generates the output
 document.
 
\end_layout

\begin_layout Standard
To solve this problem and have more normal looking lyx at edit time, I tried
 inserting a zero-width space between the chevrons, looking somewhat like
 this in Lyx: <␣<, but being represented as <
\backslash
hspace*{0in}< internally.
\end_layout

\begin_layout Standard
Sadly this does not work in the Lyx-Code environment, where the zero width
 space is presented a literal space character, and so < < is emitted in
 the document with a space between the chevrons.
\end_layout

\begin_layout Standard
This sed applied 
\emph on
after
\emph default
 noweave attempts to remove the extra @, detecting the 
\backslash
textcompwordmark{} that noweave inserts between the chevrons:
\end_layout

\begin_layout Scrap
<<fix-noweave-at>>=
\begin_inset Newline newline
\end_inset

sed 's/@<
\backslash

\backslash
textcompwordmark{}</<
\backslash

\backslash
textcompwordmark{}</g;'
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
When <
\begin_inset space \hspace*{}
\length 0in
\end_inset

<chunk-name>
\begin_inset space \hspace*{}
\length 0in
\end_inset

> is used in the Lyx-Code environment to demonstrate a code chunk as in
 section 
\begin_inset CommandInset ref
LatexCommand ref
reference "lyx:example-scrap"

\end_inset

, no special behaviour is needed -- in fact a real noweb code chunk is being
 declared, and so as long as the chunk name does not conflict it is acceptable.
 Although notangle sees a real code chunk, noweave does not -- no doubt
 because noweave only detects chunks in a Lyx Scrap.
 In any case the sed on the previous line permits @
\begin_inset space \hspace*{}
\length 0in
\end_inset

<
\begin_inset space \hspace*{}
\length 0in
\end_inset

< to be used in the Lyx-Code environment.
\end_layout

\begin_layout Section
<
\begin_inset space \hspace*{}
\length 0in
\end_inset

< in code chunks
\end_layout

\begin_layout Standard
When a double chrevron occurs within a code chunk it us usually must also
 be escaped with @, but it is shown in the generated document as a double
 chevron 
\begin_inset ERT
status open

\begin_layout Plain Layout

@<<, or >>
\end_layout

\end_inset

.
 If it is not escaped with @, then it shows in the document as the angle
 bracket ⟨.
 
\end_layout

\begin_layout Standard
This seems to be a noweave bug which should replace non-special <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< in noweb chunks with <
\backslash
textcompwordmark<
\end_layout

\begin_layout Standard
The following sed must run 
\emph on
after
\emph default
 noweave and prevents <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< and >
\begin_inset space \hspace*{}
\length 0in
\end_inset

> from being interpreted as 
\begin_inset ERT
status open

\begin_layout Plain Layout

@<<, or >>
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
First we detect when begincode environment starts or ends by coping those
 lines to the hold space with the sed h command.
\end_layout

\begin_layout Scrap
<<fix-noweave-chevron>>=
\begin_inset Newline newline
\end_inset

sed '/[^
\backslash

\backslash
]
\backslash

\backslash
nwbegincode/h;
\begin_inset Newline newline
\end_inset

     /[^
\backslash

\backslash
]
\backslash

\backslash
nwendcode/h;
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The [^
\backslash

\backslash
] is required to prevent the literal 
\backslash
nwendcode in this code chunk from triggering the nwbegincode and nwendcode
 detectors when this document is processed.
 It doesn't work by merely avoiding nwbegincode preceded by two slashes
 
\emph on
because
\emph default
 it appears that way in this code chunk.
\end_layout

\begin_layout Standard
It is because noweave is escaping back-slashes with another back-slash anyway
 so a double backslash signifies a literal document backslash, and it is
 these that we wish to avoid.
 In fact the noweave output of this chunk looks like this now: [^
\backslash

\backslash

\backslash

\backslash
]
\backslash

\backslash

\backslash

\backslash
nwbegincode?
\end_layout

\begin_layout Standard
Then, for lines that contain <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< or >
\begin_inset space \hspace*{}
\length 0in
\end_inset

> we check that the line in the hold space contains 
\emph on
begincode
\emph default
, by using the sed x command to exchange the current line in pattern space
 with the saved line in hold space and then doing a match.
 
\end_layout

\begin_layout Standard
If there is a match, then we know that we are in the begincode environment,
 and we do a replace to insert 
\backslash

\backslash
textcompwordmark between them.
 The sed /g makes sure we do this for all occurances on the line.
\end_layout

\begin_layout Scrap
<<fix-noweave-chevron>>=
\begin_inset Newline newline
\end_inset

     /<</{x;/begincode/{x;s/<</<
\backslash

\backslash
textcompwordmark</g;x};x};
\begin_inset Newline newline
\end_inset

     />>/{x;/begincode/{x;s/>>/>
\backslash

\backslash
textcompwordmark>/g;x};x}'
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Section
Underscore in chunk names
\end_layout

\begin_layout Standard
Underscores cannot be expressed in the fragment name; e.g.
\end_layout

\begin_layout LyX-Code
<<file_name.h>>=
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
otherwise the document refuses to generate.
 I believe this is a noweave bug, it should escape any _ in the <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< chunk >
\begin_inset space \hspace*{}
\length 0in
\end_inset

> line with a 
\backslash
.
\end_layout

\begin_layout Standard
The following sed must be run 
\emph on
before
\emph default
 noweave to fix this: 
\end_layout

\begin_layout Scrap
<<fix-noweave-underscore>>=
\begin_inset Newline newline
\end_inset

sed '/^<
\begin_inset space \hspace*{}
\length 0in
\end_inset

</s/_/
\backslash

\backslash
_/g'
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
This makes the noweave output conversion filter set in Tools\SpecialChar \menuseparator
Preferences\SpecialChar \menuseparator
File
 Handling\SpecialChar \menuseparator
Converters\SpecialChar \menuseparator
NoWeb -> Latex something like this
\begin_inset Note Note
status open

\begin_layout Plain Layout
I would have used @<<fix-noweave-underscore>> but I wanted the entire code
 to output in the document.
 I wish there was a @<<>> variant that showed the included text in the output
 document.
\end_layout

\end_inset

:
\end_layout

\begin_layout Scrap
<<fix-noweave>>=
\begin_inset Newline newline
\end_inset

sed '/^<</s/_/
\backslash

\backslash
_/g' $$i |
\begin_inset Newline newline
\end_inset

noweave -delay -index - |
\begin_inset Newline newline
\end_inset

sed 's/@<
\backslash

\backslash
textcompwordmark{}</<
\backslash

\backslash
textcompwordmark{}</g;' |
\begin_inset Newline newline
\end_inset

sed '/[^
\backslash

\backslash
]
\backslash

\backslash
nwbegincode/h;
\begin_inset Newline newline
\end_inset

     /[^
\backslash

\backslash
]
\backslash

\backslash
nwendcode/h; 
\begin_inset Newline newline
\end_inset

     /<</{x;/begincode/{x;s/<</<
\backslash

\backslash
textcompwordmark</g;x};x};
\begin_inset Newline newline
\end_inset

     />>/{x;/begincode/{x;s/>>/>
\backslash

\backslash
textcompwordmark>/g;x};x}' > $$o
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sub:notangle--L-breaks"

\end_inset

notangle -L breaks indentation
\end_layout

\begin_layout Standard
Normally we would generate the source using someting like:
\end_layout

\begin_layout LyX-Code
notangle -L'#line %L "%F"%N' -Rexample-print-loop noweb-lyx.lyx
\end_layout

\begin_layout Standard
Although -L'#line %L "%F"%N' is required to aid tracing compile errors back
 to the lyx document, it also spoils the indentation of the C output.
\end_layout

\begin_layout Standard
Normally the indent before the chunk include is applied to each line of
 the included chunk; e.g.
\end_layout

\begin_layout LyX-Code
\begin_inset CommandInset label
LatexCommand label
name "lyx:example-scrap"

\end_inset

@<<example-print>>=
\end_layout

\begin_layout LyX-Code
     printf 
\begin_inset Quotes eld
\end_inset

Hello
\backslash
n
\begin_inset Quotes erd
\end_inset

;
\end_layout

\begin_layout LyX-Code
     @ 
\end_layout

\begin_layout LyX-Code
 
\end_layout

\begin_layout LyX-Code
\begin_inset CommandInset label
LatexCommand label
name "lyx:example-print-loop"

\end_inset

@<<example-print-loop>>=
\end_layout

\begin_layout LyX-Code
     int main() {
\end_layout

\begin_layout LyX-Code
     ␣␣int a;
\end_layout

\begin_layout LyX-Code
     ␣␣for(a=0; a<5; a++) {
\end_layout

\begin_layout LyX-Code
     ␣␣␣␣@<<example-print>>
\end_layout

\begin_layout LyX-Code
     ␣␣}
\end_layout

\begin_layout LyX-Code
     }
\end_layout

\begin_layout LyX-Code
     @ 
\end_layout

\begin_layout Standard
Would generate something like this if the -L argument were not used
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
although the output looks only 
\emph on
somewhat
\emph default
 like this on account of other notangle problems, see section 
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Generally-mangled-notangle"

\end_inset


\end_layout

\end_inset

:
\end_layout

\begin_layout LyX-Code
int main() {
\end_layout

\begin_layout LyX-Code
␣␣int a;
\end_layout

\begin_layout LyX-Code
␣␣for(a=0; a<5; a++) {
\end_layout

\begin_layout LyX-Code
␣␣␣␣printf "Hello ";
\end_layout

\begin_layout LyX-Code
␣␣␣␣printf 
\begin_inset Quotes eld
\end_inset

there
\backslash
n
\begin_inset Quotes erd
\end_inset

;
\end_layout

\begin_layout LyX-Code
␣␣}
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
Here is an extract of the C it generates when the argument -L'#line %L "%F"%N'
 is used:
\end_layout

\begin_layout LyX-Code
#line 509 "noweb-lyx.lyx"
\end_layout

\begin_layout LyX-Code
int main() {
\end_layout

\begin_layout LyX-Code
␣␣int a;
\end_layout

\begin_layout LyX-Code
␣␣for(a=0; a<5; a++) {
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\end_layout

\begin_layout LyX-Code
#line 491 "noweb-lyx.lyx"
\end_layout

\begin_layout LyX-Code
printf "Hello ";
\end_layout

\begin_layout LyX-Code
printf "there
\backslash
n";
\end_layout

\begin_layout LyX-Code
#line 525 "noweb-lyx.lyx"
\end_layout

\begin_layout LyX-Code
␣␣}
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
We see that the correct indent is emitted on the line before the #line statement
, but the rest of the block is not indented.
 We must fix this by storing any non-newline white space before a line matching
 /^#line/ and inserting it before each line.
\end_layout

\begin_layout Standard
We do this in section 
\begin_inset CommandInset ref
LatexCommand vref
reference "notanglefix-leading-space"

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sub:Generally-mangled-notangle"

\end_inset

Generally mangled notangle output
\end_layout

\begin_layout Standard
There also is serious problem with either noweb or Lyx's Scrap handling.
 For instance, when the code block 
\emph on
example-print-loop
\emph default
 (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "lyx:example-print-loop"

\end_inset

) is untangled we see mangled output like this:
\end_layout

\begin_layout LyX-Code

\backslash
begin_inset Newline newline
\end_layout

\begin_layout LyX-Code

\backslash
end_inset
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
int main() {
\end_layout

\begin_layout LyX-Code

\backslash
begin_inset Newline newline
\end_layout

\begin_layout LyX-Code

\backslash
end_inset
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
␣␣int a;
\end_layout

\begin_layout LyX-Code

\backslash
begin_inset Newline newline
\end_layout

\begin_layout LyX-Code

\backslash
end_inset
\end_layout

\begin_layout LyX-Code
...
\end_layout

\begin_layout LyX-Code
␣␣␣␣printf 
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\backslash
begin_inset "
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\backslash
end_inset
\end_layout

\begin_layout LyX-Code
␣␣␣␣Hello
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\backslash
backslash
\end_layout

\begin_layout LyX-Code
␣␣␣␣n
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\backslash
begin_inset "
\end_layout

\begin_layout LyX-Code
␣␣␣␣
\backslash
end_inset
\end_layout

\begin_layout Standard
Line-breaks occur freely, and backslash characters come out as 
\backslash
backslash on a new line, sometimes with a blank line following.
 In fact the output has not been properly un-lyx-ified.
\end_layout

\begin_layout Standard
An awk helper script 
\emph on
notanglefix
\emph default
 is used to replace 
\backslash
backslash with an actual backslash and to remove newline characters altogether,
 and instead insert newlines where 
\emph on

\backslash
begin_inset Newline newline
\emph default
 occurs.
 (I also note that the promised [[ ]] for quoting code doesn't work).
\end_layout

\begin_layout Standard
We call this 
\emph on
notanglefix
\emph default
 because it fixes the output from notangle.
\end_layout

\begin_layout Standard
Note the space after #! which makes the first four characters #! /, and
 aids BSD systems which use the first four characters of a file as the magic
 number for script handling.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

#! /usr/bin/awk -f
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
emit_buffer simply outputs the newline-less buffer of accumulated text.
 AWK's print adds a newline on the end automatically.
 The buffer is then cleared ready for more data.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

function emit_buffer() {
\begin_inset Newline newline
\end_inset

  print indent buffer;
\begin_inset Newline newline
\end_inset

  buffer = "";
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The BEGIN block is used to initialize the buffer, although this isn't required
 by AWK.
 The indent is used to fixup indenting when the -L argument has been used
 for notangle as mentioned in section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:notangle--L-breaks"

\end_inset

.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

BEGIN {
\begin_inset Newline newline
\end_inset

  buffer = "";
\begin_inset Newline newline
\end_inset

  indent = "";
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
As notanges -L output the indent once only before the #line, we need to
 store this indent when we see #line.
 We also match a digit after the token #line in order to avoid wrongly detecting
 files (like Makefile.inc in section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Keeping-extracted-files"

\end_inset

) which might specify -L'#line %L "%F"%N'
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

/^ *#line [0-9]/ {
\begin_inset Newline newline
\end_inset

  indent = buffer;
\begin_inset Newline newline
\end_inset

  buffer = "";
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "notanglefix-leading-space"

\end_inset

We want to trim leading white-space on each line -- unless we haven't accumulate
d any output yet.
 This permits us to preserve notangles indent at the start of each proper
 line, without caring when lyx starts a new line for things like 
\backslash
backslash.
 Because we preserve the first chunk of white space, the #line matching
 code is able to take this and store it when -L mode is used.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

/^  */ {
\begin_inset Newline newline
\end_inset

  if (length(buffer) > 0) gsub("^ *", "");
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The inset 
\begin_inset Quotes eld
\end_inset

Newline newline
\begin_inset Quotes erd
\end_inset

 was determined to be emitted by notangle everywhere ctrl+enter was used
 in the lyx Scrap style, so we use this pattern to emit the buffer (with
 a trailing newline).
 We avoid doing this on the first line of the document in order to prevent
 all generate files starting with a blank line.
 This would otherwise occur, because I press ctrl+enter after the 
\emph on
<
\begin_inset space \hspace*{}
\length 0in
\end_inset

<chunk>
\begin_inset space \hspace*{}
\length 0in
\end_inset

>=
\emph default
 line before typing code in a code chunk in order to get a common indent
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Sadly if the first line of a chunk includes another chunk then we still
 get blank lines at the top of the document.
 The fix is probably to remove any Newline insets immediately after the
 chunk starts.
\end_layout

\end_inset

.
 
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

/
\backslash

\backslash
begin_inset Newline newline$/ {
\begin_inset Newline newline
\end_inset

  if (NR > 1) emit_buffer();
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
A line containing only 
\backslash
backslash is emitted by lyx where an actual backslash was present in the
 chunk, so we convert this back into a literal backslash.
 No other special character treatment has been observed as yet.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

/^ *
\backslash

\backslash
backslash/ {
\begin_inset Newline newline
\end_inset

  buffer = buffer "
\backslash

\backslash
";
\begin_inset Newline newline
\end_inset

  $0 = "";
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
Other lines observed that contain sections with a backslash don't seem relevant
 to the Scrap and so are removed.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

/
\backslash

\backslash
/ {
\begin_inset Newline newline
\end_inset

  gsub("
\backslash

\backslash

\backslash

\backslash
.*$", "");
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The default action is to append the line to the buffer.
 In AWK (unlike PERL's $_) the trailing newline is not part of $0 so we
 don't need to explicitly strip the newline at the end of $0.
 This also means that blank lines in the input are ignored.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

{
\begin_inset Newline newline
\end_inset

  buffer = buffer $0;
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
At the end of the file we emit_buffer, but only if it is not empty.
 This stops a blank line being emitted at the end of the output file.
 It also means that if the final line of the Lyx Scrap was didn't have a
 newline, that a newline will still be appended by emit_buffer.
 This is not considered a bug.
\end_layout

\begin_layout Scrap
<<notanglefix>>=
\begin_inset Newline newline
\end_inset

END {
\begin_inset Newline newline
\end_inset

  if (length(buffer) > 0) emit_buffer();
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The irony is in getting notanglefix out of this noweb document, as notanglefix
 is also required in order to get notanglefix out of this document.
\end_layout

\begin_layout Standard
A shorter (but perhaps not faster) variation could be based on this older
 but more confusing version, by defining the record separator as the same
 as the Lyx line separator, and otherwise treating embedded newlines as
 superfluous.
 This example is not complete.
\end_layout

\begin_layout Scrap
<<notanglefix2>>=
\begin_inset Newline newline
\end_inset

#! /usr/bin/awk -f
\begin_inset Newline newline
\end_inset


\begin_inset Newline newline
\end_inset

BEGIN {
\begin_inset Newline newline
\end_inset

  RS="[ ]*
\backslash

\backslash

\backslash

\backslash
begin_inset Newline newline[ 
\backslash
n]*
\backslash

\backslash

\backslash

\backslash
end_inset
\backslash
n"
\begin_inset Newline newline
\end_inset

  buffer = "";
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset


\begin_inset Newline newline
\end_inset

{
\begin_inset Newline newline
\end_inset

  gsub("
\backslash

\backslash

\backslash

\backslash
backslash", "
\backslash

\backslash
");
\begin_inset Newline newline
\end_inset

  gsub("
\backslash
n","");
\begin_inset Newline newline
\end_inset

  if (NR>1) print;
\begin_inset Newline newline
\end_inset

}
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
Finally, to extract a C source file, we use this command, where $1 is the
 lyx filename and $2 is the root fragment to extract:
\end_layout

\begin_layout Scrap
<<fix-notangle-extract>>=
\begin_inset Newline newline
\end_inset

notangle -L'#line %L "%F"%N' ${2+-R"$2"} "$1" 
\backslash

\begin_inset Newline newline
\end_inset

  | awk -f notangle-fix
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Part
Using Noweb
\end_layout

\begin_layout Section
A word about Make with Noweb and Lyx
\end_layout

\begin_layout Standard
Whitespace formatting is very important in a Makefile.
 The first character of each command line must be a TAB.
\end_layout

\begin_layout LyX-Code
target: pre-requisite
\begin_inset Newline newline
\end_inset

   →    action
\begin_inset Newline newline
\end_inset

   →    action
\end_layout

\begin_layout Standard
But a TAB is pretty hard to enter in a Lyx scrap.
 An alternative is to use a semi-colon after the pre-requisite, and a backslash
 at the end of each line (except the last).
\end_layout

\begin_layout LyX-Code
target: pre-requisite ; 
\backslash

\begin_inset Newline newline
\end_inset

␣␣action 
\backslash

\begin_inset Newline newline
\end_inset

␣␣action
\end_layout

\begin_layout Standard
This is the style that we use and it works pretty well for GNU make at least.
\end_layout

\begin_layout Standard
We also adopt a convention that code chunks whose names beginning with ./
 should always be automatically extracted from the document.
 Code chunks whose names do not begin with ./ are for internal reference.
 (This doesn't prevent such chunks from being extracted directly).
\end_layout

\begin_layout Section
Boot-strapping the extraction
\end_layout

\begin_layout Standard
It seems convenient to have the makefile extract or update the C source
 files as part of it's operation.
 It also seems convenient to have the makefile itself extracted from this
 document.
\end_layout

\begin_layout Standard
It would also be convenient to have the code to extract the makefile from
 this document to also be part of this document, however we have to start
 somewhere and this unfortunately requires us to type at least a few words
 by hand to start things off.
\end_layout

\begin_layout Standard
Therefore we will have a minimal root fragment, which, when extracted, can
 cope with extracting the rest of the source.
 This, along fix notanglefix will need to be extracted manually somehow
 first, perhaps with this shell script, which could be called 
\emph on
autoboot
\emph default
.
\end_layout

\begin_layout Scrap
<<*>>=
\begin_inset Newline newline
\end_inset

#! /bin/sh
\begin_inset Newline newline
\end_inset


\begin_inset Newline newline
\end_inset

notangle -R./Makefile.inc "${1:-noweb-lyx.lyx}" 
\backslash

\begin_inset Newline newline
\end_inset

  | awk -f notanglefix > ./Makefile.inc
\begin_inset Newline newline
\end_inset


\begin_inset Newline newline
\end_inset

make -f ./Makefile.inc tangle_source
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The general Makefile can be invoked with 
\emph on
./autoboot
\emph default
 and can also be included into any automake file to automatically re-generate
 the source files.
\end_layout

\begin_layout Standard
The 
\emph on
autoboot
\emph default
 can be extracted with this command:
\end_layout

\begin_layout LyX-Code
notangle noweb-lyx.lyx | awk -f notanglefix > ./autoboot
\end_layout

\begin_layout Standard
This looks simple enough, but as mentioned, notanglefix has to be had from
 somewhere before it can be extracted.
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sub:Keeping-extracted-files"

\end_inset

Keeping extracted files up to date
\end_layout

\begin_layout Standard
Makefile.inc will cope with extracting all the other source files from this
 document and keeping them up to date.
 It make may also be included by Makefile.am.
\end_layout

\begin_layout Standard
We first define NOWEB_SOURCE to hold the name of this Lyx file.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

NOWEB_SOURCE=noweb-lyx.lyx
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The Lyx document can result in any number of source documents, but not all
 of these will be changed each time the Lyx document is updated.
 We certainly don't want to update the timestamps of these files and cause
 the whole source tree to be recompiled just because the Lyx document was
 edited.
 To solve this problem we use a stamp file which is always updated each
 time the sources are extracted from the Lyx document.
 If the stamp file is older than the Lyx document then we can make an attempt
 to re-extract the sources.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

NOWEB_SOURCE_STAMP=$(NOWEB_SOURCE).stamp
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
We also must compute NOWEB_SOURCES to hold the names of all the source files
 defined in this document.
 We compute this only once, by means of := in assignent.
 The sed deletes the <
\begin_inset space \hspace*{}
\length 0in
\end_inset

< and >
\begin_inset space \hspace*{}
\length 0in
\end_inset

> which surround the output of the noroots command, and removes the root
 called * as that is not a valid filename.
 
\end_layout

\begin_layout Standard
As we use chunk names beginning with ./ to denote top level fragments that
 should be extracted, we also filter out all fragments that do not begin
 with ./
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

NOWEB_SOURCES:=$(shell noroots $(NOWEB_SOURCE) |
\backslash

\begin_inset Newline newline
\end_inset

  sed -e 's/^@<<//;s/@>>$$//;/^
\backslash
*$$/d;/^
\backslash
.
\backslash
//!d')
\begin_inset Newline newline
\end_inset


\begin_inset Newline newline
\end_inset

echo_noweb_sources: ; @echo $(NOWEB_SOURCES)
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
We define a convenient target called noweb_sources to re-extract the source
 if the Lyx file has been updated.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

noweb_sources: $(NOWEB_SOURCE_STAMP)
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
And also a convenient target to remove extracted sources.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

clean_noweb_sources: ; rm $(NOWEB_SOURCESTAMP) $(NOWEB_SOURCES)
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
We now define the pattern for extracting a file.
 The files are written using noweb's 
\emph on
cpif
\emph default
 so that the file timestamp will not be touched if the contents haven't
 changed.
 This avoids the need to rebuild the entire project because of a typographical
 change in the documentation, or if only a few C source files have changed.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

noweb_extract = mkdir -p $(dir $(1)) && 
\backslash

\begin_inset Newline newline
\end_inset

  notangle $(call notangle_args,$(1)) 
\backslash

\begin_inset Newline newline
\end_inset

    -R"$(1)" "$(2)" 
\backslash

\begin_inset Newline newline
\end_inset

  | awk -f notanglefix | cpif "$(1)"
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
For some source files like C files, we want to turn on source tracing by
 passing additional -L arguments to notangle so that C compile errors will
 refer to the line number in this document.
 We do this using the makefile macro tangle_line to generate these arguments
 for certain file extensions: C_EXTENSIONS.
\end_layout

\begin_layout Scrap
<<Makefile.inc>>=
\begin_inset Newline newline
\end_inset

C_EXTENSIONS=.c .h
\begin_inset Newline newline
\end_inset

C_SOURCE_TRACING=-L'
\backslash
#line %L "%F"%N'
\begin_inset Newline newline
\end_inset

notangle_args = $(if $(findstring $(suffix $(1)),
\backslash

\begin_inset Newline newline
\end_inset

    $(C_EXTENSIONS)),$(C_SOURCE_TRACING))
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
Source tracing can be turned off with:
\end_layout

\begin_layout LyX-Code
make notangle_sources C_SOURCE_TRACING=
\end_layout

\begin_layout Standard
We define a target which will extract or update all sources.
 Sadly in this first attempt the targets are all extracted in one big command
 line.
 
\end_layout

\begin_layout Scrap
<<Makefile.inc-sources-big>>=
\begin_inset Newline newline
\end_inset

$(NOWEB_SOURCE_STAMP): $(NOWEB_SOURCE); 
\backslash

\begin_inset Newline newline
\end_inset

  $(foreach source,$(NOWEB_SOURCES),
\backslash

\begin_inset Newline newline
\end_inset

    $(call noweb_extract,$(source),$(NOWEB_SOURCE)) && 
\backslash

\begin_inset Newline newline
\end_inset

  ) touch $(NOWEB_SOURCE_STAMP)
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
This better alternative defines a target for each extractable source file
 and has 
\emph on
make
\emph default
 extract them individually.
 To do this we first defined a makefile template that can do this for any
 source file.
\end_layout

\begin_layout Scrap
<<Makefile.inc-sources>>=
\begin_inset Newline newline
\end_inset

define NOTANGLE_template
\begin_inset Newline newline
\end_inset

  $(1): $(2); 
\backslash

\begin_inset Newline newline
\end_inset

    $(call noweb_extract,$(1),$(2))
\begin_inset Newline newline
\end_inset

  NOWEB_TARGETS+=$(1)
\begin_inset Newline newline
\end_inset

endef
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
We then enumerate the discovered NOTANGLE_SOURCES to generate a makefile
 rule for each one using the makefile template we defined above.
\end_layout

\begin_layout Scrap
<<Makefile.inc-sources>>=
\begin_inset Newline newline
\end_inset

$(foreach source,$(NOWEB_SOURCES),
\backslash

\begin_inset Newline newline
\end_inset

  $(eval $(call NOTANGLE_template,$(source),$(NOWEB_SOURCE)))
\backslash

\begin_inset Newline newline
\end_inset

)
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
And finally declare the rule to build them all:
\end_layout

\begin_layout Scrap
<<Makefile.inc-sources>>=
\begin_inset Newline newline
\end_inset

$(NOWEB_SOURCE_STAMP): $(NOWEB_SOURCE) $(NOWEB_TARGETS); 
\backslash

\begin_inset Newline newline
\end_inset

  touch $(NOWEB_SOURCE_STAMP)
\backslash

\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
The Makefile.inc is then defined as
\end_layout

\begin_layout Scrap
<<./Makefile.inc>>=
\begin_inset Newline newline
\end_inset

<<Makefile.inc>>
\begin_inset Newline newline
\end_inset

<<Makefile.inc-sources>>
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
We may as well have notanglefix from section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Generally-mangled-notangle"

\end_inset

 extracted automatically too, but it will sadly begin with a blank line.
\end_layout

\begin_layout Scrap
<<./notanglefix.awk>>=
\begin_inset Newline newline
\end_inset

<<notanglefix>>
\begin_inset Newline newline
\end_inset

@
\end_layout

\begin_layout Standard
If Makefile.inc is included into Makefile, then extracted files can be updated
 with this command:
\end_layout

\begin_layout LyX-Code
make noweb_sources
\end_layout

\begin_layout Standard
otherwise, with:
\end_layout

\begin_layout LyX-Code
make -f Makefile.inc noweb_sources
\end_layout

\begin_layout Bibliography
\begin_inset CommandInset bibitem
LatexCommand bibitem
label "Extended Lyx Features"
key "lyx-noweb"

\end_inset

http://nuclear.gla.ac.uk/computing/LyX_doc/Extended.html#tth_sEc6.5
\end_layout

\end_body
\end_document