WIP
[newfangle.git] / README
blobfe5d0e264b31d7e2c701b3a215ff1601f81c3bf5
1 License
3 The majority of newfangle is licensed under the GPL3 or later.
5 Specifically:
7 1. www/docs/literate/*
8    (C) Copyright various Wikipedia Contributors
9    is licensed under the Creative Commons 
10    Attribution-ShareAlike 3.0 Unported License
11    See file: COPYING.cc-by-sa 
13 2. www/index.html
14    Design is based on the Git Web interfaces
15    (C) Copyright 2005-2006 Kay Sievers
16    Text (C) Copyright 2010 Sam Liddicott
17    licensed under the GPL2
19 3. www/docs/newfangle/*
20    newfangle*
21    (C) Copyright 2010 Sam Liddicott <sam@liddicott.com>
22    licensed under the GPL3 or later
23    See file: COPYING
25 Newfangle Literate Programming
27 Summary
29 Newfangle is a literate programming technique for Lyx (or Latex) inspired by notangle.
31 It comes in two parts. The weave part that produces the formatted document is implemented entirely in Latex, and the tangle that generates the source code is implemented in awk for portability.
33 Naturally, newfangle is written using literate programming techniques, using itself, and so the source is also the documentation.
35 The source is written using the Lyx document editor - an excellent front end to Latex. Lyx is not required, but newfangle provides formatting support for Lyx.
37 Literate programming makes you write good code, because if you can't write a good justification or explanation for your code, it makes you think again and write something that you can explain.
38 Features
40     * Generics / macros. Newfangle macros accept parameters, so generic algorithms can be expressed, and then invoked in the code using any particular types or parameters - like C macros, but with all the literate goodness and without all the backslash ugliness.
41     * Latex lstlistings used for code chunk formatting, with automatic markup for dozens of language types.
42     * Automatic escaping and quoting. You can include a shell-script chunk in a makefile and have all the $ escaped to $$ automatically in the extracted source. You can include a text file in a // comment or a " string and have the appropriate escaping done automatically!
43     * Never worry about code documentation again!
44     * Newfangle has a makefile stub, Makefile.inc that will automatically extract all project sources, making newfangle easy to integrate with standard Makefileprojects (including automake and autoconf).