www/index.html

   1 <!--#if expr="! ${template}" --><!--#include virtual="/fangle/template.shtml" --><!--#else -->
   2 <h2>Introduction</h2>
   3
   4 <p><em>Fangle</em> is a <a href="docs/literate/literate.html">literate
   5 programming</a> technique for <a href="http://www.texmacs.org">TeXmacs</a>, <a
   6 href="http://www.lyx.org">Lyx</a> and Latex inspired by <a
   7 href="http://www.eecs.harvard.edu/nr/noweb/dist">notangle</a>. </p>
   8
   9 <p>Literate programming means that instead of commenting your code (or feeling
  10 guilty for not doing so) you code your comments. Or rather you write a book about
  11 the problem your program solves, and in the narrative of the book you introduce
  12 aspects of code that solve the problem. As you do this you slowly reveal the
  13 solution - a well documented solution!</p>
  14
  15 <p>Literate programming helps one to write good code, because if one can't
  16 write a good justification or explanation for one's code, it makes one think
  17 again and write something that one can explain.</p>
  18
  19 <p>See this <a href="examples/hello-world.pdf">hello-world example</a> in PDF
  20 rendering. The narrative explains hello-world as well as TeXmacs literate programming.</p>
  21
  22 <h2>Fangle comes in two parts.</h2>
  23
  24 <p>The <strong>weave</strong> part produces the formatted document is
  25 implemented entirely in TeXmacs macros (for TeXmacs) and Latex macros for
  26 Lyx.</p>
  27
  28 <p>The <strong>tangle</strong> part generates the source code is implemented in
  29 awk for portability across most unix-like or windows systems.</p>
  30
  31 <p>Naturally, fangle is written using literate programming techniques, using
  32 itself, and so the source is also the <a
  33 href="docs/fangle.e/fangle.html">documentation</a>.</p>
  34
  35 <p>The source was written using the <a href="http://www.lyx.org/">Lyx</a>
  36 document editor (an excellent front end to Latex) and then converted for
  37 <a href="http://www.texmacs.org">TeXmacs</a> which has a better WYSIWYG macro rendering system. TeXmacs and Lyx are
  38 not required, but fangle provides formatting support for TeXmacs and Lyx.</p>
  39
  40 <h2>Features</h2>
  41 <ul>
  42   <li>Generics / macros. Fangle macros accept parameters, so generic algorithms
  43     can be expressed, and then invoked in the code using any particular types
  44     or parameters - like C macros, but with all the literate goodness and
  45     without all the backslash ugliness.</li>
  46   <li>Latex lstlistings used for code chunk formatting, with automatic markup
  47     for dozens of language types.</li>
  48   <li>Automatic escaping and quoting. You can include a shell-script chunk in a
  49     makefile and have all the $ escaped to $$ automatically in the extracted
  50     source. You can include a text file in a // comment or a " string and have
  51     the appropriate escaping done automatically!</li>
  52   <li>Never worry about code documentation again!</li>
  53   <li>Fangle has a makefile stub, Makefile.inc that will automatically extract
  54     all project sources, making fangle easy to integrate with standard
  55     Makefileprojects (including automake and autoconf). </li>
  56 </ul>
  57