.TH sweb 1

.SH NAME
sweb \- Simple support for literate programming in Lisp.
.SH SYNOPSIS
.B sweb
[-stuvwxh]|[-ss] [input_file [output_file]]
.SH DESCRIPTION
A SchemeWEB2 file is a Lisp source file which contains code sections
and comment sections, but each section is identified in a novel way.
A code section begins with a line whose first character is a left
parenthesis.
It continues until a line is found which contains the
parenthesis that matches the one which started the code section.
The remaining lines of text in the source file are treated as comments.

Several operations involving SchemeWEB2 files are provided by the
.B sweb
program.
.PP
The 
.B \-t
option translates a SchemeWEB2 file into a standard Lisp file.
It simply adds an initial semicolon to comment lines that lack them, and
passes code sections through unchanged.
This process is called tangling the SchemeWEB2 file.
.PP
The 
.B \-w
option translates a SchemeWEB2 file into a LaTeX source file.
Text is added to code sections so that LaTeX will print the code verbatim.
Comment sections are passed through unchanged except that if the first
character of a line is a semicolon, it is excised.
This makes it possible to process a SchemeWEB2 file which has been tangled.
This process is called weaving the SchemeWEB2 file.
This is the default action of
.B sweb.
Inside code, the comments, as in
.P
   (define (foo x y) ; Returns ${x + y \\over 2}$
     (/ (+ x y) 2))
.P
are threated as LaTeX source code, and will be properly formated when
you call LaTeX on the weaved file.
The exception to this is that any '#' character inside code section
will be backslashify-ed (transformed into '\\#'). This makes it
possible to write things like
.P
   (define (false) #f) ; Allways returns #f

   (define debug #t)
   ;(define debug #f)
.P
without having to care about the '#'. You still can use the '#' as a
special character inside comment section.
.P 
The '%' inside comments, like in
.P
   (define foo bar) ; % This is a comment \\anything $
.P
Are threated as real comments, e.g. any text between it and the end of
line is ignored. This is the best way for commenting portions of
unused code.
.PP
The 
.B \-x
option weaves a SchemeWEB2 file as above, except the LaTeX source
produced inhibits page breaks in code sections.
.PP
The 
.B \-u
option translates a Lisp file which has been produced from a
SchemeWEB2 file back into a SchemeWEB2 file.
It simply removes the first semicolon in every line that starts with
one as its first character.
This process is called untangling a
.B sweb
produced Lisp file.
.PP
The
.B \-s
option tangles a SchemeWEB2 file and strips all comments from the file.
.PP
The
.B \-ss
option tangles a SchemeWEB2 as with
.B \-s
but the comments inside a code section are kept. This is usefull if your scheme code has to be read, and if
you think the comment section is too large.
.PP
The
.B \-v
option prints version information.
.PP
A SchemeWEB2 file can be stored and distributed as a standard Lisp
file by tangling the SchemeWEB2 file.  
For the purposes of editing comments, the SchemeWEB2 file can be
recovered by untangling the Lisp file.  
LaTeX documentation can be generated from both the Lisp file or the
SchemeWEB2 file.
.PP
If you use Emacs as a text editor, I suggest that you add the
following lines to your 
.B .emacs
.P
  (add-to-list 'auto-mode-alist 
               (cons "\\.sw\\'" 'scheme-mode))
  (add-hook 'latex-mode-hook 
            '(lambda () (local-set-key [f12] 'scheme-mode)))
  (add-hook 'scheme-mode-hook 
            '(lambda () (local-set-key [f12] 'latex-mode)))
.P
Then, you will automatically load the scheme mode on SchemeWEB2 files
(*.sw). You will swap from scheme mode to latex mode by pressing f12.
.PP
SchemeWEB2 was originally developed for the Scheme dialect of Lisp;
however, it became obvious that no changes were required to support
most other dialects.  
SchemeWEB2's name reflects its heritage.

.SH SAMPLE OF MAKEFILE FOR SchemeWEB2

You will find with the sources of SchemeWEB2 a file called sweb.make.

This is a sample Makefile for use with SchemeWEB(2)
To use it, create a new file called Makefile in the directory
containing the SchemeWEB files, whose name should end by '.sw'
inside this file, add the line

TEXFILE = XXX.tex [ YYY.tex ZZZ.tex ... ]

Where XXX.tex YYY.tex and ZZZ.tex are the name of your main tex
files (those you which to compile with 'LaTeX XXX.tex')

then, add the line

include <prefix-dir>/sweb.make

where <prefix-dir> is the name of the directory containing the
present file. You can now compile with 'make', 'make dvi', 
'make ps', 'make html', or clean the directory with 'make clean' (but be
carefull with this option !)


.SH CHANGES FROM SchemeWEB TO SchemeWEB2

The
.B \-ss
option has been added.
.P
A comment has been added to the begining of any generated files to
prevent accidental modification of them.
.P
The '#' characters are backslashifyed when weaving comments inside
code section.
.P
The end of line inside strings are now correctly managed while
weaving.
.P
The '%' characters inside comments are considered as LaTeX comments.
.P
The
.B \-h
option has been added to show the help message.
.P
A sample Makefile is provided to make it easy to keep 
.B .scm 
and 
.B .tex
files up to date, and generate dvi, ps, and html documentation.
.P
The error messages have been reformated for compatibility with Emacs
compilation mode. (<file name>:<line nb>: ...)
.P
The program has been renamed to keep the old version availlable in
case people prefer it.


.SH BUG REPORT and COMMENTS

If you have any comments about this new version of SchemeWEB, please
contact me at matthieu.moy@ensimag.imag.fr.