From e4e4254f08cc278f3f8c0709e9ff4812453b6d7d Mon Sep 17 00:00:00 2001 From: Sam Liddicott Date: Fri, 18 May 2012 16:44:45 +0100 Subject: [PATCH] WIP refactore good fake page support --- docs/examples/hello-world.tm | 310 +++++------------- docs/getting-started.tm | 589 ++++----------------------------- fangle.ts | 36 +- www/examples/hello-world.tm | 758 +++++++++++++------------------------------ 4 files changed, 389 insertions(+), 1304 deletions(-) rewrite docs/examples/hello-world.tm (84%) rewrite www/examples/hello-world.tm (73%) diff --git a/docs/examples/hello-world.tm b/docs/examples/hello-world.tm dissimilarity index 84% index c5d04a0..89d41c4 100644 --- a/docs/examples/hello-world.tm +++ b/docs/examples/hello-world.tm @@ -1,234 +1,76 @@ - - -> - -<\body> - <\hide-preamble> - - - - ||<\author-address> - sam@liddicott.com - >> - - <\abstract> - <\small> - This is a simple example of how to use literate programming templates, - using hello-world. - - Hello-world is a famous with a visible side effect. - - This example produces hello-world in multiple languages. - - - - <\table-of-contents|toc> - Hello - World> |.>>>>|> - - - In French - |.>>>>|> - > - - In German - |.>>>>|> - > - - - - - The typical hello world program looks like this: - - <\nf-chunk|hello-world> - /* The traditional hello-world program in \ - - * generated using fangle literate programming macros - - */ - - - - #include stdio.c - - - - main() { - - \ printf("\\n"); - - } - > - - - - \; - - We will derive the french hello-world program like this: - - <\nf-chunk|./hello-world.fr.c> - > - - - - - We will derive the german hello-world program like this: - - <\nf-chunk|./hello-world.de.c> - > - - - -<\references> - <\collection> - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - - - -<\auxiliary> - <\collection> - <\associate|toc> - |math-font-series||1Hello - World> |.>>>>|> - - - |1.1In French - |.>>>>|> - > - - |1.2In German - |.>>>>|> - > - - - \ No newline at end of file + + +> + +<\body> + <\hide-preamble> + + + + ||<\author-address> + sam@liddicott.com + >> + + <\abstract> + <\small> + This is a simple example of how to use literate programming templates, + using hello-world. + + Hello-world is a famous with a visible side effect. + + This example produces hello-world in multiple languages. + + + + <\table-of-contents|toc> + + + + + The typical hello world program looks like this: + + <\nf-chunk|hello-world> + /* The traditional hello-world program in \ + + * generated using fangle literate programming macros + + */ + + + + #include stdio.c + + + + main() { + + \ printf("\\n"); + + } + > + + + + \; + + We will derive the french hello-world program like this: + + <\nf-chunk|./hello-world.fr.c> + > + + + + + We will derive the german hello-world program like this: + + <\nf-chunk|./hello-world.de.c> + > + + + +<\references> + + +<\auxiliary> + \ No newline at end of file diff --git a/docs/getting-started.tm b/docs/getting-started.tm index cc3f72f..04078bb 100644 --- a/docs/getting-started.tm +++ b/docs/getting-started.tm @@ -1,4 +1,4 @@ - + > @@ -10,7 +10,7 @@ >>> - + <\wide-std-framed> \; @@ -62,178 +62,6 @@ <\table-of-contents|toc> - Getting - and Installing Fangle> |.>>>>|> - - - Getting - Fangle> |.>>>>|> - - - Installing - Fangle> |.>>>>|> - - - Choosing the editing environment - |.>>>>|> - > - - For personal use - |.>>>>|> - > - - Executables - |.>>>>|> - > - - T||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>> - plugins |.>>>>|> - > - - The - LX stylesheet - |.>>>>|> - > - - The - T||||0.5fn>|0fn|-0.1fn>>X - stylesheet |.>>>>|> - > - - For system-wide use - |.>>>>|> - > - - Executables - |.>>>>|> - > - - The - T||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>> - stylesheet |.>>>>|> - > - - The - LX stylesheet - |.>>>>|> - > - - The - T||||0.5fn>|0fn|-0.1fn>>X - stylesheet |.>>>>|> - > - - Authoring - with Fangle> |.>>>>|> - - - T||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>>> - |.>>>>|> - - - Load fangle style-sheet - |.>>>>|> - > - - Save the document - |.>>>>|> - > - - Sandard document parts - |.>>>>|> - > - - Insert your title - |.>>>>|> - > - - Insert your abstract - |.>>>>|> - > - - Insert a table of contents - |.>>>>|> - > - - Start a new section (or chapter) - |.>>>>|> - > - - Talk about your code - |.>>>>|> - > - - Insert your first code chunk - |.>>>>|> - > - - Optional chunk parameters - |.>>>>|> - > - - Create a tuple - |.>>>>|> - > - - Optional language - |.>>>>|> - > - - Type the language - |.>>>>|> - > - - Typing code - |.>>>>|> - > - - Referencing arguments - |.>>>>|> - > - - File chunks - |.>>>>|> - > - - French hello-world - |.>>>>|> - > - - German hello-world - |.>>>>|> - > - - The document so far - |.>>>>|> - > - - Additional parameters - |.>>>>|> - > - - Passing parameters - |.>>>>|> - > - - Extra chunklets - |.>>>>|> - > - - The completed document - |.>>>>|> - > - - Generating - the files> |.>>>>|> - - - Extracting individual files - |.>>>>|> - > - - Extracting all files - |.>>>>|> - > @@ -412,7 +240,7 @@ The system-wide folder defaults to , but may vary across installations. Within that is a sub-folder called > into which the fangle module is - copued. + copied. You could override like this: @@ -566,6 +394,22 @@ Fangle chunks are (currently) called: and are entered like this: + <\fake-page> + a + + \; + + + <\fake-page> + + + <\nf-chunk|blahzig> + test\\value + + \\this-pag + + + <\enumerate> type: it will appear like this: > @@ -576,11 +420,11 @@ |||>> which is the inactive view, or the active view shown below: - <\sub-page> + <\fake-page> <\nf-fake-chunk|> \; - + If the text insertion point (represented by the red verticle line ) does not appear in the position shown above, then press @@ -591,11 +435,11 @@ This will give you either |||>> for the inactive view, or the active view shown as below: - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> \; - + @@ -607,11 +451,11 @@ give you >>, but for the active view shown below you will just need to press once: - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> \; - + You may now specify parameters to the code that will be contained in the chunk. Chunks can take optional parameters, and behave somewhat like C @@ -645,11 +489,11 @@ You can type multiple parameters: >>> or - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> \; >|1|1a|||||> - + @@ -669,11 +513,11 @@ For the active view, press to select the third argument - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> \; ||1|1a|||||> - + For syntax markup, supports C++ (called ) and bourne shell (called ), but for automatic quoting fangle @@ -685,11 +529,11 @@ Enter the language : |>> or - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> \; ||1|1a|||||> - + @@ -710,11 +554,11 @@ to delete the blank line that is somehow there. - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> |1|1a|||||> - + At this point, start typing code. @@ -723,7 +567,7 @@ layout purposes, but it will not be considered a new-line when the code is extracted, and leading white-space will be stripped. - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> #include \stdio.h\ @@ -733,7 +577,7 @@ \ printf(" |1|1a|||||> - + The listing above is incomplete. Instead of typing the the traditional , we can make use of our chunk arguments. Let's @@ -752,7 +596,7 @@ Finish typing the code as shown below: - <\sub-page> + <\fake-page> <\nf-fake-chunk|hello-world> #include \stdio.h\ @@ -764,7 +608,7 @@ } |1|1a|||||> - + We've now defined a chunk of code which can potentially produce the famous in any language. @@ -799,7 +643,7 @@ and then the chunk name - <\sub-page> + <\fake-page> > We will derive the french hello-world program like this: @@ -807,7 +651,7 @@ <\nf-fake-chunk|./hello-world.fr.c> - + To include our previous chunk with the command, type and then type the name of our previous chunk, @@ -818,7 +662,7 @@ - <\sub-page> + <\fake-page> > We will derive the french hello-world program like this: @@ -827,7 +671,7 @@ |1a> - + Note that when there are no arguments to the reference, the parenthesis do not appear, but they appear automatically when there are arguments. @@ -848,7 +692,7 @@ and then the chunk name - <\sub-page> + <\fake-page> > We will derive the german hello-world program like this: @@ -856,13 +700,13 @@ <\nf-fake-chunk|./hello-world.de.c> |1a> - + The document you typed might look something like this: - <\sub-page> + <\fake-page> <\with|par-par-sep|0fn> @@ -929,7 +773,7 @@ <\nf-fake-chunk|./hello-world.de.c> |1a> |1|1c|||||> - + Which demonstrates nicely how to use fangle in terms of function, but less so in terms of style. @@ -949,21 +793,21 @@ and extending the tuple by pressing , and then typing: - <\sub-page> + <\fake-page> <\nf-fake-chunk|./hello-world.fr.c> |1a> - + And doing similarly for the german: - <\sub-page> + <\fake-page> <\nf-fake-chunk|./hello-world.de.c> |1a> - + @@ -972,7 +816,7 @@ delete up to the word and then type - <\sub-page> + <\fake-page> \; The typical hello-world program should begin with an introductory @@ -989,7 +833,7 @@ } |1|1a|||||> - + We will now enter another hello-world chunk by typing and calling it as @@ -1009,7 +853,7 @@ Note that the second chunklet no longer has any parameters showing this is because it must use the same parameters as the first chunklet. - <\sub-page> + <\fake-page> \; The typical hello-world program should begin with an introductory @@ -1030,7 +874,7 @@ } |2|1b|||||> - + Create parameters for the first chunklet, as explained in , and these are then replicated in the other @@ -1043,7 +887,7 @@ When the final program is generated, the language will be inserted into the comment. - <\sub-page> + <\fake-page> \; The typical hello-world program should begin with an introductory @@ -1070,7 +914,7 @@ } |2|1b|1a|>|1a||> - + We see that chunk 1b is not very well explained, and is only obvious to someone who has already graduated beyond . We need to @@ -1079,7 +923,7 @@ - <\sub-page> + <\fake-page> \; The typical hello-world program should begin with an introductory @@ -1108,7 +952,7 @@ } |2|1b|1a||||>1a> - + But we also wish to explain the function, so we need to split the block. @@ -1118,7 +962,7 @@ Insert chunklet called hello-world and cut-n-paste the lines from the second chunklet into the third chunklet. - <\sub-page> + <\fake-page> \; The typical hello-world program should begin with an introductory @@ -1155,7 +999,7 @@ } |3|1c|||||> - + \; @@ -1166,7 +1010,7 @@ The document you typed might look something like this: - <\sub-page> + <\fake-page> <\with|par-par-sep|0fn> @@ -1254,7 +1098,7 @@ <\nf-fake-chunk|./hello-world.de.c> |1a> |1|1c|||||> - + \; @@ -1338,327 +1182,24 @@ done + + <\initial> <\collection> - + + <\references> - <\collection> - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - <\auxiliary> - <\collection> - <\associate|idx> - |Document>||Style>||article>>|> - - |Document>||Add - package>||fangle>>|> - - |Tools>||Update>||Styles>>|> - - |Document>||View>||Create - preamble>>|> - - |Document>||View>||Show - preamble>>|> - - |Document>||View>||Show - all parts>>|> - - |File>||Save>>|> - - |Insert>||Title>||Insert - title>>|> - - |Insert>||Title>||Abstract>>|> - - |Insert>||Automatic>||Table - of contents>>|> - - |Insert>||Section>||Section>>|> - - |Insert>||Section>||Chapter>>|> - - |Tools>||Update>||Styles>>|> - - |Insert>||Section>||Subsection>>|> - - |Insert>||Section>||Section>>|> - - |Insert>||Section>||Subsection>>|> - - |Insert>||Section>||Section>>|> - - |File>||Export\|Verbatim>>|> - - <\associate|table> - |> - - <\associate|toc> - |math-font-series||font-size||IGetting - and Installing Fangle> |.>>>>|> - - - |math-font-series||1Getting - Fangle> |.>>>>|> - - - |math-font-series||2Installing - Fangle> |.>>>>|> - - - |2.1Choosing the editing - environment |.>>>>|> - > - - |2.2For personal use - |.>>>>|> - > - - |2.2.1Executables - |.>>>>|> - > - - |2.2.2T|E>||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>> - plugins |.>>>>|> - > - - |2.2.3The - LX stylesheet - |.>>>>|> - > - - |2.2.4The - T|E>||||0.5fn>|0fn|-0.1fn>>X - stylesheet |.>>>>|> - > - - |2.3For system-wide use - |.>>>>|> - > - - |2.3.1Executables - |.>>>>|> - > - - |2.3.2The - T|E>||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>> - stylesheet |.>>>>|> - > - - |2.3.3The - LX stylesheet - |.>>>>|> - > - - |2.3.4The - T|E>||||0.5fn>|0fn|-0.1fn>>X - stylesheet |.>>>>|> - > - - |math-font-series||font-size||IIAuthoring - with Fangle> |.>>>>|> - - - |math-font-series||3T|E>||||0.5fn>|0fn|-0.1fn>>XACS||||0.5fn>|0fn|-0.1fn>>> - |.>>>>|> - - - |3.1Load fangle style-sheet - |.>>>>|> - > - - |3.2Save the document - |.>>>>|> - > - - |3.3Sandard document parts - |.>>>>|> - > - - |3.3.1Insert your title - |.>>>>|> - > - - |3.3.2Insert your abstract - |.>>>>|> - > - - |3.3.3Insert a table of contents - |.>>>>|> - > - - |3.3.4Start a new section (or - chapter) |.>>>>|> - > - - |3.4Talk about your code - |.>>>>|> - > - - |3.5Insert your first code - chunk |.>>>>|> - > - - |3.6Optional chunk parameters - |.>>>>|> - > - - |3.6.1Create a tuple - |.>>>>|> - > - - |3.7Optional language - |.>>>>|> - > - - |3.7.1Type the language - |.>>>>|> - > - - |3.8Typing code - |.>>>>|> - > - - |3.8.1Referencing arguments - |.>>>>|> - > - - |3.9File chunks - |.>>>>|> - > - - |3.9.1French hello-world - |.>>>>|> - > - - |3.9.2German hello-world - |.>>>>|> - > - - |3.10The document so far - |.>>>>|> - > - - |3.11Additional parameters - |.>>>>|> - > - - |3.11.1Passing parameters - |.>>>>|> - > - - |3.11.2Extra chunklets - |.>>>>|> - > - - |3.12The completed document - |.>>>>|> - > - - |math-font-series||font-size||IIIGenerating - the files> |.>>>>|> - - - |3.13Extracting individual - files |.>>>>|> - > - - |3.14Extracting all files - |.>>>>|> - > - - \ No newline at end of file diff --git a/fangle.ts b/fangle.ts index 1a32ab4..c011401 100644 --- a/fangle.ts +++ b/fangle.ts @@ -1,4 +1,4 @@ - + @@ -167,8 +167,30 @@ + >|tuple>|>|>>||>|>>> + |gr-frame|>|gr-geometry||gr-color|red|gr-auto-crop|false||>>||>>||>>>>>> + |>>>>>> + + + + |-|>>> + + |>|>>>>>>> + + >>|0>|1|>>>> + + >>|0>||0|>>>>> + + |label||pagerefpage||old-reference||reference||this-page-no|>|fake-page-base-name||-||-|>|>>> + + |>>||>>> + + |>|page-no||0>|instance||0>|>>>>> + + |1>>> + <\active*> <\src-comment> Now, some extensions to standard functionality. @@ -424,7 +446,7 @@ - |ref|>>>|1>>>>>> + >>>>> <\active*> <\src-comment> @@ -463,7 +485,7 @@ >>>>>> - >>||label>>>|>|>>|prev_label|>>|>>>|next|>>|>>||label>>>|>|>>>|next_label|>>| + >>||label>>>|>|>>|prev_label|>>|>>>|next|>>|>>||label>>>|>|>>>|next_label|>>| >>>|> @@ -719,7 +741,7 @@ >>> - >|y|||>>>|1ln|>||>>>|>|>>|0ln|1ln|0ln|>|>>|>|>>|<\with|item|>>>|item-vsep|0fn|current-item||transform-item|> + >|y|||>>>|1ln|>||>>>|>|>>|0ln|1ln|0ln|>|>>|>|>>|<\with|item|>>>|item-vsep|0fn|current-item||transform-item|> <\surround||>||end>>>>||end>>>|>>|nv-rangle|>>|||>>>>>> >> @@ -741,7 +763,7 @@ >>>> - >|chunk_no||chunk_label||first_chunk_label||prev||prev_label||next||next_label|||1>>|1ln|||>>>|>|0>|>|0>>|0ln|1ln|0ln|>|>|<\with|xitem||item-nr|0|item-vsep|0fn|current-item||transform-item|> + >|chunk_no||chunk_label||first_chunk_label||prev||prev_label||next||next_label|||1>>|1ln|||>>>|>|0>|>|0>>|0ln|1ln|0ln|>|>|<\with|xitem||item-nr|0|item-vsep|0fn|current-item||transform-item|> >> ||>> @@ -924,8 +946,8 @@ <\initial> <\collection> - - + + \ No newline at end of file diff --git a/www/examples/hello-world.tm b/www/examples/hello-world.tm dissimilarity index 73% index 149edfa..1c3e45f 100644 --- a/www/examples/hello-world.tm +++ b/www/examples/hello-world.tm @@ -1,539 +1,219 @@ - - -> - -<\body> - X>>> - - ||<\author-address> - Using and Fangle - >> - - <\abstract> - Literate Programming will not be explained here but it will be shown as a - way narrate program development showing the progression of ideas a is - natural for humans to understand, leaving the generation of programs from - those ideas to the machine. - - is used as the editor and <\footnote> - http://new.fangled.org - as the extraction tool. - - - Here we will explain the popular written in . - - - - Here is the message that we wish to give to world: - - - - Because we did not press enter in the literate programming environment, - this line is not prefixed in the document tree with an - item\> tag and so has no line number displayed and - is not a line but a line-fragment. - - <\note> - The header contains the chunk name as well as the language - of the listing which is . The beginning of the header gives the - id to this of code - which suggests to the reader that it is the first chunk on page - . <\footnote> - The label and hyperlink were generated with - the document tag chunk-reference\|message\|1\> - to generate a link to the first chunklet of the chunk named - . - - - - - - We have a few choices available. The message can be output with - , like this: - - <\nf-chunk|message-printf> - printf("\\n"); - - - or even with : - - <\nf-chunk|message-puts> - puts("\\n"); - <|nf-chunk> - cpp - - - But, we prefer which is more traditional. - - <\note> - These last two chunks have a different letter for the chunk reference - even though they may be on the same page. - - - <\note> - They also contain a line number, because they are intended to be a full - line of text. - - - - - <\note> - If a code chunk is split across two pages, as this next code chunk is, - the code chunk header is repeated in the page header of the last page. - The technique used is to put a at the begining of - the chunk and also at the end of the chunk. We take the - of each label, and if they are not on the same page, then at the end of - the chunk we set the page header to be the same as the chunk header.\ - - - We have to enclose this line in the standard C function, like - this: - - <\nf-chunk|main> - int main(int argc, char** argv) { - - \ - - \ return 0; - - } - - - The statement lets the operating system know that the - function completed successfully which is a bit of a presumption as - we don't check if is successful. - - <\note> - Note the statement defined in - has been included in - . - - - <\note> - The line numbering starts counting again from 1 for each named chunk. - - - - - By convention, with and , a chunk whose name begins - with a is considered to be a file suitable for automatic - extraction; so we will define out main chunk to be - - - - - On my system, both and both require the - header ; so this line becomes the first line of our file.\ - - <\nf-chunk|./hello-world.c> - #include stdout.h - > - - <\note> - The header contains a link to chunk - which is the next chunklet of this named chunk. - - - - - The include statement is followed by our main function that we defined in - . - - <\nf-chunk|./hello-world.c> - - - - <\note> - This time the header also contains a link to chunk - which is the previous chunklet of this - named chunk.\ - - - - - And a final good-bye comment. - - <\nf-chunk|./hello-world.c> - /* thats the end, folks */ - - - <\note> - Like the first chunks we looked at, there are no further chunklets with - the same name and so there is no link to the next chunklet shown, - although there is a link to the previous chunklet. - - - - - Because of the amount of page-referencing going on to calculate the - chunklet references, it can sometimes require the document to be updated - three or more times to fix the links and references. - - <\enumerate> - The first time, a chunk has to discover which page it is one. - - The second time all the chunks can be given the correct id based on - the page. - - The third time, all references to a chunk can be updated to the - correct id. - - A forth and additional times may be required if the page-breaking - was changed as a result of a change in label size although this - is only likely to occur if a reference occured in the text of the - document for the references in the header have enough space so as not to - affect layout. - - - - - The file can be extracted directly with: - - <\verbatim> - texmacs -s -c hello-world.tm hello-world.txt -q && - - fangle -R./hello-world.c hello-world.txt \ hello-world.c - - - Although this is a little verbose, it shows how things work. There is a - Makefile.inc project that allows you to do all that sort of thing - automatically. - - -<\initial> - <\collection> - - - - - - - - - -<\references> - <\collection> - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - > - |2>|?>> - > - > - > - > - > - > - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - |2>|?>> - > - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - |2>|?>> - > - > - ]|2>> - > - > - > - |3>|1>> - > - > - > - |3>|?>> - > - |3>|?>> - > - > - ]|2>> - > - > - > - > - |2>|1>> - > - > - > - > - > - > - > - > - > - > - > - a|2>> - > - > - > - b|?>> - > - b|?>> - > - b|?>> - > - b|?>> - > - a|?>> - > - a|?>> - > - a|?>> - > - a|?>> - > - > - > - > - b|?>> - > - b|?>> - > - b|?>> - > - |1>|1>> - > - > - > - > - > - > - > - > - |2>|1>> - > - |4>|?>> - > - |4>|?>> - > - |4>|?>> - > - |4>|?>> - > - |4>|?>> - > - |2>|1>> - > - |5>|1>> - ]|2>> - > - |5>|1>> - > - > - > - > - > - > - > - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - ]|2>> - > - > - > - > - a|?>> - f|?>> - f|?>> - > - i|1>> - a|?>> - a|?>> - a|?>> - a|?>> - a|?>> - ]|2>> - b|?>> - > - b|?>> - c|?>> - c|?>> - c|?>> - c|?>> - b|?>> - b|?>> - b|?>> - b|?>> - > - c|?>> - c|?>> - c|?>> - c|?>> - > - > - > - > - > - a|?>> - g|1>> - i|?>> - i|?>> - i|?>> - i|?>> - i|?>> - g|1>> - ]|2>> - h|1>> - > - > - > - > - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - g|?>> - > - > - > - > - a|?>> - f|?>> - f|?>> - > - > - > - a|?>> - a|?>> - a|?>> - a|?>> - a|?>> - > - b|?>> - c|?>> - c|?>> - c|?>> - c|?>> - b|?>> - b|?>> - b|?>> - b|?>> - > - c|?>> - c|?>> - c|?>> - > - > - > - > - > - > - a|?>> - |2>|1>> - > - > - > - > - > - g|1>> - > - > - > - > - > - > - > - |3>|2>> - i|?>> - |7>|2>> - i|?>> - |7>|2>> - i|?>> - i|2>> - i|?>> - g|1>> - |5>|?>> - |5>|?>> - |5>|?>> - h|1>> - - - -<\auxiliary> - <\collection> - <\associate|toc> - |1Message - |.>>>>|> - > - - |2Displaying the message - |.>>>>|> - > - - |3The main function - |.>>>>|> - > - - |4Header files - |.>>>>|> - > - - |5Updating the Document - |.>>>>|> - > - - - \ No newline at end of file + + +> + +<\body> + X>>> + + ||<\author-address> + Using and Fangle + >> + + <\abstract> + Literate Programming will not be explained here but it will be shown as a + way narrate program development showing the progression of ideas a is + natural for humans to understand, leaving the generation of programs from + those ideas to the machine. + + is used as the editor and <\footnote> + http://new.fangled.org + as the extraction tool. + + + Here we will explain the popular written in . + + + + Here is the message that we wish to give to world: + + + + Because we did not press enter in the literate programming environment, + this line is not prefixed in the document tree with an + item\> tag and so has no line number displayed and + is not a line but a line-fragment. + + <\note> + The header contains the chunk name as well as the language + of the listing which is . The beginning of the header gives the + id to this of code + which suggests to the reader that it is the first chunk on page + . <\footnote> + The label and hyperlink were generated with + the document tag chunk-reference\|message\|1\> + to generate a link to the first chunklet of the chunk named + . + + + + + + We have a few choices available. The message can be output with + , like this: + + <\nf-chunk|message-printf> + printf("\\n"); + + + or even with : + + <\nf-chunk|message-puts> + puts("\\n"); + <|nf-chunk> + cpp + + + But, we prefer which is more traditional. + + <\note> + These last two chunks have a different letter for the chunk reference + even though they may be on the same page. + + + <\note> + They also contain a line number, because they are intended to be a full + line of text. + + + + + <\note> + If a code chunk is split across two pages, as this next code chunk is, + the code chunk header is repeated in the page header of the last page. + The technique used is to put a at the begining of + the chunk and also at the end of the chunk. We take the + of each label, and if they are not on the same page, then at the end of + the chunk we set the page header to be the same as the chunk header.\ + + + We have to enclose this line in the standard C function, like + this: + + <\nf-chunk|main> + int main(int argc, char** argv) { + + \ + + \ return 0; + + } + + + The statement lets the operating system know that the + function completed successfully which is a bit of a presumption as + we don't check if is successful. + + <\note> + Note the statement defined in + has been included in + . + + + <\note> + The line numbering starts counting again from 1 for each named chunk. + + + + + By convention, with and , a chunk whose name begins + with a is considered to be a file suitable for automatic + extraction; so we will define out main chunk to be + + + + + On my system, both and both require the + header ; so this line becomes the first line of our file.\ + + <\nf-chunk|./hello-world.c> + #include stdout.h + > + + <\note> + The header contains a link to chunk + which is the next chunklet of this named chunk. + + + + + The include statement is followed by our main function that we defined in + . + + <\nf-chunk|./hello-world.c> + + + + <\note> + This time the header also contains a link to chunk + which is the previous chunklet of this + named chunk.\ + + + + + And a final good-bye comment. + + <\nf-chunk|./hello-world.c> + /* thats the end, folks */ + + + <\note> + Like the first chunks we looked at, there are no further chunklets with + the same name and so there is no link to the next chunklet shown, + although there is a link to the previous chunklet. + + + + + Because of the amount of page-referencing going on to calculate the + chunklet references, it can sometimes require the document to be updated + three or more times to fix the links and references. + + <\enumerate> + The first time, a chunk has to discover which page it is one. + + The second time all the chunks can be given the correct id based on + the page. + + The third time, all references to a chunk can be updated to the + correct id. + + A forth and additional times may be required if the page-breaking + was changed as a result of a change in label size although this + is only likely to occur if a reference occured in the text of the + document for the references in the header have enough space so as not to + affect layout. + + + + + The file can be extracted directly with: + + <\verbatim> + texmacs -s -c hello-world.tm hello-world.txt -q && + + fangle -R./hello-world.c hello-world.txt \ hello-world.c + + + Although this is a little verbose, it shows how things work. There is a + Makefile.inc project that allows you to do all that sort of thing + automatically. + + +<\initial> + <\collection> + + + + + + + + + +<\references> + + +<\auxiliary> + \ No newline at end of file -- 2.11.4.GIT