summaryrefslogtreecommitdiff
path: root/web/schemeweb2/sweb.1
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/schemeweb2/sweb.1
Initial commit
Diffstat (limited to 'web/schemeweb2/sweb.1')
-rw-r--r--web/schemeweb2/sweb.1186
1 files changed, 186 insertions, 0 deletions
diff --git a/web/schemeweb2/sweb.1 b/web/schemeweb2/sweb.1
new file mode 100644
index 0000000000..81c160c0b6
--- /dev/null
+++ b/web/schemeweb2/sweb.1
@@ -0,0 +1,186 @@
+.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.
+
+
+
+