examples/hello-world.tm

   1 <TeXmacs|1.0.7.10>
   2
   3 <style|<tuple|article|fangle>>
   4
   5 <\body>
   6   <hide-preamble|<assign|LyX|<macro|L<space|-0.1667em><move|Y|0fn|-0.25em><space|-0.125em>X>>>
   7
   8   <doc-data|<doc-title|Sample Literate Programming>|<doc-author-data|<author-name|Sam
   9   Liddicott>|<\author-address>
  10     Using <TeXmacs> and Fangle
  11   </author-address>>>
  12
  13   <\abstract>
  14     Literate Programming will not be explained here but it will be shown as a
  15     way narrate program development showing the progression of ideas a is
  16     natural for humans to understand, leaving the generation of programs from
  17     those ideas to the machine.
  18
  19     <TeXmacs> is used as the editor and <name|Fangle><\footnote>
  20       http://new.fangled.org
  21     </footnote> as the extraction tool.
  22   </abstract>
  23
  24   Here we will explain the popular <em|hello world> written in <name|C>.
  25
  26   <subsubsection|Message>
  27
  28   Here is the message that we wish to give to world:
  29
  30   <nf-chunk|message|Hello World!|txt|>
  31
  32   Because we did not press enter in the literate programming environment,
  33   this line is not prefixed in the document tree with an
  34   <verbatim|\<less\>item\<gtr\>> tag and so has no line number displayed and
  35   is not a line but a line-fragment.
  36
  37   <\note>
  38     The header contains the chunk name <em|message> as well as the language
  39     of the listing which is <em|txt>. The beginning of the header gives the
  40     id to this <em|chunk> of code <emdash> <chunk-reference|message|1>
  41     <emdash> which suggests to the reader that it is the first chunk on page
  42     <chunk-page-reference|message|1>. <\footnote>
  43       The label and hyperlink <chunk-reference|message|1> were generated with
  44       the <TeXmacs> document tag <verbatim|\<less\>chunk-reference\|message\|1\<gtr\>>
  45       to generate a link to the first chunklet of the chunk named
  46       <em|message>.
  47     </footnote>
  48   </note>
  49
  50   <subsubsection|Displaying the message>
  51
  52   We have a few choices available. The message can be output with
  53   <verbatim|printf>, like this:
  54
  55   <\nf-chunk|message-printf>
  56     <item>printf("<nf-ref|message>\\n");
  57   </nf-chunk|cpp|>
  58
  59   or even with <verbatim|puts>:
  60
  61   <\nf-chunk|message-puts>
  62     <item>puts("<nf-ref|message>\\n");
  63   <|nf-chunk>
  64     cpp
  65   </nf-chunk>
  66
  67   But, we prefer <verbatim|printf> which is more traditional.
  68
  69   <\note>
  70     These last two chunks have a different letter for the chunk reference
  71     even though they may be on the same page.
  72   </note>
  73
  74   <\note>
  75     They also contain a line number, because they are intended to be a full
  76     line of text.
  77   </note>
  78
  79   <subsubsection|The main function>
  80
  81   <\note>
  82     If a code chunk is split across two pages, as this next code chunk is,
  83     the code chunk header is repeated in the page header of the last page.
  84     The technique used is to put a <TeXmacs> <em|label> at the begining of
  85     the chunk and also at the end of the chunk. We take the <em|pagerefpage>
  86     of each label, and if they are not on the same page, then at the end of
  87     the chunk we set the page header to be the same as the chunk header.\
  88   </note>
  89
  90   We have to enclose this line in the standard C <em|main> function, like
  91   this:
  92
  93   <\nf-chunk|main>
  94     <item>int main(int argc, char** argv) {
  95
  96     <item> \ <label|printfs><nf-ref|message-printf>
  97
  98     <item> \ return 0;
  99
 100     <item>}
 101   </nf-chunk|cpp>
 102
 103   The statement <verbatim|return 0;> lets the operating system know that the
 104   function completed successfully <emdash> which is a bit of a presumption as
 105   we don't check if <verbatim|printf> is successful.
 106
 107   <\note>
 108     Note the <verbatim|printf> statement defined in
 109     <chunk-reference|message-printf|1> has been included in
 110     <reference|printfs>.
 111   </note>
 112
 113   <\note>
 114     The line numbering starts counting again from 1 for each named chunk.
 115   </note>
 116
 117   <subsubsection|Composing the file>
 118
 119   By convention, with <TeXmacs> and <name|Fangle>, a chunk whose name begins
 120   with a <verbatim|./> is considered to be a file suitable for automatic
 121   extraction; so we will define out main chunk to be
 122   <verbatim|./hello-world.c>
 123
 124   <paragraph|Header files>
 125
 126   On my system, both <verbatim|printf> and <verbatim|puts> both require the
 127   header <verbatim|stdio.h>; so this line becomes the first line of our file.\
 128
 129   <\nf-chunk|./hello-world.c>
 130     <item>#include stdout.h
 131   </nf-chunk|cpp|<tuple|>>
 132
 133   <\note>
 134     The header contains a link to chunk <chunk-reference|hello-world.c|2>
 135     which is the next chunklet of this named chunk.
 136   </note>
 137
 138   <subparagraph|Main Body>
 139
 140   The include statement is followed by our main function that we defined in
 141   <chunk-reference|main|1>.
 142
 143   <\nf-chunk|./hello-world.c>
 144     <item><nf-ref|main>
 145   </nf-chunk|cpp>
 146
 147   <\note>
 148     This time the header also contains a link to chunk
 149     <chunk-reference|hello-world.c|1> which is the previous chunklet of this
 150     named chunk.\
 151   </note>
 152
 153   <subparagraph|Closing remarks>
 154
 155   And a final good-bye comment.
 156
 157   <\nf-chunk|./hello-world.c>
 158     <item>/* thats the end, folks */
 159   </nf-chunk|cpp>
 160
 161   <\note>
 162     Like the first chunks we looked at, there are no further chunklets with
 163     the same name and so there is no link to the next chunklet shown,
 164     although there is a link to the previous chunklet.
 165   </note>
 166
 167   <subsubsection|Updating the Document>
 168
 169   Because of the amount of page-referencing going on to calculate the
 170   chunklet references, it can sometimes require the document to be updated
 171   three or more times to fix the links and references.
 172
 173   <\enumerate>
 174     <item>The first time, a chunk has to discover which page it is one.
 175
 176     <item>The second time all the chunks can be given the correct id based on
 177     the page.
 178
 179     <item>The third time, all references to a chunk can be updated to the
 180     correct id.
 181
 182     <item>A forth and additional times may be required if the page-breaking
 183     was changed as a result of a change in label size <emdash> although this
 184     is only likely to occur if a reference occured in the text of the
 185     document for the references in the header have enough space so as not to
 186     affect layout.
 187   </enumerate>
 188
 189   <subsubsection|Extracting the source>
 190
 191   The file <verbatim|./hello-world.c> can be extracted directly with:
 192
 193   <\verbatim>
 194     texmacs -s -c hello-world.tm hello-world.txt -q &&
 195
 196     fangle -R./hello-world.c hello-world.txt \<gtr\> hello-world.c
 197   </verbatim>
 198
 199   Although this is a little verbose, it shows how things work. There is a
 200   Makefile.inc project that allows you to do all that sort of thing
 201   automatically.
 202 </body>
 203
 204 <\initial>
 205   <\collection>
 206     <associate|info-flag|detailed>
 207     <associate|page-medium|paper>
 208     <associate|page-screen-margin|false>
 209     <associate|page-show-hf|true>
 210     <associate|preamble|false>
 211     <associate|src-style|scheme>
 212   </collection>
 213 </initial>
 214
 215 <\references>
 216 </references>
 217
 218 <\auxiliary>
 219 </auxiliary>