diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/schemeweb2/sweb.1 |
Initial commit
Diffstat (limited to 'web/schemeweb2/sweb.1')
-rw-r--r-- | web/schemeweb2/sweb.1 | 186 |
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. + + + + |