Directory web/schemeweb

$Id: README,v 2.1 94/07/22 07:00:10 ramsdell Exp $

SchemeWEB---Simple support for literate programming in Lisp.

SchemeWEB is a Unix filter that allows you to generate both Lisp and
LaTeX code from one source file.  The generated LaTeX code formats
Lisp programs in typewriter font obeying the spacing in the source
file.  Comments can include arbitrary LaTeX commands.  SchemeWEB was
originally developed for the Scheme dialect of Lisp, but it can easily
be used with most other dialects.

Version 2.1 implements several improvements over the version 1.2 which
was released in 1990.

* The LaTeX source generated from a SchemeWEB file no longer requires
the use of a style option, such as the astyped option required by the
previous version.  The output is similar to that produced by c2latex.

* By default, Lisp source generated from a SchemeWEB file includes all
comments.  As a result, the filter can translate the Lisp source
generated from a SchemeWEB file directly into LaTeX source.

* The filter can translate the Lisp source generated from a SchemeWEB
file into the original SchemeWEB file.

As a result of these changes, a SchemeWEB file can be stored and
distributed as a standard Lisp file by tangling the SchemeWEB file.
For the purposes of editing comments, the SchemeWEB file can be
recovered by untangling the Lisp file.  LaTeX documentation can be
generated from both the Lisp file or the SchemeWEB file.

Version 2.1 patches version 2.0 so it now correctly formats strings
which span more than one line of text.

Installation:

1) Create the executable by typing:

	make

2) Install the executable and the manual page by typing:

	make install

By default the makefile will install the executable in $(prefix)/bin
and the manual page in $(prefix)/man/man1, where prefix=/usr/local.
You can change the prefix by typing:

	make prefix=<Your path> install

You can also change the installation targets by editing the makefile.

3) You can modify the reader used by your Lisp system's standard LOAD
so that it can read SchemeWEB files directly.  To make this change,
follow the model given in "reader.sw", a reader of SchemeWEB source
for the R4RS dialect of Scheme.

A formatted version of the manual page follows.

-----------------------------------------------------------------

sweb(1)                  USER COMMANDS                    sweb(1)



NAME
     sweb - Simple support for literate programming in Lisp.

SYNOPSIS
     sweb [-stuvwx] [input_file [output_file]]

DESCRIPTION
     A SchemeWEB file is a Lisp source file which  contains  code
     sections  and  comment sections, but each section is identi-
     fied 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 remain-
     ing lines of text in the source file  are  treated  as  com-
     ments.

     Several operations involving SchemeWEB files are provided by
     the sweb program.

     The -t option translates a SchemeWEB 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 SchemeWEB
     file.

     The -w option translates  a  SchemeWEB  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  SchemeWEB file which has been tangled.  This
     process is called weaving the SchemeWEB file.  This  is  the
     default action of sweb.

     The -x option weaves a SchemeWEB file as above,  except  the
     LaTeX source produced inhibits page breaks in code sections.

     The -u option translates a Lisp file which has been produced
     from a SchemeWEB file back into a SchemeWEB file.  It simply
     removes the first semicolon in every line that  starts  with
     one  as  its first character.  This process is called untan-
     gling a sweb produced Lisp file.

     The -s option tangles a SchemeWEB file and strips  all  com-
     ments from the file.

     The -v option prints version information.

     A SchemeWEB file can be stored and distributed as a standard
     Lisp  file by tangling the SchemeWEB file.  For the purposes
     of editing comments, the SchemeWEB file can be recovered  by
     untangling  the  Lisp  file.   LaTeX  documentation  can  be
     generated from both the Lisp file or the SchemeWEB file.

     SchemeWEB was originally developed for the Scheme dialect of
     Lisp;  however,  it  became  obvious  that  no  changes were
     required to support most other dialects.   SchemeWEB's  name
     reflects its heritage.