User:Lzheng5/sandbox

Original author(s)	Pretson Briggs
Operating system	Cross-platform
Type	Literate programming
Website	http://nuweb.sourceforge.net

nuweb is a literate programming tool, created in 1989 by Preston Briggs. It is designed to be simple, fast and configurable to generate more than one output files from a single nuweb file. This is useful when constructing programs in more than one programming language with great documentation in TeX. It works with any programming language hence does not support pretty printing. It gives the programmer simplicity, flexibility, and complete control of the code layout.

The nuweb source file with extension .w is given as input to the nuweb tool. The .w file is comprised of i) LaTeX source code, ii) nuweb commands, and iii) any arbitrary programming language source code. The nuweb tool outputs a .tex file and all source files in other languages specified by the @o nuweb command.

Nuweb also supports generating HTML. If the target is .html file, then according to the nuweb manual the file extension should be changed to be .hw, and include html as the document style option, then use LaTeX2HTML tool to produce the resulting .html file^[1].

History[edit]

WEB was first designed by Donald Knuth to support literate programming^[2]. The idea of literate programming as described by Knuth is to “let us concentrate on explaining to human beings what we want a computer to do, instead of instructing a computer what to do.”^[2]. Thus it frees programming language structure from the traditional [[top-down and bottom-up programming style into a more flexible style specialized for human interpretation. Knuth created the WEB tool by combining the Pascal language and TeX. It had two major components namely the TANGLE tool, which produced compilable pascal code and the WEAVE tool, which produced nicely-formatted TeX file. Extending his own work, Knuth went on to create CWEB which has the same functionality as WEB but works with C and TeX instead of Pascal and TeX^[3].

noweb was the first literate programming tool that was language independent. Nuweb is highly inspired from noweb in terms of features and names^[1]. It does not have the extensibility of noweb, but it can use the listings package of LaTeX to provide pretty-printing and the hyperref package to provide hyperlinks in PDF output^[3]. noweb separates TANGLE and WEAVE, whereas nuweb combines those two together, bringing the users more simplicity.^[3]

Syntax[edit]

All the nuweb commands begin with ‘at sign’(@)^[1].
There are three major nuweb commands described in the nuweb manual^[1].

@o file-name flags scrap

Output a file. The file name is terminated by whitespace.
@d fragment-name scrap

Define a fragment. The fragment name is terminated by a return or the beginning of a scrap.
@q fragment-name scrap

Define a fragment. The fragment name is terminated by a return or the beginning of a scrap. This a quoted fragment.

Build[edit]

Binary

Arch Linux

Run yaort -S nuweb
OS X

With MacPorts run sudo port install nuweb
Note that the installed version is 1.0b1, whereas the current version is 1.58. And version 1.0b1 is not fully compatible with the user manual, i.e. nuweb commands such as @s and @q will not work with the 1.01b version.
General Linux
1. Download nuweb-*.tar.gz from the official repository
2. make nuweb
  On OS X 10.10.4 this might not be successful see Troubleshooting 1
3. sudo cp nuweb /usr/bin/ # or some other directory

Documentation

After building the binary, the following typing out the following commands in the terminal will produce the official nuweb document.
```
./nuweb nuweb.w
latex nuweb
bibtex nuweb
latex nuweb
latex nuweb
dvipdf nuweb
```

Examples[edit]

qsort in C++[edit]

\section{quick\_sort}
\subsection{Plan of the Program}
This program will accept a pointer to a generic array, a lower index, and a higher index as inputs, where the $<$ operator is defined for the element of the generic vector. Since it will directly mutate the array, nothing needs to be returned.

@o quick_sort.hpp -it @{
@<include header files@>
@<quick sort definition@>
@} 

\subsection{Implementation}
Let's begin by including all the header files needed.

@d include header files @{
#include <algorithm>
@}

Next let's work on the quick\_sort definition. 

@d quick sort definition @{
template<class T>
void quick_sort(T* unsorted, int low, int high)
{
   if (low < high)
   {
        @<choose a pivot@>
        @<partition unsorted@>
        @<quick sort left branch@>
        @<quick sort right branch@>
   }
}
@| unsorted low high@} 

Let's choose the middle point as the pivot.

@d choose a pivot @{
   int pivot = (low + high)/2;
@}

To partition we can use Lomuto's partitioning algorithm.

@d partition unsorted @{
   std::swap(unsorted[low], unsorted[pivot]);
   pivot = low; 
   for (int i = pivot + 1; i <= high; i++)
     if (unsorted[i] < unsorted[low])
       std::swap(unsorted[i], unsorted[++pivot]);
   std::swap(unsorted[low], unsorted[pivot]);
@}
Since pivot is already sorted, then we just need to sort left and right branches.
@d quick sort left branch @{
   quick_sort(unsorted, low, pivot - 1);
@}
@d quick sort right branch @{
   quick_sort(unsorted, pivot + 1, high);
@}

After running nuweb quick_sort.w, a quick_sort.tex file and the following quick_sort.hpp file will be generated.

#include <algorithm>

template<class T>
void quick_sort(T* unsorted, int low, int high)
{
   if (low < high)
   {
    int pivot = (low + high)/2;

    std::swap(unsorted[low], unsorted[pivot]);
    pivot = low; 
    for (int i = pivot + 1; i <= high; i++)
        if (unsorted[i] < unsorted[low])
            std::swap(unsorted[i], unsorted[++pivot]);
    std::swap(unsorted[low], unsorted[pivot]);
    quick_sort(unsorted, low, pivot - 1);
    quick_sort(unsorted, pivot + 1, high);
   }
}

Troubleshooting[edit]

On OS X 10.10.4

An error [error: non-void function 'write_scraps' should return a value [-Wreturn-type]] might be produced because the write_scrap function in scraps.c does not return a value. On OS X10.10.4 gcc will produce an error instead of a warning.

To resolve it go to scraps.c and change return; to return 0;.

External Links[edit]

Notes[edit]

^ ^a ^b ^c ^d "Nuweb" (PDF).
^ ^a ^b "Literate Programming". www.literateprogramming.com. Retrieved 2016-09-11.
^ ^a ^b ^c "Literate programming". Wikipedia, the free encyclopedia. 2016-08-19.

[:1-1] "Nuweb" (PDF).

[:2-2] "Literate Programming". www.literateprogramming.com. Retrieved 2016-09-11.

[:0-3] "Literate programming". Wikipedia, the free encyclopedia. 2016-08-19.

[1]

[2]

[3]