├── .gitignore ├── CHECKLIST ├── ChangeLog ├── Makefile ├── README ├── TODO ├── bootstrap ├── bootstrap.ss ├── chezweb.mp ├── chezweb.w ├── chezwebmac.tex ├── config.mk.template ├── contrib └── iu-chezweb ├── doc └── cwebman.tex ├── installit ├── tangleit ├── weaveit └── www ├── chezweb_screen.css └── index.xhtml /.gitignore: -------------------------------------------------------------------------------- 1 | config.mk 2 | cheztangle 3 | chezweave 4 | *.idx 5 | *.log 6 | *.mpx 7 | *.pdf 8 | *.scn 9 | *.so 10 | *.toc 11 | chezweb.tex 12 | chezweb.[1-9] 13 | *.ss 14 | !bootstrap.ss 15 | runtime.sls 16 | -------------------------------------------------------------------------------- /CHECKLIST: -------------------------------------------------------------------------------- 1 | Checklist for a new release: 2 | 3 | [ ] All developer documentation current and double-checked for accuracy 4 | [ ] User documentation updated to reflect changes in user interface 5 | [ ] Passes test suite (not implemented yet) 6 | [ ] Known bugs documented 7 | [ ] All issues fixed by this release updated on Tracker 8 | [ ] Updated Version numbering in and out of main document 9 | [ ] Build system tested on Chez and Petite 10 | [ ] Updated ChangeLog 11 | [ ] Binaries released 12 | [ ] Website updated 13 | [ ] Announce to lists and newsgroups 14 | [ ] Post on Blog 15 | -------------------------------------------------------------------------------- /ChangeLog: -------------------------------------------------------------------------------- 1 | Changs from 1.3.2 to 2.0: 2 | 3 | Change versioning scheme to only two digits. 4 | 5 | Improved README and documentation, though user guide is not quite there. 6 | 7 | Completely new underlying infrastructure and interface, which operates 8 | mostly in the same way that CWEB does, with two offline programs 9 | cheztangle and chezweave. 10 | 11 | Output now looks like CWEB because it is based off of the cwebman.tex 12 | file 13 | 14 | Improved support for Petite 15 | 16 | Greatly improved build system 17 | 18 | A copy of the CWEB manual is now included in place of the old and 19 | incomplete guide; this will be expanded and changed in future releases 20 | to reflect unique ChezWEB-isms. 21 | 22 | We have improved the underlying pretty printer in preparation for more 23 | sophisticated pretty printing. 24 | 25 | Improved reliability of the output 26 | 27 | Improved meta data tracking in captures and exports 28 | 29 | Improved formatting of captures and exports 30 | 31 | The programs chezweave and cheztangle now produce more helpful output 32 | to track down bugs and problems. 33 | 34 | Empty section bodies are allowed now. 35 | 36 | Fully new and mostly compatible CWEB syntax that is not nested 37 | s-expressions 38 | 39 | Support for including files 40 | 41 | Indexing support with a section and keyword index. 42 | 43 | Improved automatic table of contents 44 | 45 | Section heading levels with nesting. 46 | 47 | Implicit and explicit indexing support 48 | 49 | Support for concatenation of sections 50 | 51 | Section names do not need to have their captures threaded explicitely 52 | anymore 53 | 54 | Support for automatic cross-referencing of section names and numbers 55 | 56 | ChezWEB is now written in ChezWEB and can weave/tangle itself 57 | 58 | This is a complete rewrite of the system 59 | 60 | Changes from 1.3.1 to 1.3.2: 61 | 62 | Fix the @> handling of ellipses in the case where we return a value 63 | instead of export definitions. 64 | 65 | Changes from 1.3 to 1.3.1: 66 | 67 | Make @e a definition rather than a value form. 68 | 69 | Make it possible to access the parameters of ChezWEAVE in @e. 70 | 71 | Changes from 1.2.3 to 1.3: 72 | 73 | Make the system compatible with Chez Scheme 8.2, 8.1, and 8.0. 74 | 75 | Miscellaneous Typo fixes. 76 | 77 | Add an evaluator form to evaluate code during weaving for their 78 | side-effects. Useful for setting pretty printer settings. 79 | 80 | Add scripts to help those who might want to use the source version 81 | of ChezWEB with Petite, without the compiler. 82 | 83 | Adjust the behavior of named chunks to enable macros with ellipses 84 | to be defined without needing to be wrapped in a (... ---) form 85 | so long as no ellipses appear in the capture clause. 86 | 87 | The guide has been updated to reflect the changes above with some 88 | examples and more exposition. 89 | 90 | Changes from 1.2.2 to 1.2.3: 91 | 92 | Fix a bug where ‘quote’ was not handled in the right way in 93 | ChezWEAVE. 94 | 95 | Changes from 1.2.1 to 1.2.2: 96 | 97 | Upgrade the system to use the latest Chez Scheme version 8.1. 98 | 99 | Changes from 1.2 to 1.2.1: 100 | 101 | Fix a bug in the order of exact? and integer? checks in ChezWEAVE. 102 | 103 | Changes from 1.1 to 1.2: 104 | 105 | Enable environment variables CHEZWEBMAXELEMS and CHEZWEBLISTCOLUMNS 106 | to control the limits of the simple elemtsn and number of columns 107 | that are generate for output in ChezWEB. This tells the weave 108 | program when it should go from simple listings to columns of 109 | listings for exports and such. 110 | 111 | Various reliability improvements have been introduced, including 112 | fixes to the TeX file and the way that we output the TeX, which 113 | enables a greater range of characters in the source code. 114 | 115 | @<< and @chunk-ref/thread have been fixed so that threading will 116 | occur even in cases where there is a bunch of nesting. 117 | 118 | A manual has been created for ChezWEB, and we now ship with the TeX 119 | file available for users. 120 | 121 | Changes from 1.0 to 1.1: 122 | 123 | You can now use long names for the control codes rather than just the 124 | short ones: 125 | 126 | @ @section 127 | @* @section/header 128 | @< @chunk-ref 129 | @<< @chunk-ref/thread 130 | @> @define-chunk 131 | @c @code 132 | @l @library 133 | 134 | The makefile package target now overwrites any tarballs that already 135 | exist. 136 | 137 | The Makefile now does a better job of cleaning the directory. 138 | 139 | The makefile is now included in binary packages. 140 | 141 | The README file is now included in binary packages and has been 142 | altered some. 143 | 144 | The chezwebmac.tex file is now included in binary packages. 145 | 146 | Greatly improved control over how and where exports are visible. There 147 | are now two control codes for inserting a chunk: @< and @<<. The @< 148 | inserts the chunk only into the current scope and does not allow them 149 | to escape, whereas the @<< wraps the exports at the call site where 150 | the enclosing @> is called. 151 | 152 | Library exports now have a greatly improved formatting. 153 | 154 | You now specify imports, exports, and captures through named options 155 | at the beginning of a chunk, and all of them are optional. That is, 156 | rather than doing something like this: 157 | 158 | (@> Blah () (a b) () (define a #t) (define b #f)) 159 | 160 | You would now do something like this: 161 | 162 | (@> Blah (export a b) (define a #t) (define b #f)) 163 | 164 | There have been many little formatting improvements in the TeX macros. 165 | The macros are now more robust, but not perfect. 166 | 167 | The exports and imports and, in fact, any long list controlled by 168 | ChezWEAVE will now dynamically switch from a ragged paragraph to a 169 | table format if there are too many elements. 170 | 171 | The library handling is now more robust. 172 | 173 | The weaving of modules can now handle a more complete module syntax. 174 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | VERSION=2.0 2 | 3 | include config.mk 4 | 5 | PACKAGE_FILES=README ChangeLog \ 6 | cheztangle chezweave chezweb.pdf doc/cwebman.pdf chezwebmac.tex \ 7 | runtime.so 8 | 9 | build: 10 | ./bootstrap 11 | ./tangleit 12 | ./weaveit 13 | 14 | petite: 15 | ./bootstrap 16 | ./tangleit petite 17 | ./weaveit 18 | 19 | install: 20 | env BINDIR=${BINDIR} \ 21 | TEXDIR=${TEXDIR} \ 22 | DOCDIR=${DOCDIR} \ 23 | LIBDIR=${LIBDIR} \ 24 | OWNER=${OWNER} \ 25 | GROUP=${GROUP} \ 26 | ./installit ${PREFIX} 27 | 28 | package: build 29 | rm -rf chezweb-${VERSION}-${MACHINE} 30 | mkdir chezweb-${VERSION}-${MACHINE} 31 | cp ${PACKAGE_FILES} chezweb-${VERSION}-${MACHINE} 32 | tar cvJf chezweb-${VERSION}-${MACHINE}.tar.xz \ 33 | chezweb-${VERSION}-${MACHINE} 34 | rm -r chezweb-${VERSION}-${MACHINE} 35 | 36 | clean: 37 | rm -rf runtime.ss runtime.sls cheztangle.ss chezweave.ss chezweb.ss 38 | rm -rf runtime.so cheztangle chezweave 39 | rm -rf chezweb.{1,2,3,4,5} 40 | rm -rf chezweb.tex chezweb.pdf doc/cwebman.pdf doc/cwebman.log 41 | rm -rf chezweb.{idx,log,mpx,scn,toc} 42 | rm -rf doc/cwebman.toc 43 | -------------------------------------------------------------------------------- /README: -------------------------------------------------------------------------------- 1 | ┌──────────────────────────────────┐ 2 | │ ChezWEB: A WEB system for Scheme │ 3 | └──────────────────────────────────┘ 4 | 5 | Copyright (c) 2012 Aaron W. Hsu . 6 | 7 | ChezWEB is a system for doing Knuthian style WEB programming in Scheme, and 8 | more particularly, it is implemented in Chez Scheme. It has a number of 9 | novel features, and is designed to provide a level of integration with 10 | Scheme that is not to be found in other Literate Programming systems. In 11 | particular, it implements hygienic named sections that perserve hygiene and 12 | scoping in the presence of definitions and the like. 13 | 14 | I have provided the quickstart information first, and you can find the rest 15 | of the documentation further down. 16 | 17 | Installing ChezWEB from Source 18 | ────────────────────────────── 19 | 20 | The fastest way to install ChezWEB is to use the make file provided. There 21 | are a few constants defined at the top of the file, which you can change for 22 | your particular installation, but otherwise, it should be as easy as: 23 | 24 | $ make build install 25 | 26 | You should make sure you edit the constants to do what you want and to 27 | install everything where you want them installed. The makefile assumes that 28 | you already have a version of Chez Scheme installed. 29 | 30 | A more complete installation line might look like this: 31 | 32 | $ make build install \ 33 | PREFIX= \ 34 | TEXDIR=... \ 35 | DOCDIR=... \ 36 | BINDIR=... \ 37 | LIBDIR=... 38 | 39 | You can learn more about these values by running the installit script 40 | without any arguments. There are three main components to the ChezWEB 41 | system. 42 | 43 | 1) ChezWEAVE and ChezTANGLE programs 44 | 2) chezwebmac.tex macros 45 | 3) Runtime library for independent use 46 | 47 | To get this all working, we have to execute three build scripts to link it 48 | all up, followed by one install script. 49 | 50 | bootstrap Bootstraps the ChezWEB system 51 | tangleit Tangles the actual ChezWEB programs 52 | weaveit Weaves the ChezWEB documentation 53 | installit Installs all the components 54 | 55 | Building ChezWEB without the compiler 56 | ───────────────────────────────────── 57 | 58 | If you only have Petite Chez Scheme, you can still use ChezWEB. There are 59 | two things to change. Firstly, build the system using the 'petite' target 60 | instead of the 'build' target. Secondly, make sure that your CHEZWEBHOME 61 | environment variable points to the LIBDIR that you specified. 62 | 63 | System Requirements 64 | ─────────────────── 65 | 66 | ChezWEB is tested on (Petite) Chez Scheme 8.4+, as it is built on R6RS and 67 | relies on certain features introduced after version 8.0. Earlier versions 68 | may run, but there is no guarantee, and you should really be using the 69 | latest version of Chez Scheme 8.x. 70 | 71 | If you want to actually do the weaving of the main ChezWEB document and 72 | get some reasonable output, which includes running the weaveit program, 73 | you will need to have a properly configured TeX Live installation with 74 | a working MetaPost. There have been some reports of misconfigured 75 | TeX Live installations which result in MetaPost not working, which will 76 | cause errors in the weaveit part of the build. You do not actually 77 | need to do this step if you just want to use the system, but you will 78 | not get the documentation. I recommend that you just make sure you 79 | have a working MetaPost. 80 | 81 | Documentation 82 | ───────────── 83 | 84 | A copy of the CWEB manual is included with this distribution. It provides 85 | a basic overview of how a system like this should normally work. It does 86 | not focus on ChezWEB specifically, which is a known problem that I hope to 87 | rectify soon. If there are any volunteers.... 88 | 89 | Contact/Support 90 | ─────────────── 91 | 92 | Please contact Aaron W. Hsu if you have any 93 | questions about the system, or if you have patches to commit. I 94 | welcome any additions and contributions! 95 | -------------------------------------------------------------------------------- /TODO: -------------------------------------------------------------------------------- 1 | * REPL printing in texts 2 | * Non-hygienic chunks 3 | * Pretty printer for Scheme 4 | * Deal with Unicode properly 5 | * Find a way of dealing with libraries 6 | * Add a verification pass so that we don't have to verify the code in 7 | both weaving and tangling sections. 8 | 9 | NEW OPERATORS FOR VERSION 2 10 | 11 | @* Title section 12 | @ Untitled section 13 | @p Top level program 14 | @( Write to file 15 | @< Define Chunk (Runtime) 16 | @>= Delimit chunk 17 | @> Delimit code text 18 | @c Captures and Exports 19 | @f Format 20 | @r REPL Interaction 21 | @@ Escaped @ 22 | @^ Index in roman type 23 | @. Index in typewriter type 24 | @: Index defined by \9 25 | @q Comment 26 | @i Include 27 | -------------------------------------------------------------------------------- /bootstrap: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | ./bootstrap.ss 5 | chmod +x cheztangle.ss 6 | chmod +x chezweave.ss 7 | -------------------------------------------------------------------------------- /bootstrap.ss: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env scheme-script 2 | ;;; -*- Mode: scheme -*- 3 | 4 | ;;;; Bootstrap Tangler for ChezWEB 5 | ;;;; Allow ChezWEB to be bootstrapped 6 | 7 | ;;; Copyright (c) 2011 Aaron W. Hsu 8 | ;;; 9 | ;;; Permission to use, copy, modify, and distribute this software for 10 | ;;; any purpose with or without fee is hereby granted, provided that the 11 | ;;; above copyright notice and this permission notice appear in all 12 | ;;; copies. 13 | ;;; 14 | ;;; THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL 15 | ;;; WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 16 | ;;; WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE 17 | ;;; AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL 18 | ;;; DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA 19 | ;;; OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 20 | ;;; TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 21 | ;;; PERFORMANCE OF THIS SOFTWARE. 22 | 23 | ;; This program is basically a hand composed version of TANGLE that 24 | ;; allows the ChezWEB system to be boostrapped from the ground up. It 25 | ;; works only on the CWEB syntax, and does not support the Scribble 26 | ;; syntax. It is designed to let the user build a running version of 27 | ;; TANGLE from the WEB syntax files tangle.w. 28 | #!chezscheme 29 | (import (chezscheme)) 30 | 31 | (module (@< =>) 32 | (import-only (chezscheme)) 33 | 34 | (define-syntax @< 35 | (syntax-rules (=>) 36 | [ (_ (name c ...) => (e ...) b1 b2 ...) 37 | (for-all identifier? #'(name c ... e ...)) 38 | (module-form name (c ...) (e ...) b1 b2 ...)] 39 | [ (_ (name c ...) b1 b2 ...) 40 | (value-form name (c ...) b1 b2 ...)])) 41 | 42 | (define-syntax module-form 43 | (syntax-rules () 44 | [ (_ name (c ...) (e ...) body ...) 45 | (define-syntax (name x) 46 | (syntax-case x () 47 | [ id (identifier? #'id) 48 | #'(build-module-form 49 | id (c ...) (e ...) ((... ...) body) ...)]))])) 50 | 51 | (define-syntax value-form 52 | (syntax-rules () 53 | [ (_ name (c ...) body ...) 54 | (define-syntax (name x) 55 | (syntax-case x () 56 | [ id (identifier? #'id) 57 | #'(build-value-form id (c ...) ((... ...) body) ...)] 58 | [ (id . rest) 59 | #'( (build-value-form id (c ...) ((... ...) body) ...) 60 | . rest)]))])) 61 | 62 | (define-syntax (build-module-form x) 63 | (syntax-case x () 64 | [ (_ id (ic ...) (ie ...) body ...) 65 | (with-syntax 66 | ( [(oc ...) (datum->syntax #'id (syntax->datum #'(ic ...)))] 67 | [(oe ...) (datum->syntax #'id (syntax->datum #'(ie ...)))]) 68 | #'(module (oe ...) 69 | (alias ic oc) ... 70 | (module (ie ...) body ...) 71 | (alias oe ie) ...))])) 72 | 73 | (define-syntax (build-value-form x) 74 | (syntax-case x () 75 | [ (_ id (ic ...) body ...) 76 | (with-syntax 77 | ([ (oc ...) 78 | (datum->syntax #'id (syntax->datum #'(ic ...)))]) 79 | #'(let () (alias ic oc) ... body ...))])) 80 | 81 | (indirect-export @< 82 | module-form value-form build-module-form build-value-form) 83 | ) 84 | 85 | ;;; All the chunk definitions go here 86 | 87 | (@< (|Parse possible control code| c cur tokens port loop) 88 | (let ([nc (read-char port)]) 89 | (case nc 90 | [ (#\@) (loop tokens (cons c cur))] 91 | [ (#\q) (get-line port) (loop tokens cur)] 92 | [ (#\space #\< #\p #\* #\e #\r #\( #\^ #\. #\: #\i #\c) ;) 93 | (let ([token (string->symbol (string c nc))]) 94 | (if (null? cur) 95 | (loop (cons token tokens) '()) 96 | (loop (cons* token (list->string (reverse cur)) tokens) '())))] 97 | [ (#\>) |Parse possible @>= delimiter|] 98 | [else 99 | (if (eof-object? nc) 100 | (loop tokens cur) 101 | (loop tokens (cons* nc c cur)))])) 102 | ) 103 | 104 | (@< (|Parse possible @>= delimiter| port cur loop tokens c nc) 105 | (define (extend tok ncur) 106 | (if (null? cur) 107 | (loop (cons tok tokens) ncur) 108 | (loop 109 | (cons* tok (list->string (reverse cur)) tokens) 110 | ncur))) 111 | (let ([nnc (read-char port)]) 112 | (if (char=? #\= nnc) 113 | (begin (get-line port) (extend '@>= '())) 114 | (extend '@> (list nnc)))) 115 | ) 116 | 117 | (@< (|Extend default top-level| loop tokens top-level) 118 | (define-values (ntkns body) (slurp-code (cdr tokens) tangle-encode)) 119 | (hashtable-update! top-level '*default* 120 | (lambda (cur) (string-append cur body)) 121 | "") 122 | (loop ntkns '() #f) 123 | ) 124 | 125 | (@< (|Extend file top-level| loop tokens top-level) 126 | |Verify and extract delimited chunk| 127 | (let ([name (strip-whitespace name)]) 128 | (hashtable-update! top-level name 129 | (lambda (cur) (string-append cur body)) 130 | "")) 131 | (loop tknsrest '() #f) 132 | ) 133 | 134 | (@< (|Update the current captures| loop tokens) 135 | (unless (string? (cadr tokens)) 136 | (error #f "Expected captures line" (cadr tokens))) 137 | (with-input-from-string (cadr tokens) 138 | (lambda () 139 | (let* ([captures (read)] [arrow (read)] [exports (read)]) 140 | (unless (and (list? captures) (for-all symbol? captures)) 141 | (error #f "Expected list of identifiers for captures" captures)) 142 | (unless (and (eof-object? arrow) (eof-object? exports)) 143 | (unless (eq? '=> arrow) 144 | (error #f "Expected =>" arrow)) 145 | (unless (and (list? exports) (for-all symbol? exports)) 146 | (error #f "Expected list of identifiers for exports" exports))) 147 | (loop (cddr tokens) captures 148 | (and (not (eof-object? exports)) exports))))) 149 | ) 150 | 151 | (@< (|Extend named chunk| 152 | loop tokens named current-captures current-exports captures) 153 | |Verify and extract delimited chunk| 154 | (let ([name (string->symbol (strip-whitespace name))]) 155 | (hashtable-update! named name 156 | (lambda (cur) (string-append cur body)) 157 | "") 158 | (hashtable-update! captures name 159 | (lambda (cur) |Extend captures and exports|) 160 | #f)) 161 | (loop tknsrest '() #f) 162 | ) 163 | 164 | (@< (|Extend captures and exports| 165 | current-exports current-captures cur name) 166 | (define (union s1 s2) 167 | (fold-left (lambda (s e) (if (memq e s) s (cons e s))) s1 s2)) 168 | (when (and cur (not (cdr cur)) current-exports) 169 | (error #f "attempt to extend a value named chunk as a definition chunk" 170 | name current-exports)) 171 | (when (and cur (cdr cur) (not current-exports)) 172 | (error #f "attempt to extend a definition chunk as a value chunk" 173 | name (cdr cur))) 174 | 175 | (if cur 176 | (cons (append (car cur) current-captures) 177 | (and (cdr cur) (append (cdr cur) current-exports))) 178 | (cons current-captures current-exports)) 179 | ) 180 | 181 | (@< (|Verify and extract delimited chunk| tokens) => (name body tknsrest) 182 | (define (encode x) (format "|~a|" x)) 183 | (define-values (name body tknsrest) 184 | (let () 185 | (unless (<= 4 (length tokens)) 186 | (error #f "unexpected end of file" tokens)) 187 | (let ([name (list-ref tokens 1)] [closer (list-ref tokens 2)]) 188 | (unless (eq? '@>= closer) 189 | (error #f "Expected closing @>=" name closer)) 190 | (unless (string? name) 191 | (error #f "Expected name string" name)) 192 | (let-values ([(ntkns body) 193 | (slurp-code (list-tail tokens 3) tangle-encode)]) 194 | (values name body ntkns))))) 195 | ) 196 | 197 | (@< (|Write tangled file contents| 198 | file output-file top-level-chunks named-chunks captures) 199 | (call-with-output-file output-file 200 | (lambda (output-port) 201 | (when (eq? file '*default*) 202 | (put-string output-port "#!chezscheme\n") 203 | (put-string output-port runtime-code) 204 | |Write named chunks to file|) 205 | (put-string output-port 206 | (hashtable-ref top-level-chunks 207 | (if (eq? file '*default*) '*default* output-file) 208 | ""))) 209 | 'replace) 210 | ) 211 | 212 | (@< (|Verify index syntax| tokens) 213 | (unless (<= 3 (length tokens)) 214 | (error #f "invalid index entry" tokens)) 215 | (unless (string? (cadr tokens)) 216 | (error #f "expected index entry text" (list-head tokens 3))) 217 | (unless (eq? '@> (caddr tokens)) 218 | (error #f "expected index entry closer" (list-head tokens 3))) 219 | ) 220 | 221 | (@< (|Write named chunks to file| captures named-chunks output-port) 222 | (for-each 223 | (lambda (name) 224 | (let ([cell (hashtable-ref captures name '(() . #f))]) 225 | (format output-port 226 | "(@< (~s ~{~s ~}) ~@[=> (~{~s ~})~]~n~a)~n~n" 227 | name (car cell) (cdr cell) 228 | (hashtable-ref named-chunks name "")))) 229 | (vector->list (hashtable-keys named-chunks))) 230 | ) 231 | 232 | (@< (|Verify chunk reference syntax| tokens) 233 | (unless (<= 3 (length tokens)) 234 | (error #f "unexpected end of token stream" tokens)) 235 | (unless (string? (cadr tokens)) 236 | (error #f "expected chunk name" (list-head tokens 2))) 237 | (unless (eq? '@> (caddr tokens)) 238 | (error #f "expected chunk closer" (list-head tokens 3))) 239 | ) 240 | 241 | 242 | ;;; All of the top-level code goes here 243 | 244 | (define (chezweb-tokenize port) 245 | (let loop ([tokens '()] [cur '()]) 246 | (let ([c (read-char port)]) 247 | (cond 248 | [ (eof-object? c) 249 | (reverse 250 | (if (null? cur) 251 | tokens 252 | (cons (list->string (reverse cur)) tokens)))] 253 | [(char=? #\@ c) |Parse possible control code|] 254 | [else (loop tokens (cons c cur))])))) 255 | 256 | (define runtime-code 257 | "(module (@< =>) 258 | (import-only (chezscheme)) 259 | 260 | (define-syntax @< 261 | (syntax-rules (=>) 262 | [(_ (name c ...) => (e ...) b1 b2 ...) 263 | (for-all identifier? #'(name c ... e ...)) 264 | (module-form name (c ...) (e ...) b1 b2 ...)] 265 | [(_ (name c ...) b1 b2 ...) 266 | (value-form name (c ...) b1 b2 ...)])) 267 | 268 | (define-syntax module-form 269 | (syntax-rules () 270 | [(_ name (c ...) (e ...) body ...) 271 | (define-syntax (name x) 272 | (syntax-case x () 273 | [id (identifier? #'id) 274 | #'(build-module-form 275 | id (c ...) (e ...) ((... ...) body) ...)]))])) 276 | 277 | (define-syntax value-form 278 | (syntax-rules () 279 | [(_ name (c ...) body ...) 280 | (define-syntax (name x) 281 | (syntax-case x () 282 | [id (identifier? #'id) 283 | #'(build-value-form id (c ...) ((... ...) body) ...)] 284 | [(id . rest) 285 | #'((build-value-form id (c ...) ((... ...) body) ...) 286 | . rest)]))])) 287 | 288 | (define-syntax (build-module-form x) 289 | (syntax-case x () 290 | [(_ id (ic ...) (ie ...) body ...) 291 | (with-syntax 292 | ([(oc ...) (datum->syntax #'id (syntax->datum #'(ic ...)))] 293 | [(oe ...) (datum->syntax #'id (syntax->datum #'(ie ...)))]) 294 | #'(module (oe ...) 295 | (alias ic oc) ... 296 | (module (ie ...) body ...) 297 | (alias oe ie) ...))])) 298 | 299 | (define-syntax (build-value-form x) 300 | (syntax-case x () 301 | [(_ id (ic ...) body ...) 302 | (with-syntax 303 | ([(oc ...) 304 | (datum->syntax #'id (syntax->datum #'(ic ...)))]) 305 | #'(let () (alias ic oc) ... body ...))])) 306 | 307 | (indirect-export @< 308 | module-form value-form build-module-form build-value-form) 309 | ) 310 | 311 | ") 312 | 313 | (define (construct-chunk-tables token-list) 314 | (let 315 | ([named (make-eq-hashtable)] 316 | [top-level (make-hashtable equal-hash equal?)] 317 | [captures (make-eq-hashtable)]) 318 | (let loop 319 | ([tokens 320 | (if (string? (car token-list)) 321 | (cdr token-list) 322 | token-list)] 323 | [current-captures '()] 324 | [current-exports #f]) 325 | (if (null? tokens) 326 | (values top-level named captures) 327 | (case (car tokens) 328 | [(|@ | @* @e @r @^ @. @: @i) 329 | (loop (cddr tokens) '() #f)] 330 | [(@p) 331 | |Extend default top-level|] 332 | [(@<) 333 | |Extend named chunk|] 334 | [(|@(|) 335 | |Extend file top-level|] 336 | [(@c) 337 | |Update the current captures|] 338 | [else 339 | (error #f "Unexpected token" (car tokens) (cadr tokens))]))))) 340 | 341 | (define (strip-whitespace str) 342 | (define (search str inc start end) 343 | (let loop ([i start]) 344 | (cond 345 | [(= i end) #f] 346 | [(not (char-whitespace? (string-ref str i))) i] 347 | [else (loop (inc i))]))) 348 | (let ([s (search str 1+ 0 (string-length str))] 349 | [e (search str -1+ (-1+ (string-length str)) -1)]) 350 | (or (and (not s) (not e) "") 351 | (substring str s (1+ e))))) 352 | 353 | (define (tangle-file web-file) 354 | (let ([default-file (format "~a.ss" (path-root web-file))] 355 | [tokens 356 | (cleanse-tokens-for-tangle 357 | (call-with-input-file web-file chezweb-tokenize))]) 358 | (let-values ([(top-level-chunks named-chunks captures) 359 | (construct-chunk-tables tokens)]) 360 | (for-each 361 | (lambda (file) 362 | (let ([output-file (if (eq? '*default* file) 363 | default-file file)]) 364 | |Write tangled file contents|)) 365 | (vector->list (hashtable-keys top-level-chunks)))))) 366 | 367 | (define (cleanse-tokens-for-tangle tokens) 368 | (let loop ([tokens tokens] [res '()]) 369 | (cond 370 | [(null? tokens) (reverse res)] 371 | [(memq (car tokens) '(@: @^ @.)) 372 | |Verify index syntax| 373 | (loop (cdddr tokens) res)] 374 | [(string? (car tokens)) 375 | (if (and (pair? res) (string? (car res))) 376 | (loop (cdr tokens) 377 | (cons (string-append (car res) (car tokens)) (cdr res))) 378 | (loop (cdr tokens) (cons (car tokens) res)))] 379 | [else 380 | (loop (cdr tokens) (cons (car tokens) res))]))) 381 | 382 | (define (slurp-code tokens encode) 383 | (define (verify x) 384 | (when (zero? (string-length x)) 385 | (error #f "expected code body" 386 | (list-head tokens (min (length tokens) 3)))) 387 | x) 388 | (let loop ([tokens tokens] [res ""]) 389 | (cond 390 | [(null? tokens) (values '() (verify res))] 391 | [(string? (car tokens)) 392 | (loop (cdr tokens) (string-append res (car tokens)))] 393 | [(eq? '@< (car tokens)) 394 | |Verify chunk reference syntax| 395 | (loop (cdddr tokens) 396 | (string-append 397 | res (encode (strip-whitespace (cadr tokens)))))] 398 | [else (values tokens (verify res))]))) 399 | 400 | (define (tangle-encode x) (format "~s" (string->symbol x))) 401 | 402 | (tangle-file "chezweb.w") 403 | (exit 0) 404 | -------------------------------------------------------------------------------- /chezweb.mp: -------------------------------------------------------------------------------- 1 | beginfig(1); 2 | defaultfont := "bchr8r"; 3 | defaultscale := 2; 4 | 5 | numeric x,y; 6 | numeric ss,sd,sz,sh; 7 | 8 | x := 0.5in; y := 0.5in; 9 | ss := 1in; sd := 2in; sz := 3in; sh := 0.5in; 10 | 11 | draw (x,y)--(x+sd,y)--(x+sd,y+sz)--(x,y+sz)--cycle; 12 | draw (x,y+ss)--(x+sd,y+ss); 13 | draw (x,y+sd)--(x+sd,y+sd); 14 | 15 | label("Runtime", (x+ss,y+sd+sh)); 16 | label("Named Chunks", (x+ss,y+ss+sh)); 17 | label("Top-level Code", (x+ss,y+sh)); 18 | endfig; 19 | 20 | beginfig(2); 21 | numeric x, y, bx, bs; 22 | numeric s, ss, sss, ssss, sh; 23 | 24 | s := 18pt; ss := s*2; sss := s*3; ssss := s*4; 25 | sh := s/2; sq := s/3; 26 | 27 | bx := 9pt; by := 9pt; 28 | 29 | x := bx; y := by; 30 | draw (x , y)--(x+ss,y)--(x+ss,y+s)--(x,y+s)--cycle; 31 | x := x+ssss+ss; 32 | draw (x,y)--(x+ss,y)--(x+ss,y+s)--(x,y+s)--cycle; 33 | x := x+ssss+ss; 34 | draw (x,y)--(x+ss,y)--(x+ss,y+s)--(x,y+s)--cycle; 35 | 36 | x := bx+ss; y := by+sh; 37 | drawarrow (x,y)--(x+ssss,y); 38 | x := x+ssss+ss; 39 | drawarrow (x,y)--(x+ssss,y); 40 | 41 | x := bx+s; 42 | label(btex {\tt WEB} etex, (x,y)); 43 | x := x+ss*3; 44 | label(btex \TeX etex, (x,y)); 45 | x := x+ss*3; 46 | label(btex {\rm PDF} etex, (x,y)); 47 | 48 | x := bx+ssss; y := y+sq; 49 | label(btex Chez{\tt WEAVE} etex, (x,y)); 50 | x := x+ss*3; 51 | label(btex Xe\TeX etex, (x,y)); 52 | endfig; 53 | 54 | beginfig(3); 55 | numeric x,y, q, s, v; 56 | numeric l,ll,lll,llll; 57 | 58 | s := 50pt; v := 0.3in; q := 6pt; 59 | l := v*4; ll := v*3; lll := v*2; llll := v*1; 60 | 61 | x := s*4.5; y := l; 62 | label(btex Control Codes etex, (x,y)); 63 | y := y-q; 64 | draw (x,y)--(s*1.5,ll); 65 | draw (x,y)--(s*3,ll); 66 | draw (x,y)--(s*4.5,ll); 67 | draw (x,y)--(s*7.5,ll); 68 | 69 | x := s*1.5; y := ll-q; 70 | draw (x,y-q)--(x-s/2,lll); 71 | draw (x,y-q)--(x+s/2,lll); 72 | label(btex Data etex, (x,y)); x := s*3; 73 | 74 | draw (x,y-q)--(x-s/2,lll); 75 | draw (x,y-q)--(x,lll); 76 | draw (x,y-q)--(x+s/2,lll); 77 | label(btex Code etex, (x,y)); x := s*4.5; 78 | 79 | draw (x,y-q)--(x-s/2,lll); 80 | draw (x,y-q)--(x+s/2,lll); 81 | label(btex Delimiter etex, (x,y)); x := s*7.5; 82 | 83 | draw (x,y-q)--(x-s*2,lll); 84 | draw (x,y-q)--(x-s,lll); 85 | draw (x,y-q)--(x,lll); 86 | draw (x,y-q)--(x+s,lll); 87 | label(btex Annotation etex, (x,y)); 88 | 89 | x := s*1.5-s/2; y := lll-q; 90 | label(btex {\tt @\ } etex, (x,y)); x := x+s; 91 | label(btex {\tt @*} etex, (x,y)); 92 | 93 | x := s*3-s/2; 94 | label(btex {\tt @p} etex, (x,y)); x := x+s/2; 95 | label(btex {\tt @<} etex, (x,y)); x := x+s/2; 96 | label(btex {\tt @(} etex, (x,y)); x := x+s/2; 97 | 98 | x := s*4.5-s/2; 99 | label(btex {\tt @>} etex, (x,y)); x := x+s; 100 | label(btex {\tt @>=} etex, (x,y)); x := x+s; 101 | 102 | x := s*7.5-s*2; 103 | label(btex {\tt @c} etex, (x,y)); x := x+s; 104 | label(btex {\tt @q} etex, (x,y)); x := x+s; 105 | label(btex Index etex, (x,y)); x := x+s; 106 | label(btex {\tt @i} etex, (x,y)); x := x+s; 107 | 108 | x := s*7.5; y := y-q; 109 | draw (x,y)--(x-s/2,llll); 110 | draw (x,y)--(x,llll); 111 | draw (x,y)--(x+s/2,llll); 112 | 113 | x := s*7.5-s/2; y := llll-q; 114 | label(btex {\tt @\^\ } etex, (x,y)); x := x+s/2; 115 | label(btex {\tt @:} etex, (x,y)); x := x+s/2; 116 | label(btex {\tt @.} etex, (x,y)); x := x+s/2; 117 | endfig; 118 | 119 | beginfig(4); 120 | numeric x, y, bx, bs; 121 | numeric s, ss, sss, ssss, sh; 122 | 123 | s := 18pt; ss := s*2; sss := s*3; ssss := s*4; 124 | sh := s/2; sq := s/3; 125 | 126 | bx := 9pt; by := 9pt; 127 | 128 | x := bx; y := by; 129 | draw (x , y)--(x+ss,y)--(x+ss,y+s)--(x,y+s)--cycle; 130 | x := x+ssss+ss; 131 | draw (x,y)--(x+ss,y)--(x+ss,y+s)--(x,y+s)--cycle; 132 | 133 | x := bx+ss; y := by+sh; 134 | drawarrow (x,y)--(x+ssss,y); 135 | 136 | x := bx+s; 137 | label(btex {\tt WEB} etex, (x,y)); 138 | x := x+ss*3; 139 | label(btex {\tt SCM} etex, (x,y)); 140 | 141 | x := bx+ssss; y := y+sq; 142 | label(btex Chez{\tt TANGLE} etex, (x,y)); 143 | endfig; 144 | 145 | beginfig(5); 146 | path ob,rtb,rtlb,ssb,wvb,tngb; 147 | 148 | ob := (0in,0in)--(0in,3in)--(6in,3in)--(6in,0in)--cycle; 149 | rtb := (0.1in,0.1in)--(0.1in,2.5in)--(2.95in,2.5in)--(2.95in,0.1in)--cycle; 150 | ssb := (3.05in,0.1in)--(3.05in,2.5in)--(5.9in,2.5in)--(5.9in,0.1in)--cycle; 151 | rtlb := (0.2in,0.2in)--(0.2in,1in)--(2.85in,1in)--(2.85in,0.2in)--cycle; 152 | tngb := (3.15in,0.2in)--(3.15in,1in)--(5.8in,1in)--(5.8in,0.2in)--cycle; 153 | wvb := (3.15in,1.1in)--(3.15in,2in)--(5.8in,2in)--(5.8in,1.1in)--cycle; 154 | 155 | draw ob; draw rtb; draw ssb; draw rtlb; draw tngb; draw wvb; 156 | 157 | label("chezweb.w", (3in,2.75in)); 158 | label("runtime.ss", (1.5in,1.75in)); 159 | label("runtime.sls", (1.5in,0.60in)); 160 | label("chezweb.ss", (4.5in,2.24in)); 161 | label("cheztangle.ss", (4.5in,1.55in)); 162 | label("chezweave.ss", (4.5in,0.60in)); 163 | endfig; 164 | 165 | end 166 | -------------------------------------------------------------------------------- /chezwebmac.tex: -------------------------------------------------------------------------------- 1 | % standard macros for CWEB listings (in addition to plain.tex) 2 | % Version 3.67 --- July 2006 3 | % Modified by Aaron W. Hsu for use in ChezWEB -- March 2010 4 | \ifx\renewenvironment\undefined\else\endinput\fi % LaTeX will use other macros 5 | \xdef\fmtversion{\fmtversion+CWEB3.67} 6 | \chardef\cwebversion=3 \chardef\cwebrevision=67 7 | \newif\ifpdf 8 | \ifx\pdf+\pdftrue\fi 9 | % Uncomment the following line if you want PDF goodies to be the default 10 | %\ifx\pdf-\else\pdftrue\fi 11 | \def\pdflinkcolor{0 0 1} % the RGB values for hyperlink color 12 | \newif\ifpdftex 13 | \ifx\pdfoutput\undefined \pdftexfalse \else\ifnum\pdfoutput=0 \pdftexfalse 14 | \else \pdftextrue \pdfoutput=1 \input pdfcolor \let\setcolor\pdfsetcolor \fi\fi 15 | \newif\ifacro \ifpdf\acrotrue\fi \ifpdftex\acrotrue\fi 16 | 17 | \let\:=\. % preserve a way to get the dot accent 18 | % (all other accents will still work as usual) 19 | 20 | \parskip 0pt % no stretch between paragraphs 21 | \parindent 1em % for paragraphs and for the first line of C text 22 | 23 | \font\ninerm=cmr9 24 | \let\mc=\ninerm % medium caps 25 | \def\CEE/{{\mc C\spacefactor1000}} 26 | \def\UNIX/{{\mc U\kern-.05emNIX\spacefactor1000}} 27 | \def\TEX/{\TeX} 28 | \def\CPLUSPLUS/{{\mc C\PP\spacefactor1000}} 29 | \def\Cee{\CEE/} % for backward compatibility 30 | \def\9#1{} 31 | % with this definition of \9 you can say @:sort key}{TeX code@> 32 | % to alphabetize an index entry by the sort key but format with the TeX code 33 | \font\eightrm=cmr8 34 | \let\sc=\eightrm % for smallish caps (NOT a caps-and-small-caps font) 35 | \let\mainfont=\tenrm 36 | \let\cmntfont\tenrm 37 | %\font\tenss=cmss10 \let\cmntfont\tenss % alternative comment font 38 | \font\titlefont=cmr7 scaled\magstep4 % title on the contents page 39 | \font\ttitlefont=cmtt10 scaled\magstep2 % typewriter type in title 40 | \font\tentex=cmtex10 % TeX extended character set (used in strings) 41 | \fontdimen7\tentex=0pt % no double space after sentences 42 | 43 | \def\\#1{\leavevmode\hbox{\it#1\/\kern.05em}} % italic type for identifiers 44 | \def\|#1{\leavevmode\hbox{$#1$}} % one-letter identifiers look better this way 45 | \def\{\leavevmode\hbox{\bf 46 | \def\_{\kern.04em\vbox{\hrule width.3em height .6pt}\kern.08em}% 47 | #1\/\kern.05em}} % boldface type for reserved words 48 | \def\.#1{\leavevmode\hbox{\tentex % typewriter type for strings 49 | \let\\=\BS % backslash in a string 50 | \let\{=\LB % left brace in a string 51 | \let\}=\RB % right brace in a string 52 | \let\~=\TL % tilde in a string 53 | \let\ =\SP % space in a string 54 | \let\_=\UL % underline in a string 55 | \let\&=\AM % ampersand in a string 56 | \let\^=\CF % circumflex in a string 57 | #1\kern.05em}} 58 | \def\){{\tentex\kern-.05em}\discretionary{\hbox{\tentex\BS}}{}{}} 59 | \def\AT{@} % at sign for control text (not needed in versions >= 2.9) 60 | \def\ATL{\par\noindent\bgroup\catcode`\_=12 \postATL} % print @l in limbo 61 | \def\postATL#1 #2 {\bf letter \\{\uppercase{\char"#1}} 62 | tangles as \tentex "#2"\egroup\par} 63 | \def\noATL#1 #2 {} 64 | \def\noatl{\let\ATL=\noATL} % suppress output from @l 65 | \def\ATH{{\acrofalse\X\kern-.5em:Preprocessor definitions\X}} 66 | \let\PB=\relax % hook for program brackets |...| in TeX part or section name 67 | 68 | \chardef\AM=`\& % ampersand character in a string 69 | \chardef\BS=`\\ % backslash in a string 70 | \chardef\LB=`\{ % left brace in a string 71 | \chardef\RB=`\} % right brace in a string 72 | \def\SP{{\tt\char`\ }} % (visible) space in a string 73 | \chardef\TL=`\~ % tilde in a string 74 | \chardef\UL=`\_ % underline character in a string 75 | \chardef\CF=`\^ % circumflex character in a string 76 | 77 | \newbox\PPbox % symbol for ++ 78 | \setbox\PPbox=\hbox{\kern.5pt\raise1pt\hbox{\sevenrm+\kern-1pt+}\kern.5pt} 79 | \def\PP{\copy\PPbox} 80 | \newbox\MMbox \setbox\MMbox=\hbox{\kern.5pt\raise1pt\hbox{\sevensy\char0 81 | \kern-1pt\char0}\kern.5pt} 82 | \def\MM{\copy\MMbox} 83 | \newbox\MGbox % symbol for -> 84 | \setbox\MGbox=\hbox{\kern-2pt\lower3pt\hbox{\teni\char'176}\kern1pt} 85 | \def\MG{\copy\MGbox} 86 | \def\MRL#1{\mathrel{\let\K==#1}} 87 | %\def\MRL#1{\KK#1}\def\KK#1#2{\buildrel\;#1\over{#2}} 88 | \let\GG=\gg 89 | \let\LL=\ll 90 | \let\NULL=\Lambda 91 | \mathchardef\AND="2026 % bitwise and; also \& (unary operator) 92 | \let\OR=\mid % bitwise or 93 | \let\XOR=\oplus % bitwise exclusive or 94 | \def\CM{{\sim}} % bitwise complement 95 | \newbox\MODbox \setbox\MODbox=\hbox{\eightrm\%} 96 | \def\MOD{\mathbin{\copy\MODbox}} 97 | \def\DC{\kern.1em{::}\kern.1em} % symbol for :: 98 | \def\PA{\mathbin{.*}} % symbol for .* 99 | \def\MGA{\mathbin{\MG*}} % symbol for ->* 100 | \def\this{\&{this}} 101 | 102 | \newbox\bak \setbox\bak=\hbox to -1em{} % backspace one em 103 | \newbox\bakk\setbox\bakk=\hbox to -2em{} % backspace two ems 104 | 105 | \newcount\ind % current indentation in ems 106 | \def\1{\global\advance\ind by1\hangindent\ind em} % indent one more notch 107 | \def\2{\global\advance\ind by-1} % indent one less notch 108 | \def\3#1{\hfil\penalty#10\hfilneg} % optional break within a statement 109 | \def\4{\copy\bak} % backspace one notch 110 | \def\5{\hfil\penalty-1\hfilneg\kern2.5em\copy\bakk\ignorespaces}% optional break 111 | \def\6{\ifmmode\else\par % forced break 112 | \hangindent\ind em\noindent\kern\ind em\copy\bakk\ignorespaces\fi} 113 | \def\7{\Y\6} % forced break and a little extra space 114 | \def\8{\hskip-\ind em\hskip 2em} % no indentation 115 | 116 | \newcount\gdepth % depth of current major group, plus one 117 | \newcount\secpagedepth 118 | \secpagedepth=3 % page breaks will occur for depths -1, 0, and 1 119 | \newtoks\gtitle % title of current major group 120 | \newskip\intersecskip \intersecskip=12pt minus 3pt % space between sections 121 | \let\yskip=\smallskip 122 | \def\?{\mathrel?} 123 | \def\note#1#2.{\Y\noindent{\hangindent2em% 124 | \baselineskip10pt\eightrm#1~\ifacro% 125 | \everyverbatim={\smtt}% 126 | {\pdfnote#2.}\else#2\fi.\par}} 127 | 128 | \newtoks\toksA \newtoks\toksB \newtoks\toksC \newtoks\toksD 129 | \newtoks\toksE \newtoks\toksF \newtoks\usersanitizer 130 | \newcount\countA \countA=0 \newcount\countB \countB=0 131 | \newcount\countC \countC=0 132 | \newif\iftokprocessed \newif\ifTnum \newif\ifinstr 133 | {\def\\{\global\let\spacechar= }\\ } 134 | 135 | \ifacro % The following are pdf macros 136 | \def\thewidth{\the\wd0 \space} 137 | \def\theheight{\the\ht\strutbox\space} 138 | \def\thedepth{\the\dp\strutbox\space} 139 | \ifpdftex 140 | \ifx\pdfannotlink\undefined\let\pdfannotlink\pdfstartlink\fi% for pdfTeX 0.14 141 | \def\pdflink#1#2{\hbox{\pdfannotlink height\ht\strutbox depth\dp\strutbox 142 | attr{/Border [0 0 0]} goto num #1 \BlueGreen #1\Black\pdfendlink}} 143 | \else\def\pdflink#1#2{\setbox0=\hbox{\special{pdf: bc [ \pdflinkcolor ]}{#1}% 144 | \special{pdf: ec}}\special{pdf: ann width \thewidth height \theheight 145 | depth \thedepth << /Type /Annot /Subtype /Link 146 | /Border [0 0 0] /A << /S /GoTo /D (#2) >> >>}\box0\relax}\fi 147 | \def\pdfnote#1.{\setbox0=\hbox{\toksA={#1.}\toksB={}\maketoks}\the\toksA} 148 | \def\firstsecno#1.{\setbox0=\hbox{\toksA={#1.}\toksB={}% 149 | \def\makenote{\addtokens\toksB{\the\toksC}\def\makenote{\toksD={} 150 | \toksC={}\let\space\empty}\makenote}\maketoks}} 151 | \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} 152 | \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}% 153 | \ifcat\noexpand\first0\countB=`#1\else\countB=0\fi\toksA={#2}} 154 | \def\maketoks{\expandafter\poptoks\the\toksA|ENDTOKS|% 155 | \ifnum\countB>`9 \countB=0 \fi 156 | \ifnum\countB<`0 157 | \ifnum0=\countC\else\makenote\fi 158 | \ifx\first.\let\next=\maketoksdone\else 159 | \let\next=\maketoks 160 | \addtokens\toksB{\the\toksD} 161 | \ifx\first,\addtokens\toksB{\space}\fi 162 | \fi 163 | \else \addtokens\toksC{\the\toksD}\global\countC=1\let\next=\maketoks 164 | \fi 165 | \next 166 | } 167 | \def\makenote{\addtokens\toksB 168 | {\noexpand\pdflink{\the\toksC}{\romannumeral\the\toksC}}\toksC={}\global\countC=0} 169 | \def\maketoksdone{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} 170 | \def\pdfURL#1#2{\ifpdftex\pdfannotlink height\ht\strutbox depth\dp\strutbox 171 | attr {/Border [0 0 0]} user { /Type /Action /Subtype /Link /A 172 | << /S /URI /URI (#2) >>}\BlueGreen #1\Black \pdfendlink 173 | \else \ifpdf{\setbox0=\hbox{\special{pdf: bc [ \pdflinkcolor ]}{#1}% 174 | \special{pdf: ec}}\special{pdf: ann width \thewidth\space height \theheight 175 | \space depth \thedepth\space << /Border [0 0 0] 176 | /Type /Action /Subtype /Link /A << /S /URI /URI (#2) >> >>}\box0\relax}% 177 | \else #1 ({\tt#2})\fi\fi} 178 | {\catcode`\~=12 \gdef\TILDE/{~}} % ~ in a URL 179 | {\catcode`\_=12 \gdef\UNDER/{_}} % _ in a URL 180 | \def\sanitizecommand#1#2{\addtokens\usersanitizer 181 | {\noexpand\dosanitizecommand\noexpand#1{#2}}} 182 | \def\dosanitizecommand#1#2{\ifx\nxt#1\addF{#2}\fi} 183 | 184 | \catcode`\[=1 \catcode`\]=2 \catcode`\{=12 \catcode`\}=12 185 | \def\lbchar[{] \def\rbchar[}] 186 | \catcode`\[=12 \catcode`\]=12 \catcode`\{=1 \catcode`\}=2 187 | \catcode`\~=12 \def\tildechar{~} \catcode`\~=13 188 | \catcode`\|=0 |catcode`|\=12 |def|bschar{\} |catcode`|\=0 \catcode`\|=12 189 | \def\makeoutlinetoks{\Tnumfalse\afterassignment\makeolproctok\let\nxt= } 190 | \def\makeolnexttok{\afterassignment\makeolproctok\let\nxt= } 191 | \def\makeolgobbletok{\afterassignment\makeolnexttok\let\nxt= } 192 | \def\addF#1{\addtokens\toksF{#1}\tokprocessedtrue} 193 | % now comes a routine to "sanitize" section names, for pdf outlines 194 | \def\makeolproctok{\tokprocessedfalse 195 | \let\next\makeolnexttok % default 196 | \ifx\nxt\outlinedone\let\next\outlinedone 197 | \else\ifx{\nxt \else\ifx}\nxt \Tnumfalse \instrfalse % skip braces 198 | \else\ifx$\nxt % or a $ sign 199 | \else\ifx^\nxt \addF^\else\ifx_\nxt \addF_% sanitize ^ and _ 200 | \else\ifx\nxt\spacechar \addF\space 201 | \else\if\noexpand\nxt\relax % we have a control sequence; is it one we know? 202 | \ifx\nxt~\addF\space 203 | \else\ifx\nxt\onespace\addF\space 204 | \else\the\usersanitizer 205 | \iftokprocessed\else\makeolproctokctli 206 | \iftokprocessed\else\makeolproctokctlii 207 | \iftokprocessed\else\makeolproctokctliii % if not recognised, skip it 208 | \fi\fi\fi\fi\fi 209 | \else % we don't have a control sequence, it's an ordinary char 210 | \ifx/\nxt \addF{\string\/}% quote chars special to PDF with backslash 211 | \else\ifx(\nxt \addF{\string\(}\else\ifx)\nxt \addF{\string\)}% 212 | \else\ifx[\nxt \addF{\string\[}\else\ifx]\nxt \addF{\string\]}% 213 | \else\expandafter\makeolproctokchar\meaning\nxt 214 | \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi 215 | \next 216 | } 217 | \def\makeolproctokchar#1 #2 #3{\addF{#3}} 218 | \def\makeolproctokctli{% 219 | \ifx\nxt\CEE\addF{C}\let\next\makeolgobbletok % \CEE/ 220 | \else\ifx\nxt\UNIX\addF{UNIX}\let\next\makeolgobbletok % \UNIX/ 221 | \else\ifx\nxt\TEX\addF{TeX}\let\next\makeolgobbletok % \TEX/ 222 | \else\ifx\nxt\TeX\addF{TeX}\else\ifx\nxt\LaTeX\addF{LaTeX}% 223 | \else\ifx\nxt\CPLUSPLUS\addF{C++}\let\next\makeolgobbletok % \CPLUSPLUS/ 224 | \else\ifx\nxt\Cee\addF{C}% 225 | \else\ifx\nxt\PB \let\next\makeolgobbletok \tokprocessedtrue % \PB{...} 226 | \else\ifx\nxt\.\tokprocessedtrue\instrtrue % \.{...} 227 | % skip \| 228 | \else\ifx\nxt\\\ifinstr\addF{\bschar\bschar}\else\tokprocessedtrue\fi 229 | \else\ifx\nxt\&\ifinstr\addF&\else\tokprocessedtrue\fi 230 | \else\ifx\nxt\~\ifTnum\addF{0}\else\addF\tildechar\fi % 077->\T{\~77} 231 | \else\ifx\nxt\_\ifTnum\addF{E}\else\addF_\fi % 0.1E5->\T{0.1\_5} 232 | \else\ifx\nxt\^\ifTnum\addF{0x}\else\addF^\fi % 0x77 -> \T{\^77} 233 | \else\ifx\nxt\$\ifTnum\tokprocessedtrue\else\addF$\fi % \T{77\$L} 234 | \else\ifx\nxt\{\addF\lbchar \else\ifx\nxt\}\addF\rbchar 235 | \else\ifx\nxt\ \addF\space \else\ifx\nxt\#\addF{\string\#}% 236 | \else\ifx\nxt\PP\addF{++}\else\ifx\nxt\MM\addF{--}% 237 | \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi 238 | } 239 | \def\makeolproctokctlii{% 240 | \ifx\nxt\MG\addF{->}\else\ifx\nxt\GG\addF{>>}% 241 | \else\ifx\nxt\LL\addF{<<}\else\ifx\nxt\NULL\addF{NULL}% 242 | \else\ifx\nxt\AND\addF&\else\ifx\nxt\OR\addF|% 243 | \else\ifx\nxt\XOR\addF^\else\ifx\nxt\CM\addF\tildechar 244 | \else\ifx\nxt\MOD\addF{\string\%}\else\ifx\nxt\DC\addF{::}% 245 | \else\ifx\nxt\PA\addF{.*}\else\ifx\nxt\MGA\addF{->*}% 246 | \else\ifx\nxt\this\addF{this}\else\ifx\nxt\?\addF?% 247 | \else\ifx\nxt\E\addF{==}\else\ifx\nxt\G\addF{>=}% 248 | \else\ifx\nxt\I\addF{!=}\else\ifx\nxt\K\addF{=}% 249 | \else\ifx\nxt\l\addF{l}\else\ifx\nxt\L\addF{L}% 250 | \else\ifx\nxt\o\addF{o}\else\ifx\nxt\O\addF{O}% 251 | \else\ifx\nxt\R\addF!% 252 | \else\ifx\nxt\T \Tnumtrue \let\next\makeolgobbletok 253 | \tokprocessedtrue % \T{number} 254 | \else\ifx\nxt\AM\addF&\else\ifx\nxt\%\addF{\string\%}% 255 | \fi\fi\fi\fi\fi \fi\fi\fi\fi\fi 256 | \fi\fi\fi\fi\fi \fi\fi\fi\fi\fi 257 | \fi\fi\fi\fi\fi\fi 258 | } 259 | \def\makeolproctokctliii{% 260 | \ifx\nxt\V\addF{||}\else\ifx\nxt\W\addF{&&}\else\ifx\nxt\Z\addF{<=}% 261 | \else\ifx\nxt\*\addF*\else\ifx\nxt\Xand\addF{\space and\space}% 262 | \else\ifx\nxt\Xandxeq\addF{\space and_eq\space}% 263 | \else\ifx\nxt\Xbitand\addF{\space bitand\space}% 264 | \else\ifx\nxt\Xbitor\addF{\space bitor\space}% 265 | \else\ifx\nxt\Xcompl\addF{\space compl\space}% 266 | \else\ifx\nxt\Xnot\addF{\space not\space}% 267 | \else\ifx\nxt\Xnotxeq\addF{\space not_eq\space}% 268 | \else\ifx\nxt\Xor\addF{\space or\space}% 269 | \else\ifx\nxt\Xorxeq\addF{\space or_eq\space}% 270 | \else\ifx\nxt\Xxor\addF{\space xor\space}% 271 | \else\ifx\nxt\Xxorxeq\addF{\space xor_eq\space}% 272 | \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi 273 | \fi\fi\fi\fi\fi 274 | } 275 | \def\outlinedone{\edef\outlinest{\global\noexpand\toksE={\the\toksF}}% 276 | \outlinest\let\outlinedone=\relax} 277 | \fi % End of pdf macros 278 | 279 | \def\lapstar{\rlap{*}} 280 | \def\stsec{\rightskip=0pt % get out of C mode (cf. \B) 281 | \sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50 282 | \noindent{\let\*=\lapstar\bf\secstar.\quad}% 283 | \ifpdftex\smash{\raise\baselineskip\hbox to0pt{% 284 | \let\*=\empty\pdfdest num \secstar fith}} 285 | \else\ifpdf\smash{\raise\baselineskip\hbox to0pt{% 286 | \let\*=\empty\special{% 287 | pdf: dest (\romannumeral\secstar) [ @thispage /FitH @ypos ]}}}\fi\fi} 288 | \let\startsection=\stsec 289 | \def\defin#1{\global\advance\ind by 2 \1\&{#1 } } % begin `define' or `format' 290 | \def\A{\note{See also section}} % xref for doubly defined section name 291 | \def\As{\note{See also sections}} % xref for multiply defined section name 292 | \def\B{\rightskip=0pt plus 100pt minus 10pt % go into C mode 293 | \sfcode`;=3000 294 | \pretolerance 10000 295 | \hyphenpenalty 1000 % so strings can be broken (discretionary \ is inserted) 296 | \exhyphenpenalty 10000 297 | \global\ind=2 \1\ \unskip} 298 | \def\C#1{\5\5\quad$/\ast\,${\cmntfont #1}$\,\ast/$} 299 | \let\SHC\C % "// short comments" treated like "/* ordinary comments */" 300 | %\def\C#1{\5\5\quad$\triangleright\,${\cmntfont#1}$\,\triangleleft$} 301 | %\def\SHC#1{\5\5\quad$\diamond\,${\cmntfont#1}} 302 | \def\D{\defin{\#define}} % macro definition 303 | \let\E=\equiv % equivalence sign 304 | \def\ET{ and~} % conjunction between two section numbers 305 | \def\ETs{, and~} % conjunction between the last two of several section numbers 306 | \def\F{\defin{format}} % format definition 307 | \let\G=\ge % greater than or equal sign 308 | % \H is long Hungarian umlaut accent 309 | \let\I=\ne % unequal sign 310 | \def\J{\.{@\&}} % TANGLE's join operation 311 | \let\K== % assignment operator 312 | %\let\K=\leftarrow % "honest" alternative to standard assignment operator 313 | % \L is Polish letter suppressed-L 314 | \outer\def\M#1{\MN{#1}\ifon\vfil\penalty-100\vfilneg % beginning of section 315 | \vskip\intersecskip\startsection\ignorespaces} 316 | \outer\def\N#1#2#3.{% beginning of starred section 317 | \ifacro{\toksF={}\makeoutlinetoks#3\outlinedone\outlinedone}\fi 318 | \gdepth=#1\gtitle={#3}\MN{#2}% 319 | \ifon\ifnum#1<\secpagedepth \vfil\eject % force page break if depth is small 320 | \else\vfil\penalty-100\vfilneg\vskip\intersecskip\fi\fi 321 | \message{*\secno} % progress report 322 | \def\stripprefix##1>{}\def\gtitletoks{#3}% 323 | \edef\gtitletoks{\expandafter\stripprefix\meaning\gtitletoks}% 324 | \edef\next{\write\cont{\ZZ{\gtitletoks}{#1}{\secno}% write to contents file 325 | {\noexpand\the\pageno}{\the\toksE}}}\next % \ZZ{title}{depth}{sec}{page}{ss} 326 | \ifpdftex\expandafter\xdef\csname curr#1\endcsname{\secno} 327 | \ifnum#1>0\countB=#1 \advance\countB by-1 328 | \advancenumber{chunk\the\countB.\expnumber{curr\the\countB}}\fi\fi 329 | \ifpdf\special{pdf: outline #1 << /Title (\the\toksE) /Dest 330 | [ @thispage /FitH @ypos ] >>}\fi 331 | \ifon\startsection{\bf#3.\quad}\ignorespaces} 332 | \def\MN#1{\par % common code for \M, \N 333 | {\xdef\secstar{#1}\let\*=\empty\xdef\secno{#1}}% remove \* from section name 334 | \ifx\secno\secstar \onmaybe \else\ontrue \fi 335 | \mark{{{\tensy x}\secno}{\the\gdepth}{\the\gtitle}}} 336 | % each \mark is {section reference or null}{depth plus 1}{group title} 337 | % \O is Scandinavian letter O-with-slash 338 | % \P is paragraph sign 339 | \def\Q{\note{This code is cited in section}} % xref for mention of a section 340 | \def\Qs{\note{This code is cited in sections}} % xref for mentions of a section 341 | \let\R=\lnot % logical not 342 | % \S is section sign 343 | \def\T#1{\leavevmode % octal, hex or decimal constant 344 | \hbox{$\def\?{\kern.2em}% 345 | % \def\$##1{\egroup_{\,\rm##1}\bgroup}% suffix to constant % versions < 3.67 346 | \def\$##1{\egroup_{\rm##1}\bgroup}% suffix to constant 347 | \def\_{\cdot 10^{\aftergroup}}% power of ten (via dirty trick) 348 | \let\~=\oct \let\^=\hex {#1}$}} 349 | \def\U{\note{This code is used in section}} % xref for use of a section 350 | \def\Us{\note{This code is used in sections}} % xref for uses of a section 351 | \let\V=\lor % logical or 352 | \let\W=\land % logical and 353 | \def\X#1:#2\X{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi %$% section name 354 | \XX$\langle\,${\let\I=\ne#2\eightrm\kern.5em 355 | \ifacro{\pdfnote#1.}\else#1\fi}$\,\rangle$\XX} 356 | \def\Y{\par\yskip} 357 | \let\Z=\le 358 | \let\ZZ=\let % now you can \write the control sequence \ZZ 359 | \let\*=* 360 | 361 | \def\Xand{\W} \def\Xandxeq{\MRL{{\AND}{\K}}} \def\Xbitand{\AND} 362 | \def\Xbitor{\OR} \def\Xcompl{\CM} \def\Xnot{\R} \def\Xnotxeq{\I} \def\Xor{\V} 363 | \def\Xorxeq{\MRL{{\OR}{\K}}} \def\Xxor{\XOR} \def\Xxorxeq{\MRL{{\XOR}{\K}}} 364 | 365 | %\def\oct{\hbox{\rm\char'23\kern-.2em\it\aftergroup\?\aftergroup}} % WEB style 366 | %\def\hex{\hbox{\rm\char"7D\tt\aftergroup}} % WEB style 367 | \def\oct{\hbox{$^\circ$\kern-.1em\it\aftergroup\?\aftergroup}}% CWEB style 368 | \def\hex{\hbox{$^{\scriptscriptstyle\#}$\tt\aftergroup}} % CWEB style 369 | \def\vb#1{\leavevmode\hbox{\kern2pt\vrule\vtop{\vbox{\hrule 370 | \hbox{\strut\kern2pt\.{#1}\kern2pt}} 371 | \hrule}\vrule\kern2pt}} % verbatim string 372 | 373 | \def\onmaybe{\let\ifon=\maybe} \let\maybe=\iftrue 374 | \newif\ifon \newif\iftitle \newif\ifpagesaved 375 | 376 | \newif\ifheader 377 | \def\lheader{\headertrue\mainfont\the\pageno\eightrm\qquad\grouptitle 378 | \hfill\title\qquad\mainfont\topsecno} % top line on left-hand pages 379 | \def\rheader{\headertrue\mainfont\topsecno\eightrm\qquad\title\hfill 380 | \grouptitle\qquad\mainfont\the\pageno} % top line on right-hand pages 381 | \def\grouptitle{\let\i=I\let\j=J\uppercase\expandafter{\expandafter 382 | \takethree\topmark}} 383 | \def\topsecno{\expandafter\takeone\topmark} 384 | \def\takeone#1#2#3{#1} 385 | \def\taketwo#1#2#3{#2} 386 | \def\takethree#1#2#3{#3} 387 | \def\nullsec{\eightrm\kern-2em} % the \kern-2em cancels \qquad in headers 388 | 389 | \let\page=\pagebody \raggedbottom 390 | % \def\page{\box255 }\normalbottom % faster, but loses plain TeX footnotes 391 | \def\normaloutput#1#2#3{\ifodd\pageno\hoffset=\pageshift\fi 392 | \shipout\vbox{ 393 | \vbox to\fullpageheight{ 394 | \iftitle\global\titlefalse 395 | \else\hbox to\pagewidth{\vbox to10pt{}\ifodd\pageno #3\else#2\fi}\fi 396 | \vfill#1}} % parameter #1 is the page itself 397 | \global\advance\pageno by1} 398 | 399 | \gtitle={\.{CWEB} output} % this running head is reset by starred sections 400 | \mark{\noexpand\nullsec0{\the\gtitle}} 401 | \def\title{\expandafter\uppercase\expandafter{\jobname}} 402 | \def\topofcontents{\centerline{\titlefont\title}\vskip.7in 403 | \vfill} % this material will start the table of contents page 404 | \def\startpdf{\ifpdftex\pdfcatalog{/PageMode /UseOutlines}\else 405 | \ifpdf{\special{pdf: docview << /PageMode /UseOutlines >>}}\fi\fi} 406 | \def\botofcontents{\vfill 407 | \centerline{\covernote}} % this material will end the table of contents page 408 | \def\covernote{} 409 | \def\contentspagenumber{0} % default page number for table of contents 410 | \newdimen\pagewidth \pagewidth=6.5in % the width of each page 411 | \newdimen\pageheight \pageheight=8.7in % the height of each page 412 | \newdimen\fullpageheight \fullpageheight=9in % page height including headlines 413 | \newdimen\pageshift \pageshift=0in % shift righthand pages wrt lefthand ones 414 | \def\magnify#1{\mag=#1\pagewidth=6.5truein\pageheight=8.7truein 415 | \fullpageheight=9truein\setpage} 416 | \def\setpage{\hsize\pagewidth\vsize\pageheight} % use after changing page size 417 | \def\contentsfile{\jobname.toc} % file that gets table of contents info 418 | \def\readcontents{\input \contentsfile} 419 | \def\readindex{\input \jobname.idx} 420 | \def\readsections{\input \jobname.scn} 421 | 422 | \newwrite\cont 423 | \output{\setbox0=\page % the first page is garbage 424 | \openout\cont=\contentsfile 425 | \write\cont{\catcode `\noexpand\@=11\relax} % \makeatletter 426 | \global\output{\normaloutput\page\lheader\rheader}} 427 | \setpage 428 | \vbox to \vsize{} % the first \topmark won't be null 429 | 430 | \def\ch{\note{The following sections were changed by the change file:} 431 | \let\*=\relax} 432 | \newbox\sbox % saved box preceding the index 433 | \newbox\lbox % lefthand column in the index 434 | \def\inx{\par\vskip6pt plus 1fil % we are beginning the index 435 | \def\page{\box255 } \normalbottom 436 | \write\cont{} % ensure that the contents file isn't empty 437 | \write\cont{\catcode `\noexpand\@=12\relax} % \makeatother 438 | \closeout\cont % the contents information has been fully gathered 439 | \output{\ifpagesaved\normaloutput{\box\sbox}\lheader\rheader\fi 440 | \global\setbox\sbox=\page \global\pagesavedtrue} 441 | \pagesavedfalse \eject % eject the page-so-far and predecessors 442 | \setbox\sbox\vbox{\unvbox\sbox} % take it out of its box 443 | \vsize=\pageheight \advance\vsize by -\ht\sbox % the remaining height 444 | \hsize=.5\pagewidth \advance\hsize by -10pt 445 | % column width for the index (20pt between cols) 446 | \parfillskip 0pt plus .6\hsize % try to avoid almost empty lines 447 | \def\lr{L} % this tells whether the left or right column is next 448 | \output{\if L\lr\global\setbox\lbox=\page \gdef\lr{R} 449 | \else\normaloutput{\vbox to\pageheight{\box\sbox\vss 450 | \hbox to\pagewidth{\box\lbox\hfil\page}}}\lheader\rheader 451 | \global\vsize\pageheight\gdef\lr{L}\global\pagesavedfalse\fi} 452 | \message{Index:} 453 | \parskip 0pt plus .5pt 454 | \outer\def\I##1, ##2.{\par\hangindent2em\noindent##1:\kern1em 455 | \ifacro\pdfnote##2.\else##2\fi.} % index entry 456 | \def\[##1]{$\underline{##1}$} % underlined index item 457 | \rm \rightskip0pt plus 2.5em \tolerance 10000 \let\*=\lapstar 458 | \hyphenpenalty 10000 \parindent0pt 459 | \readindex} 460 | \def\fin{\par\vfill\eject % this is done when we are ending the index 461 | \ifpagesaved\null\vfill\eject\fi % output a null index column 462 | \if L\lr\else\null\vfill\eject\fi % finish the current page 463 | \parfillskip 0pt plus 1fil 464 | \def\grouptitle{NAMES OF THE SECTIONS} 465 | \let\topsecno=\nullsec 466 | \message{Section names:} 467 | \output={\normaloutput\page\lheader\rheader} 468 | \setpage 469 | \def\note##1##2.{\quad{\eightrm##1~\ifacro{\pdfnote##2.}\else{##2}\fi.}} 470 | \def\Q{\note{Cited in section}} % crossref for mention of a section 471 | \def\Qs{\note{Cited in sections}} % crossref for mentions of a section 472 | \def\U{\note{Used in section}} % crossref for use of a section 473 | \def\Us{\note{Used in sections}} % crossref for uses of a section 474 | \def\I{\par\hangindent 2em}\let\*=* 475 | \ifacro \def\outsecname{Names of the sections} \let\Xpdf\X 476 | \ifpdftex \makebookmarks \pdfdest name {NOS} fitb 477 | \pdfoutline goto name {NOS} count -\secno {\outsecname} 478 | \def\X##1:##2\X{\Xpdf##1:##2\X \firstsecno##1.% 479 | {\toksF={}\makeoutlinetoks##2\outlinedone\outlinedone}% 480 | \pdfoutline goto num \the\toksA \expandafter{\the\toksE}} 481 | \else\ifpdf 482 | \special{pdf: outline -1 << /Title (\outsecname) 483 | /Dest [ @thispage /FitH @ypos ] >>} 484 | \def\X##1:##2\X{\Xpdf##1:##2\X \firstsecno##1.% 485 | {\toksF={}\makeoutlinetoks##2\outlinedone\outlinedone}% 486 | \special{pdf: outline 0 << /Title (\the\toksE) 487 | /A << /S /GoTo /D (\romannumeral\the\toksA) >> >>}} 488 | \fi\fi\fi 489 | \readsections} 490 | \def\makebookmarks{\let\ZZ=\writebookmarkline \readcontents\relax} 491 | \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% 492 | \else \csname#1\endcsname \fi} % Petr Olsak's macros from texinfo.tex 493 | \def\advancenumber#1{\countA=\expnumber{#1}\relax \advance\countA by1 494 | \expandafter\xdef\csname#1\endcsname{\the\countA}} 495 | \def\writebookmarkline#1#2#3#4#5{{% 496 | \let\(=\let \let\)=\let \let\[=\let \let\]=\let \let\/=\let 497 | \pdfoutline goto num #3 count -\expnumber{chunk#2.#3} {#5}}} 498 | \def\con{\par\vfill\eject % finish the section names 499 | % \ifodd\pageno\else\titletrue\null\vfill\eject\fi % for duplex printers 500 | \rightskip 0pt \hyphenpenalty 50 \tolerance 200 501 | \setpage \output={\normaloutput\page\lheader\rheader} 502 | \titletrue % prepare to output the table of contents 503 | \pageno=\contentspagenumber 504 | \def\grouptitle{TABLE OF CONTENTS} 505 | \message{Table of contents:} 506 | \topofcontents \startpdf 507 | \line{\hfil Section\hbox to3em{\hss Page}} 508 | \let\ZZ=\contentsline 509 | \readcontents\relax % read the contents info 510 | \botofcontents \end} % print the contents page(s) and terminate 511 | \def\contentsline#1#2#3#4#5{\ifnum#2=0 \smallbreak\fi 512 | \line{\consetup{#2}#1 513 | \rm\leaders\hbox to .5em{.\hfil}\hfil 514 | \ \ifacro\pdflink{#3}{\romannumeral#3}\else#3\fi\hbox to3em{\hss#4}}} 515 | \def\consetup#1{\ifcase#1 \bf % depth -1 (@**) 516 | \or % depth 0 (@*) 517 | \or \hskip2em % depth 1 (@*1) 518 | \or \hskip4em \or \hskip6em \or \hskip8em \or \hskip10em % depth 2,3,4,5 519 | \else \hskip12em \fi} % depth 6 or more 520 | \def\noinx{\let\inx=\end} % no indexes or table of contents 521 | \def\nosecs{\let\FIN=\fin \def\fin{\let\parfillskip=\end \FIN}} 522 | % no index of section names or table of contents 523 | \def\nocon{\let\con=\end} % no table of contents 524 | \def\today{\ifcase\month\or 525 | January\or February\or March\or April\or May\or June\or 526 | July\or August\or September\or October\or November\or December\fi 527 | \space\number\day, \number\year} 528 | \newcount\twodigits 529 | \def\hours{\twodigits=\time \divide\twodigits by 60 \printtwodigits 530 | \multiply\twodigits by-60 \advance\twodigits by\time :\printtwodigits} 531 | \def\gobbleone1{} 532 | \def\printtwodigits{\advance\twodigits100 533 | \expandafter\gobbleone\number\twodigits 534 | \advance\twodigits-100 } 535 | \def\TeX{{\ifmmode\it\fi 536 | \leavevmode\hbox{T\kern-.1667em\lower.424ex\hbox{E}\hskip-.125em X}}} 537 | \def\,{\relax\ifmmode\mskip\thinmuskip\else\thinspace\fi} 538 | \def\datethis{\def\startsection{\leftline{\sc\today\ at \hours}\bigskip 539 | \let\startsection=\stsec\stsec}} 540 | % say `\datethis' in limbo, to get your listing timestamped before section 1 541 | %\def\datecontentspage{% versions up to 3.65 542 | % \def\topofcontents{\leftline{\sc\today\ at \hours}\bigskip 543 | % \centerline{\titlefont\title}\vfill}} % timestamps the contents page 544 | \def\datecontentspage{% changed in version 3.66 545 | \def\botofcontents{\vfill 546 | \centerline{\covernote} 547 | \bigskip 548 | \leftline{\sc\today\ at \hours}}} % timestamps the contents page 549 | 550 | %%%% 551 | %% Some macros that are special for ChezWEB 552 | 553 | \font\smtt=cmtt8 554 | 555 | \def\CAP{\note{This section captures}}% For the captures line. 556 | \def\EXP{\note{This section exports}}% For the exports line. 557 | 558 | %%%% 559 | %% We setup the verbatim mode 560 | 561 | %Author: C.G. van der Laan, Hunzeweg 57, 9893PB 562 | % Garnwerd, The Netherlands 563 | % 05941-1525, cgl@risc1.rug.nl. 564 | %Purpose: Verbatim macros via plain TeX, 565 | % to be used with AnyTeX. 566 | % *numvrb 567 | %User toks variables 568 | \newtoks\thisverbatim 569 | \newtoks\everyverbatim 570 | % 571 | %User customization 572 | %\let\preverbatim 573 | %\let\postverbatim 574 | % *vrblin100 575 | %User `options': \numvrb 576 | \newcount\vrblin 577 | \def\numvrb{\vrblin0 578 | \everypar{\advance\vrblin1 579 | \llap{\sevenrm\the\vrblin\quad}}} 580 | \def\nonum{\everypar={}} 581 | % : \emc 582 | \def\makeescape#1{\catcode`#1=0 } 583 | \def\makeactive#1{\catcode`#1=13 } 584 | {\makeactive\< 585 | \gdef\emc{\makeactive\<% 586 | \def<##1>{$\langle##1\rangle$}}} 587 | % *vrblin200 588 | %User macro 589 | \def\verbatim{\begingroup%\preverbatim\begingroup 590 | \tt\setupverbatim 591 | \the\everyverbatim\relax 592 | \the\thisverbatim\relax 593 | \verbatimgobble} 594 | % 595 | \def\endverbatim{\endgroup%\postverbatim 596 | \thisverbatim={}} 597 | % 598 | \def\setupverbatim{\makeactive\`% 599 | \let\!=!\makeescape\!%Knuth&Levy 600 | \def\par{\leavevmode\endgraf}%TB381 601 | \obeylines\uncatcodespecials 602 | \obeyspaces} 603 | % 604 | {\obeyspaces\global\let =\ 605 | \obeylines\gdef\verbatimgobble#1^^M{}% 606 | \makeactive\` \gdef`{\relax\lq}}%TB381 607 | % 608 | \def\uncatcodespecials{\def\do##1{% 609 | \catcode`##1=12 }\dospecials} 610 | % *vrblin250 611 | %Minimal | tag for inline verbatim 612 | \def\vrt{{\tt\char`\|}}\makeactive\| 613 | \def|{\bgroup\tt\setupverbatim 614 | \the\everyverbatim\relax 615 | \the\thisverbatim\relax 616 | \def|{\egroup\thisverbatim={}}} 617 | 618 | % \endinput %14/2/94 cgl@risc1.rug.nl 619 | 620 | -------------------------------------------------------------------------------- /config.mk.template: -------------------------------------------------------------------------------- 1 | PREFIX=/usr/local 2 | MACHINE=ta6le 3 | TEXDIR=/usr/share/texmf-local 4 | DOCDIR=/usr/doc/chezweb-${VERSION} 5 | BINDIR=${PREFIX}/bin 6 | LIBDIR=${PREFIX}/lib64/chezweb 7 | OWNER=root 8 | GROUP=root 9 | -------------------------------------------------------------------------------- /contrib/iu-chezweb: -------------------------------------------------------------------------------- 1 | #! /bin/ksh 2 | 3 | set -e 4 | 5 | mkdir -p $HOME/bin $HOME/texmf/tex/generic 6 | ln -sf /nobackup/awhsu/ChezWEB/cheztangle $HOME/bin/cheztangle 7 | ln -sf /nobackup/awhsu/ChezWEB/chezweave $HOME/bin/chezweave 8 | ln -sf /nobackup/awhsu/ChezWEB/chezwebmac.tex $HOME/texmf/tex/generic/ 9 | texhash 10 | 11 | echo "ChezWEB installed successfully!" 12 | -------------------------------------------------------------------------------- /doc/cwebman.tex: -------------------------------------------------------------------------------- 1 | % This file generates the user manual; TeX it, don't read it! 2 | 3 | \def\tangref{3} % where the main explanation of CTANGLing is given 4 | \input cwebmac 5 | \acrofalse\pdffalse\pdftexfalse 6 | \def\page{\box255 } \normalbottom 7 | \parskip 0pt plus 1pt 8 | \def\RA{\char'31 } % right arrow 9 | \def\hang{\hangindent 4em\ignorespaces} 10 | \font\eightrm=cmr8 11 | \font\ninerm=cmr9 12 | \font\ninett=cmtt9 13 | \font\eighttt=cmtt8 14 | \font\twelvett=cmtt12 15 | \font\quoterm=cmssq8 16 | \font\quoteit=cmssqi8 17 | \font\authorfont=cmr12 18 | \font\sectionfont=cmbx12 19 | 20 | \def\pb{\.{|...|}} 21 | \def\v{\.{\char'174}} % vertical (|) in typewriter font 22 | \def\lpile{\def\cr{\hfill\endline}\matrix} % I only use \lpile by itself 23 | \abovedisplayskip=.5\abovedisplayskip 24 | \belowdisplayskip=.5\belowdisplayskip 25 | \abovedisplayshortskip=.5\abovedisplayshortskip 26 | \belowdisplayshortskip=.5\belowdisplayshortskip 27 | \advance\baselineskip by -.5pt 28 | \advance\pageheight by \baselineskip % the manual just got a bit longer 29 | \advance\fullpageheight by \baselineskip 30 | \setpage 31 | 32 | \outer\def\section #1.{\penalty-500\bigskip 33 | \centerline{\sectionfont\def\.##1{{\twelvett##1}} #1}\nobreak\vskip 6pt 34 | \everypar{\hskip-\parindent\everypar{}}} 35 | 36 | \def\lheader{\mainfont\the\pageno\hfill\sc\runninghead\hfill} 37 | \def\rheader{\hfill\sc\runninghead\hfill\mainfont\the\pageno} 38 | \def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 3.64)} 39 | 40 | % This verbatim mode assumes that ! marks are !! in the text being copied. 41 | \def\verbatim{\begingroup 42 | \def\do##1{\catcode`##1=12 } \dospecials 43 | \parskip 0pt \parindent 0pt \let\!=! 44 | \catcode`\ =13 \catcode`\^^M=13 45 | \tt \catcode`\!=0 \verbatimdefs \verbatimgobble} 46 | {\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} % 47 | \gdef\verbatimgobble#1^^M{}} 48 | 49 | \null\vfill 50 | \centerline{\titlefont The {\ttitlefont CWEB} System of 51 | Structured Documentation} 52 | \vskip 18pt\centerline{(Version 3.64 --- February 2002)} 53 | \vskip 24pt 54 | \centerline{\authorfont Donald E. Knuth and Silvio Levy} 55 | \vfill 56 | 57 | \noindent 58 | \TeX\ is a trademark of the American Mathematical Society. 59 | 60 | \noindent 61 | Acrobat Reader is a trademark of Adobe Systems Incorporated. 62 | 63 | \bigskip\noindent 64 | The printed form of this manual is copyright \copyright\ 1994 65 | by Addison-Wesley Publishing Company, Inc. All rights reserved. 66 | \smallskip\noindent 67 | The electronic form is copyright \copyright\ 1987, 1990, 1993, 2000 68 | by Silvio Levy and Donald E. Knuth. 69 | 70 | \bigskip\noindent 71 | Permission is granted to make and distribute verbatim copies of the 72 | electronic form of this document provided that the electronic copyright 73 | notice and this permission notice are preserved on all copies. 74 | 75 | \smallskip\noindent 76 | Permission is granted to copy and distribute modified versions of the 77 | electronic form of this document under the conditions for verbatim copying, 78 | provided that the entire resulting derived work is distributed under the terms 79 | of a permission notice identical to this one. 80 | 81 | \smallskip\noindent 82 | Individuals may make copies of the documentation from the electronic files 83 | for their own personal use. 84 | 85 | \smallskip\noindent 86 | Internet page \.{http://www-cs-faculty.stanford.edu/\char`\~knuth/cweb.html} 87 | contains current info about \.{CWEB} and related topics. 88 | 89 | \pageno=0 \titletrue\eject 90 | 91 | \titletrue 92 | \centerline{\titlefont The {\ttitlefont CWEB} System of 93 | Structured Documentation} 94 | 95 | \vskip 15pt plus 3pt minus 3pt 96 | \centerline{\authorfont Donald E. Knuth and Silvio Levy} 97 | 98 | \vskip 24pt plus 3pt minus 3pt 99 | \noindent 100 | This document describes a version of Don Knuth's \.{WEB} system, 101 | adapted to \CEE/ by Silvio Levy. Since its creation in 1987, \.{CWEB} 102 | has been revised and enhanced in various ways, by both Knuth and Levy. 103 | We now believe that its evolution is near an end; however, bug 104 | reports, suggestions and comments are still welcome, and 105 | should be sent to Levy (\.{levy@math.berkeley.edu}). 106 | 107 | Readers who are familiar with Knuth's memo ``The \.{WEB} System of Structured 108 | Documentation'' will be able 109 | to skim this material rapidly, because \.{CWEB} and \.{WEB} share 110 | the same philosophy and (essentially) the same syntax. In some respects 111 | \.{CWEB} is a simplification 112 | of \.{WEB}: for example, \.{CWEB} does not need \.{WEB}'s features 113 | for macro definition and string handling, because \CEE/ and its 114 | preprocessor already take care of macros and strings. Similarly, the \.{WEB} 115 | conventions of denoting octal and hexadecimal constants by \.{@'77} 116 | and \.{@"3f} are replaced by \CEE/'s conventions \.{077} and 117 | \.{0x3f}. All other features of \.{WEB} have been 118 | retained, and new features have been added. 119 | 120 | We thank all who contributed suggestions and criticism to 121 | the development of \.{CWEB}. We are especially grateful to Steve 122 | Avery, Nelson Beebe, Hans-Hermann Bode, Klaus Guntermann, Norman Ramsey, 123 | Joachim Schnitter, and Saroj Mahapatra, 124 | who contributed code, and to Cameron Smith, who 125 | made many suggestions improving the manual. Ramsey has made 126 | literate programming accessible to users of yet other languages by means of 127 | his \.{SPIDER} system [see {\sl Communications of the ACM\/ \bf32} (1989), 128 | 1051--1055]. The book {\sl Literate Programming\/} by Knuth (1992) contains 129 | a comprehensive bibliography of related early work. 130 | Bode, Schnitter, and Mahapatra adapted \.{CWEB} so that it works 131 | for \CPLUSPLUS/ as well; therefore in the text below you can read \CPLUSPLUS/ 132 | for \CEE/ if you so desire. 133 | 134 | \section Introduction. 135 | The philosophy behind \.{CWEB} is 136 | that programmers who want to provide the best 137 | possible documentation for their programs need two things 138 | simultaneously: a language like \TEX/ for formatting, and a language like 139 | \CEE/ for programming. Neither type of language can provide the 140 | best documentation by itself. But when both are appropriately combined, we 141 | obtain a system that is much more useful than either language separately. 142 | 143 | The structure of a software program may be thought of as a ``web'' that is 144 | made up of many interconnected pieces. To document such a program, we want 145 | to explain each individual part of the web and how it relates to its 146 | neighbors. The typographic tools provided by \TEX/ give us an opportunity 147 | to explain the local structure of each part by making that structure 148 | visible, and the programming tools provided by \CEE/ make it possible 149 | for us to specify the algorithms formally and unambiguously. By combining 150 | the two, we can develop a style of programming that maximizes our ability 151 | to perceive the structure of a complex piece of software, and at the same 152 | time the documented programs can be mechanically translated into a working 153 | software system that matches the documentation. 154 | 155 | The \.{CWEB} system consists of two programs named \.{CWEAVE} and \.{CTANGLE}. 156 | When writing a \.{CWEB} program the user keeps the 157 | \CEE/ code and the documentation in the same file, called the \.{CWEB} 158 | file and generally named \.{something.w}. The command 159 | `\.{cweave} \.{something}' creates an output file \.{something.tex}, which 160 | can then be fed to \TEX/, yielding a ``pretty printed'' version of 161 | \.{something.w} that correctly handles 162 | typographic details like page layout and the use of indentation, 163 | italics, boldface, and mathematical symbols. The typeset output also 164 | includes extensive cross-index 165 | information that is gathered automatically. Similarly, if you run the 166 | command `\.{ctangle} \.{something}' you will get a \CEE/ file \.{something.c}, 167 | which can then be compiled to yield executable code. 168 | 169 | Besides providing a documentation tool, \.{CWEB} enhances the \CEE/ 170 | language by providing the 171 | ability to permute pieces of the program text, so that a large system can 172 | be understood entirely in terms of small sections and their local 173 | interrelationships. The \.{CTANGLE} program is so named because it takes a 174 | given web and moves the sections from their web structure into the order 175 | required by \CEE/; the advantage of programming in \.{CWEB} is that the 176 | algorithms can be expressed in ``untangled'' form, with each section 177 | explained separately. The \.{CWEAVE} program is so named because it takes 178 | a given web and intertwines the \TEX/ and \CEE/ portions contained in 179 | each section, then it knits the whole fabric into a structured document. 180 | (Get it? Wow.) Perhaps there is some deep connection here with the fact 181 | that the German word for ``weave'' is ``{\it webe\/}'', and the 182 | corresponding Latin imperative is ``{\it texe\/}''! 183 | 184 | A user of \.{CWEB} should be fairly familiar with the \CEE/ 185 | programming language. A minimal amount of acquaintance with \TEX/ is also 186 | desirable, but in fact it can be acquired as one uses \.{CWEB}, since 187 | straight text can be typeset in \TEX/ with virtually no knowledge of 188 | that language. To someone familiar with both \CEE/ and \TEX/ the amount of 189 | effort necessary to learn the commands of \.{CWEB} is small. 190 | 191 | \section Overview. 192 | Two kinds of material go into \.{CWEB} files: \TEX/ text and \CEE/ text. 193 | A programmer writing in \.{CWEB} should be thinking both of the 194 | documentation and of the \CEE/ program being created; 195 | i.e., the programmer should be instinctively aware of the different 196 | actions that \.{CWEAVE} and \.{CTANGLE} will perform on the \.{CWEB} file. 197 | \TEX/ text is essentially copied without change by \.{CWEAVE}, and it is 198 | entirely deleted by \.{CTANGLE}; the \TEX/ text is ``pure 199 | documentation.'' \CEE/ text, on the other hand, is formatted by 200 | \.{CWEAVE} and it is shuffled around by \.{CTANGLE}, according to rules that 201 | will become clear later. For now the important point to keep in mind is 202 | that there are two kinds of text. Writing \.{CWEB} programs is something 203 | like writing \TEX/ documents, but with an additional ``\CEE/ mode'' 204 | that is added to \TEX/'s horizontal mode, vertical mode, and math mode. 205 | 206 | A \.{CWEB} file is built up from units called {\sl sections\/} that are more 207 | or less self-contained. Each section has three parts: 208 | 209 | \yskip\item{$\bullet$} A \TEX/ part, containing explanatory material about what 210 | is going on in the section. 211 | 212 | \item{$\bullet$} A middle part, containing macro definitions that serve as 213 | abbreviations for \CEE/ constructions that would be less comprehensible 214 | if written out in full each time. They are turned by \.{CTANGLE} into 215 | preprocessor macro definitions. 216 | 217 | \item{$\bullet$} A \CEE/ part, containing a piece of the program that 218 | \.{CTANGLE} will produce. This \CEE/ code should ideally be about a 219 | dozen lines long, so that it is easily comprehensible as a unit and so 220 | that its structure is readily perceived. 221 | 222 | \yskip\noindent The three parts of each section must appear in this order; 223 | i.e., the \TEX/ commentary must come first, then the middle part, and 224 | finally the \CEE/ code. Any of the parts may be empty. 225 | 226 | A section begins with either of the symbols `\.{@\ }' or `\.{@*}', where 227 | `\.{\ }' denotes a blank space. A section ends 228 | at the beginning of the next section (i.e., at the next 229 | `\.{@\ }' or `\.{@*}'), or at the end of the file, whichever comes first. 230 | The \.{CWEB} file may also contain material that is not part of any section 231 | at all, namely the text (if any) that occurs before the first section. 232 | Such text is said to be ``in limbo''; it is ignored by \.{CTANGLE} 233 | and copied essentially verbatim by \.{CWEAVE}, so its function is to 234 | provide any additional formatting instructions that may be desired in the 235 | \TEX/ output. Indeed, it is customary to begin a \.{CWEB} file with 236 | \TEX/ code in limbo that loads special fonts, defines special macros, 237 | changes the page sizes, and/or produces a title page. 238 | 239 | Sections are numbered consecutively, starting with 1. These numbers appear 240 | at the beginning of each section of the \TEX/ documentation output by 241 | \.{CWEAVE}, and they appear 242 | as bracketed comments at the beginning and end of the code generated by that 243 | section in the \CEE/ program output by \.{CTANGLE}. 244 | 245 | \section Section Names. 246 | Fortunately, you never mention these numbers yourself when you are writing 247 | in \.{CWEB}. You just say `\.{@\ }' or `\.{@*}' at the beginning of each 248 | new section, and the numbers are supplied automatically by \.{CWEAVE} and 249 | \.{CTANGLE}. As far as you are concerned, a section has a 250 | {\sl name\/} instead of a number; its name is specified by writing 251 | `\.{@<}' followed by \TEX/ text followed by `\.{@>}'. When \.{CWEAVE} 252 | outputs a section name, it replaces the `\.{@<}' and `\.{@>}' by 253 | angle brackets and inserts the section number in small type. Thus, when you 254 | read the output of \.{CWEAVE} it is easy to locate any section that is 255 | referred to in another section. 256 | 257 | For expository purposes, a section name should be a good description of the 258 | contents of that section; i.e., it should stand for the abstraction 259 | represented by the section. Then the section can be ``plugged into'' one or 260 | more other sections in such a way 261 | that unimportant details of its inner workings 262 | are suppressed. A section name therefore ought to be long enough to convey 263 | the necessary meaning. 264 | 265 | Unfortunately, it is laborious to type 266 | such long names over and over again, and it is also difficult to specify a 267 | long name twice in exactly the same way so that \.{CWEAVE} and \.{CTANGLE} 268 | will be able to match the names to the sections. To ameliorate this situation, 269 | \.{CWEAVE} and \.{CTANGLE} let you abbreviate a section name, so long as 270 | the full name appears somewhere in the \.{CWEB} file; you can type simply 271 | `\.{@<$\alpha$...@>}', where $\alpha$ is any string that is a prefix of 272 | exactly one section name appearing in the file. For example, `\.{@}' can be abbreviated to `\.{@}' if no other section 274 | name begins with the five letters `\.{Clear}'. Elsewhere 275 | you might use the abbreviation `\.{@}', and so on. 276 | 277 | Section names must otherwise match character for character, except 278 | that consecutive characters of white space (spaces, tab marks, newlines, and/or 279 | form feeds) are treated as equivalent to a single space, and such spaces are 280 | deleted at the beginning and end of the name. Thus, `\.{@< Clear { }the 281 | arrays @>}' will also match the name in the previous example. 282 | Spaces following the ellipsis in abbreviations are ignored as well, but 283 | not those before, so that `\.{@}' would not match 284 | `\.{@}'. 285 | 286 | \section What \.{CTANGLE} Does. 287 | We have said that a section begins with `\.{@\ }' or `\.{@*}', but we 288 | didn't say how it gets divided up into a \TEX/ part, a middle part, 289 | and a \CEE/ part. The middle part begins with the first appearance of 290 | `\.{@d}' or `\.{@f}' in the section, and the \CEE/ part begins with 291 | the first appearance of `\.{@c}' or `\.{@
=}'. In the 292 | latter case you are saying, in effect, that the section name stands 293 | for the \CEE/ text that follows. Alternatively, if the \CEE/ part 294 | begins with `\.{@c}' instead of a section name, the current section is 295 | said to be {\sl unnamed}. 296 | 297 | The construct `\.{@
}' can appear 298 | any number of times in the \CEE/ part of a section: 299 | Subsequent appearances indicate that a named section is being 300 | ``used'' rather than ``defined.'' In other words, the 301 | \CEE/ code for the named section, presumably defined elsewhere, should be 302 | spliced in at this point in the \CEE/ program. Indeed, 303 | the main idea of \.{CTANGLE} is to make a \CEE/ program out of 304 | individual sections, named and unnamed. The exact way in which this is done 305 | is this: First all the macro definitions 306 | indicated by `\.{@d}' are turned into \CEE/ preprocessor macro definitions 307 | and copied at the beginning. 308 | Then the \CEE/ parts of unnamed sections are copied down, 309 | in order; this constitutes the first-order 310 | approximation to the text of the program. (There should be at least 311 | one unnamed section, otherwise there will be no program.) Then all section 312 | names that appear in the first-order approximation are replaced by the \CEE/ 313 | parts of the corresponding sections, and this substitution process 314 | continues until no section names remain. All comments are removed, because 315 | the \CEE/ program is intended only for the eyes of the \CEE/ compiler. 316 | 317 | If the same name has been given to more than one section, the \CEE/ text 318 | for that name is obtained by putting together all of the \CEE/ parts in 319 | the corresponding sections. This feature is useful, for example, in a 320 | section named `Global variables', since one can then 321 | declare global variables in whatever sections those variables are 322 | introduced. When several sections have the same name, \.{CWEAVE} assigns the 323 | first section number as the number corresponding to that name, and it 324 | inserts a note at the bottom of that section telling the reader to `See 325 | also sections so-and-so'; this footnote gives the numbers of all the other 326 | sections having the same name as the present one. The \CEE/ text 327 | corresponding to a section is usually formatted by \.{CWEAVE} so that the 328 | output has an equivalence sign in place of the equals sign in the \.{CWEB} 329 | file; i.e., the output says `$\langle\,$section 330 | name$\,\rangle\equiv\null$\CEE/ text'. However, in the case of the second 331 | and subsequent appearances of a section with the same name, this `$\equiv$' 332 | sign is replaced by `$\mathrel+\equiv$', as an indication that the 333 | following \CEE/ text is being appended to the \CEE/ text of another section. 334 | 335 | As \.{CTANGLE} enters and leaves sections, it inserts preprocessor 336 | \.{\#line} commands into the \CEE/ output file. This means that 337 | when the compiler gives you error messages, or when you debug your program, 338 | the messages refer to line numbers in the \.{CWEB} file, and not in the 339 | \CEE/ file. In most cases you can therefore 340 | forget about the \CEE/ file altogether. 341 | 342 | \section What \.{CWEAVE} Does. 343 | The general idea of \.{CWEAVE} is to make a \.{.tex} file from the \.{CWEB} 344 | file in the following way: The first line of the \.{.tex} file 345 | tells \TEX/ to input a file with macros that 346 | define \.{CWEB}'s documentation conventions. The next lines of the file 347 | will be copied from whatever \TEX/ text is in limbo before the first 348 | section. Then comes the output for each section in turn, possibly 349 | interspersed with end-of-page marks. Finally, \.{CWEAVE} will generate a 350 | cross-reference index that lists each section number in which each \CEE/ 351 | identifier appears, and it will also generate an alphabetized list 352 | of the section names, as well as a table of contents that 353 | shows the page and section numbers for each ``starred'' section. 354 | 355 | What is a ``starred'' section, you ask? A section that begins with `\.{@*}' 356 | instead of `\.{@\ }' is slightly special in that it denotes a new major 357 | group of sections. The `\.{@*}' should be followed by the title of this 358 | group, followed by a period. Such sections will always start on a new page 359 | in the \TEX/ output, and the group title will appear as a running headline 360 | on all subsequent pages until the next starred section. The title will also 361 | appear in the table of contents, and in boldface type at the beginning of 362 | its section. Caution: Do not use \TEX/ control sequences in such titles, 363 | unless you know that the \.{cwebmac} macros will do the right thing with 364 | them. The reason is that these titles are converted to uppercase when 365 | they appear as running heads, and they are converted to boldface when they 366 | appear at the beginning of their sections, and they are also written out to 367 | a table-of-contents file used for temporary storage while \TEX/ is 368 | working; whatever control sequences you use must be meaningful in all 369 | three of these modes. 370 | 371 | The \TEX/ output produced by \.{CWEAVE} for each section consists of 372 | the following: First comes the section number (e.g., `\.{\\M123.}' 373 | at the beginning of section 123, except that `\.{\\N}' appears in place of 374 | `\.{\\M}' at the beginning of a starred section). Then comes the 375 | \TEX/ part of the section, copied almost verbatim except as noted 376 | below. Then comes the middle part and the \CEE/ part, formatted 377 | so that there will be a little extra space between them if both are 378 | nonempty. The middle and \CEE/ parts are obtained by inserting 379 | a bunch of funny-looking \TEX/ macros into the \CEE/ program; these 380 | macros handle typographic details about fonts and proper math spacing, 381 | as well as line breaks and indentation. 382 | 383 | \section C Code in \TEX/ Text and Vice Versa. 384 | When you are typing \TEX/ text, you will probably want to make frequent 385 | reference to variables and other quantities in your \CEE/ code, and you 386 | will want those variables to have the same typographic treatment 387 | when they appear in your text as when they appear in your 388 | program. Therefore the \.{CWEB} language allows you to get the effect of 389 | \CEE/ editing within \TEX/ text, if you place `\.|' marks before and 390 | after the \CEE/ material. For example, suppose you want to say something 391 | like this: 392 | $$\hbox{ If \\{pa} is declared as `\&{int} ${}{*}\\{pa}$', 393 | the assignment $\\{pa}\K{\AND}\|a[\T{0}]$ makes \\{pa} 394 | point to the zeroth element of \|a.}$$ 395 | The \TEX/ text would look like this in your \.{CWEB} file: 396 | $$\lpile{\.{If |pa| is declared as `|int *pa|', the}\cr 397 | \.{assignment |pa=\&a[0]| makes |pa| point 398 | to the zeroth element of |a|.}\cr}$$ 399 | And \.{CWEAVE} translates this into something you are glad you didn't have 400 | to type: 401 | $$\lpile{\.{If \\\\\{pa\} is declared as 402 | `\\\&\{int\} \$\{\}\{*\}\\\\\{pa\}\$',}\cr 403 | \.{the assignment \$\\\\\{pa\}\\K\{\\AND\}\\|a[\\T\{0\}]\$}\cr 404 | \.{makes \\\\\{pa\} point to the zeroth element of \\|a.}\cr}$$ 405 | Incidentally, the cross-reference index that \.{CWEAVE} would make, in 406 | the presence of a comment like this, would include 407 | the current section number as one of the index entries for \\{pa}, 408 | even though \\{pa} might not appear in the \CEE/ part of 409 | this section. Thus, the index covers references to identifiers in 410 | the explanatory comments as well as in the program itself; you will 411 | soon learn to appreciate this feature. However, the identifiers 412 | \&{int} and \|a\ would not be indexed, 413 | because \.{CWEAVE} does not make index entries for reserved words or 414 | single-letter identifiers. Such identifiers are felt to be so ubiquitous 415 | that it would be pointless to mention every place where they occur. 416 | 417 | Although a section begins with \TEX/ text and ends with \CEE/ text, we 418 | have noted that the dividing line isn't sharp, since \CEE/ text can be 419 | included in \TEX/ text if it is enclosed in `\pb'. Conversely, \TEX/ text 420 | appears frequently within \CEE/ text, because everything in 421 | comments (i.e., between \.{/*} and \.{*/}, or following \.{//}) 422 | is treated as \TEX/ text. 423 | Likewise, the text of a section name consists of \TEX/ text, but 424 | the construct \.{@
} as a whole is expected to be found 425 | in \CEE/ text; thus, one typically goes back and forth 426 | between the \CEE/ and \TEX/ environments in a natural way, as in these 427 | examples: 428 | $$ 429 | \displaylines{ 430 | \hbox{\.{if} \.{(x==0)} \.{@}} \cr 431 | \hbox{\.{...} \.{using} \.{the} \.{algorithm} 432 | \.{in} \.{|@|.}} } 433 | $$ 434 | The first of these excerpts 435 | would be found in the \CEE/ part of a section, into which the code 436 | from the section 437 | named ``Empty the \\{buffer} array'' is being spliced. The second excerpt 438 | would be found in the \TEX/ part of the section, and the named section 439 | is being ``cited'', rather than defined or used. 440 | (Note the `\pb' surrounding the section name in this case.) 441 | 442 | \section Macros. 443 | The control code \.{@d} followed by 444 | $$\\{identifier}\.{ }\hbox{\CEE/ text}\qquad\hbox{or by}\qquad 445 | \\{identifier}\.(\\{par}_1,\ldots,\\{par}_n\.{) }\hbox{\CEE/ text}$$ 446 | (where there is no blank between the 447 | \\{identifier} and the parentheses in the second case) is 448 | transformed by \.{CTANGLE} into a preprocessor command, starting with 449 | \.{\#define}, which is printed at the top of the \CEE/ output file 450 | as explained earlier. 451 | 452 | A `\.{@d}' macro definition can go on for several lines, and the 453 | newlines don't have to be protected by backslashes, since \.{CTANGLE} 454 | itself inserts the backslashes. If 455 | for any reason you need a \.{\#define} command at a specific spot in 456 | your \CEE/ file, you can treat it as \CEE/ code, instead of as a 457 | \.{CWEB} macro; but then you do have to protect newlines yourself. 458 | 459 | \section Strings and constants. 460 | If you want a string to appear in the \CEE/ file, delimited by pairs of 461 | \.' or \." marks as usual, you can type it exactly so in the \.{CWEB} file, 462 | except that the character `\.@' should be typed `\.{@@}' (it becomes a 463 | control code, the only one that can appear in strings; see below). 464 | Strings should end on the same line as they begin, unless there's a 465 | backslash at the end of lines within them. 466 | 467 | \TEX/ and \CEE/ have different ways to refer to octal and hex constants, 468 | because \TEX/ is oriented to technical writing while \CEE/ is oriented to 469 | computer processing. In \TEX/ you 470 | make a constant octal or hexadecimal by prepending \.' or \.", 471 | respectively, to it; in \CEE/ the constant should be preceded by \.0 472 | or \.{0x}. In \.{CWEB} it seems reasonable to let each convention hold 473 | in its respective realm; so in \CEE/ text you get $40_8$ by typing 474 | `\.{040}', which \.{CTANGLE} faithfully copies into the \CEE/ file (for 475 | the compiler's benefit) and which \.{CWEAVE} prints as $\T{\~40}$. 476 | Similarly, \.{CWEAVE} prints the hexadecimal \CEE/ constant `\.{0x20}' 477 | as \T{\^20}. The use of italic font for octal digits and typewriter font 478 | for hexadecimal digits makes the meaning of such constants clearer in 479 | a document. For consistency, then, you 480 | should type `\.{|040|}' or `\.{|0x20|}' 481 | in the \TEX/ part of the section. 482 | 483 | \section Control codes. 484 | A \.{CWEB} {\sl control code\/} 485 | is a two-character combination of which the first is `\.@'. 486 | We've already seen the meaning of several control codes; it's time to 487 | list them more methodically. 488 | 489 | In the following list, 490 | the letters in brackets after a control code indicate in what contexts that 491 | code is allowed. $L$ indicates that the code is allowed in limbo; $T$ 492 | (for \TEX/), $M$ (for middle), and $C$ (for \CEE/) mean that the code is 493 | allowed in each of the three parts of a section, at top level---that 494 | is, outside such constructs as `\pb' and section names. An arrow $\to$ 495 | means that the control code terminates the present part of the \.{CWEB} 496 | file, and inaugurates the part indicated by the letter following the 497 | arrow. Thus $[LTMC\to T]$ next to \.{@\ } indicates that this control 498 | code can occur in limbo, or in any of the three parts of a section, and 499 | that it starts the (possibly empty) \TEX/ part of the following section. 500 | 501 | Two other abbreviations can occur in these brackets: The letter $r$ stands for 502 | {\it restricted context}, that is, material inside \CEE/ comments, section 503 | names, \CEE/ strings and control texts (defined below); the letter 504 | $c$ stands for {\it inner \CEE/ context}, that is, \CEE/ material 505 | inside `\pb' (including `\pb's inside comments, but not those 506 | occurring in other restricted contexts). An asterisk $*$ following 507 | the brackets means 508 | that the context from this control code to the matching \.{@>} is 509 | restricted. 510 | 511 | Control codes involving letters are case-insensitive; thus \.{@d} and 512 | \.{@D} are equivalent. Only the lowercase versions are mentioned 513 | specifically below. 514 | 515 | \gdef\@#1[#2] {\penalty-50\yskip\hangindent 2em\noindent\.{@#1\unskip 516 | \spacefactor1000{ }}$[#2]$\quad} 517 | \def\more{\hangindent 2em \hangafter0} 518 | \def\subsec{\penalty-300\medskip\noindent} 519 | 520 | \@@ [LTMCrc] A double \.@ denotes the single character `\.@'. This is 521 | the only control code that is legal everywhere. 522 | Note that you must use this convention if you are giving an internet 523 | email address in a \.{CWEB} file (e.g., \.{levy@@math.berkeley.edu}). 524 | 525 | \subsec 526 | Here are the codes that introduce the \TEX/ part of a section. 527 | 528 | \@\ [LTMC\to T] This denotes the beginning of a new (unstarred) 529 | section. A tab mark or form feed or 530 | end-of-line character is equivalent to a space when it follows an \.@ 531 | sign (and in most other cases). 532 | 533 | \@* [LTMC\to T] This denotes the beginning of a new starred 534 | section, i.e., a section that begins a new major group. The title of the new 535 | group should appear after the \.{@*}, followed by a period. As explained 536 | above, \TEX/ control sequences should be avoided in such titles unless 537 | they are quite simple. When \.{CWEAVE} and \.{CTANGLE} read a \.{@*}, they 538 | print an asterisk on the terminal 539 | followed by the current section number, so that the user 540 | can see some indication of progress. The very first section should be starred. 541 | 542 | \more You can specify the ``depth'' of a starred section by typing \.* or a 543 | decimal number after the \.{@*}; this indicates the relative ranking 544 | of the current group of sections in the program hierarchy. Top-level 545 | portions of the program, introduced by \.{@**}, get their names typeset 546 | in boldface type in the table of contents; they are said to have 547 | depth~$-1$. Otherwise the depth is a nonnegative number, which governs 548 | the amount of indentation on the contents page. Such indentation helps 549 | clarify the structure of a long program. The depth is assumed to be 0 550 | if it is not specified explicitly; when your program is short, you 551 | might as well leave all depths zero. A starred section always begins 552 | a new page in the output, unless the depth is greater than~1. 553 | 554 | \subsec 555 | The middle part of each section consists of any number of 556 | macro definitions (beginning with \.{@d}) and format definitions (beginning 557 | with \.{@f} or \.{@s}), intermixed in any order. 558 | 559 | \@d [TM\to M] Macro definitions begin with \.{@d}, followed by 560 | an identifier and optional parameters and \CEE/ text as explained earlier. 561 | 562 | \@f [TM\to M] Format definitions begin with \.{@f}; they cause 563 | \.{CWEAVE} to treat identifiers in a special way when they appear in 564 | \CEE/ text. The general form of a format definition is `\.{@f} \|l 565 | \|r', followed by an optional comment enclosed between 566 | \.{/*} and \.{*/}, where \|l and \|r 567 | are identifiers; \.{CWEAVE} will subsequently treat identifier \|l as it 568 | currently treats \|r. This feature allows a \.{CWEB} programmer to invent 569 | new reserved words and/or to unreserve some of \CEE/'s reserved 570 | identifiers. For example, the common words `error' and `line' 571 | have been given a special meaning in the \CEE/ preprocessor, 572 | so \.{CWEAVE} is set up to format them specially; if you want a variable 573 | named \\{error} or \\{line}, you should say 574 | $$\.{@f error normal}\qquad\qquad\.{@f line normal}$$ 575 | somewhere in your program. 576 | 577 | \more If \|r is the special identifier `\\{TeX}', identifier \|l 578 | will be formatted as a \TEX/ control sequence; for example, 579 | `\.{@f foo TeX}' in the \.{CWEB} file will cause identifier \\{foo} to 580 | be output as \.{\\foo} by \.{CWEAVE}. The programmer should define 581 | \.{\\foo} to have whatever custom format is desired, assuming \TEX/ 582 | math mode. (Each underline 583 | character is converted to \.{x} when making the \TEX/ control sequence, 584 | and each dollar sign is converted to~\.X; 585 | thus \\{foo\_bar} becomes \.{\\fooxbar}. Other characters, including digits, 586 | are left untranslated, so \TEX/ will consider them as macro parameters, 587 | not as part of the control sequence itself. For example, 588 | $$\.{\\def\\x\#1\{x\_\{\#1\}\} @f x1 TeX @f x2 TeX}$$ 589 | will format \.{x1} and \.{x2} not as \\{x1} and \\{x2} but as $x_1$ and $x_2$.) 590 | 591 | \more If \|r is the special identifier `\\{make\_pair}', identifier \|l will 592 | be treated as a \CPLUSPLUS/ function template. For example, after 593 | \.{@f}~\.{convert}~\.{make\_pair} one can say `\.{convert(2.5)}' without 594 | having \.< and \.> misunderstood as less-than and greater-than signs. 595 | 596 | \more \.{CWEAVE} knows that identifiers being 597 | defined with a \&{typedef} should become reserved words; thus you 598 | don't need format definitions very often. 599 | 600 | \@s [TM\to M;\;L] Same as \.{@f}, but \.{CWEAVE} does not show the format 601 | definition in the output, and the optional \CEE/ comment is not 602 | allowed. This is used mostly in \.{@i} files. 603 | 604 | \subsec 605 | Next come the codes that govern the \CEE/ part of a section. 606 | 607 | \@{c @p} [TM\to C] The \CEE/ part of an unnamed section begins with \.{@c} 608 | (or with \.{@p} for ``program''; both control codes do the same thing). 609 | This causes \.{CTANGLE} to append the following \CEE/ code 610 | to the first-order program text, as explained on page~\tangref. 611 | Note that \.{CWEAVE} does not print a `\.{@c}' in the \TEX/ 612 | output, so if you are creating a \.{CWEB} file based on a \TEX/-printed 613 | \.{CWEB} documentation you have to remember to insert \.{@c} in the 614 | appropriate places of the unnamed sections. 615 | 616 | \@< [TM\to C;\; C;\; c] $*$ This control code introduces a 617 | section name (or unambiguous prefix, as discussed above), which 618 | consists of \TEX/ text and extends to the matching \.{@>}. 619 | The whole construct \.{@<...@>} is conceptually a \CEE/ element. 620 | The behavior is different depending on the context: 621 | 622 | \more A \.{@<} appearing in contexts $T$ and $M$ attaches the 623 | following section name to the current section, and inaugurates the 624 | \CEE/ part of the section. The closing \.{@>} should be followed by 625 | \.{=} or \.{+=}. 626 | 627 | \more 628 | In context $C$, \.{@<} indicates that the named 629 | section is being used---its \CEE/ definition is spliced in by 630 | \.{CTANGLE}, as explained on page~\tangref. 631 | As an error-detection measure, 632 | \.{CTANGLE} and \.{CWEAVE} complain if such a section name is followed 633 | by \.=, because most likely this is meant as the definition of a new 634 | section, and so should be preceded by \.{@\ }. If you really want to 635 | say $\langle\,$foo$\,\rangle=\\{bar}$, where $\langle\,$foo$\,\rangle$ 636 | is being used and not defined, put a newline before the \.=. 637 | 638 | \more 639 | Finally, in inner \CEE/ context (that is, within `\pb' in the \TEX/ part 640 | of a section or in a comment), \.{@<...@>} 641 | means that the named section is being 642 | cited. Such an occurrence is ignored by \.{CTANGLE}. Note that 643 | even here we think of the section name as being a \CEE/ element, hence the \pb. 644 | 645 | \@( [TM\to C;\;C;\;c] $*$ A section name can begin with \.{@(}. 646 | Everything works just as for \.{@<}, except that the \CEE/ code 647 | of the section named \.{@(foo@>} is written by \.{CTANGLE} 648 | to file \.{foo}. In this way you can get multiple-file output from 649 | a single \.{CWEB} file. (The \.{@d} definitions are not output 650 | to such files, only to the master \.{.c} file.) One use of this feature 651 | is to produce header files for other program modules that will be loaded 652 | with the present one. Another use is to produce a test routine that 653 | goes with your program. By keeping the sources for a program and its 654 | header and test routine together, you are more likely to keep 655 | all three consistent with each other. Notice that the output of a named 656 | section can be incorporated in several different output files, because 657 | you can mention \.{@} in both \.{@(bar1@>} and \.{@(bar2@>}. 658 | 659 | \@h [Cc] Causes \.{CTANGLE} 660 | to insert at the current spot the \.{\#define} statements 661 | from the middle parts of all sections, 662 | and {\it not\/} to write them at the beginning of the \CEE/ file. 663 | Useful when you want the macro definitions to come after the include files, 664 | say. (Ignored by \.{CTANGLE} inside `\pb'.) 665 | 666 | \subsec 667 | The next several control codes introduce ``control 668 | texts,'' which end with the next `\.{@>}'. The closing `\.{@>}' must be on 669 | the same line of the \.{CWEB} file as the line where the control text began. 670 | The context from each of these control codes to the matching \.{@>} is 671 | restricted. 672 | 673 | \@\^ [TMCc] $*$ The control text that follows, up to the next 674 | `\.{@>}', will be entered into the index together with the identifiers of 675 | the \CEE/ program; this text will appear in roman type. For example, to 676 | put the phrase ``system dependencies'' into the index that is output by 677 | \.{CWEAVE}, type 678 | `\.{@\^system dependencies@>}' in each section 679 | that you want to index as system dependent. 680 | 681 | \@. [TMCc] $*$ The control text that follows will be entered into the index 682 | in \.{typewriter} \.{type}. 683 | 684 | \@: [TMCc] $*$ The control text that follows will be entered into the index 685 | in a format controlled by the \TEX/ macro `\.{\\9}', which you 686 | should define as desired. 687 | 688 | \@t [MCc] $*$ The control text that follows will 689 | be put into a \TEX/ \.{\\hbox} and formatted along with the neighboring 690 | \CEE/ program. This text is ignored by \.{CTANGLE}, but it can be used 691 | for various purposes within \.{CWEAVE}. For example, you can make comments 692 | that mix \CEE/ and classical mathematics, as in `$\\{size}<2^{15}$', by 693 | typing `\.{|size < 2@t\$\^\{15\}\$@>|}'. 694 | 695 | \@= [MCc] $*$ The control text that follows will 696 | be passed verbatim to the \CEE/ program. 697 | 698 | \@q [LTMCc] $*$ The control text that follows will 699 | be totally ignored---it's a comment for readers of the \.{CWEB} file only. 700 | A file intended to be included in 701 | limbo, with \.{@i}, can identify itself with \.{@q} comments. 702 | Another use is to balance unbalanced parentheses in \CEE/ strings, 703 | so that your text editor's parenthesis matcher doesn't go into a tailspin. 704 | 705 | \@! [TMCc] $*$ 706 | The section number in an index entry will be underlined if `\.{@!}' 707 | immediately precedes the identifier or control text being indexed. This 708 | convention is used to distinguish the sections where an identifier is 709 | defined, or where it is explained in some special way, from the sections 710 | where it is used. A~reserved word or an identifier of length one will not 711 | be indexed except for underlined entries. An `\.{@!}' is implicitly inserted 712 | by \.{CWEAVE} when an identifier is being defined or declared in \CEE/ 713 | code; for example, the definition 714 | $$\hbox{\&{int} \\{array}[\\{max\_dim}], \\{count}${}=\\{old\_count};$}$$ 715 | makes the names \\{array} and \\{count} get an underlined entry in the 716 | index. Statement labels, function definitions like 717 | \\{main}(\&{int}~\\{argc},\,\&{char}~$*$\\{argv}[\,]), 718 | and \&{typedef} definitions also 719 | imply underlining. An old-style 720 | function definition (without prototyping) doesn't define its arguments; 721 | the arguments will, however, be considered to be defined 722 | (i.e., their index entries will be underlined) if their types are 723 | declared before the body of the function in the usual way 724 | (e.g., `\&{int}~\\{argc}; \&{char}~${*}\\{argv}[\,]$; $\{\,\ldots\,\}$'). 725 | Thus \.{@!} is not needed very often, except in unusual constructions 726 | or in cases like 727 | $$\.{enum boolean \{@!false, @!true\};}$$ 728 | here \.{@!} gives the best results because individual constants enumerated 729 | by \.{enum} are not automatically underlined in the index at their 730 | point of definition. 731 | 732 | \subsec 733 | We now turn to control codes that affect only the operation of 734 | \.{CTANGLE}. 735 | 736 | \@' [MCc] This control code is dangerous because it has quite different 737 | meanings in \.{CWEB} and the original \.{WEB}. In \.{CWEB} it produces the 738 | decimal constant corresponding to the ASCII code for a string of length~1 739 | (e.g., \.{@'a'} is \.{CTANGLE}d into \.{97} and \.{@'\\t'} into 740 | \.9). You might want to use this if you need to work in ASCII on a 741 | non-ASCII machine; but in most cases the \CEE/ conventions of 742 | \.{} are adequate for character-set-independent programming. 743 | 744 | \@\& [MCc] The \.{@\&} operation causes whatever is on its left to be 745 | adjacent to whatever is on its right, in the \CEE/ output. No spaces or 746 | line breaks will separate these two items. 747 | 748 | \@l [L] \.{CWEB} programmers have the option of using any 8-bit character 749 | code from the often-forbidden range 128--255 within \TEX/ text; such 750 | characters are also permitted in strings and even in identifiers of the 751 | \CEE/ program. 752 | Under various extensions of the basic 753 | ASCII standard, the higher 8-bit codes correspond 754 | to accented letters, letters from non-Latin alphabets, 755 | and so on. When such characters occur in identifiers, \.{CTANGLE} must replace 756 | them by standard ASCII alphanumeric characters or 757 | \.{\_}, in order to generate legal \CEE/ code. It does this by means 758 | of a transliteration table, which by default associates the string 759 | \.{Xab} to the character with ASCII code \T{\^}$ab$ (where $a$ and $b$ are 760 | hexadecimal digits, and $a\ge8$). By placing the 761 | construction \.{@l\ ab\ newstring} in limbo, you are telling 762 | \.{CTANGLE} to replace this character by \.{newstring} instead. 763 | For example, the ISO Latin-1 code for the letter `\"u' is \T{\^FC} 764 | (or \.{'\char`\\374'}), 765 | and \.{CTANGLE} will normally change this code to the 766 | three-character sequence \.{XFC} if it 767 | appears in an identifier. If you say \.{@l} \.{fc} \.{ue}, the code will 768 | be transliterated into \.{ue} instead. 769 | 770 | \more 771 | \.{CWEAVE} passes 8-bit characters straight through to \TEX/ without 772 | transliteration; therefore \TEX/ must be prepared to receive them. 773 | If you are formatting all your nonstandard identifiers as ``custom'' 774 | control sequences, you should 775 | make \TEX/ treat all their characters as letters. Otherwise you should either 776 | make your 8-bit codes ``active'' in \TEX/, or load fonts that 777 | contain the special characters you need in the correct positions. 778 | (The font selected by \TEX/ control sequence \.{\\it} is used for 779 | identifiers.) 780 | Look for special macro packages designed for \.{CWEB} users in your language; 781 | or, if you are brave, write one yourself. 782 | 783 | \subsec 784 | The next eight control codes (namely `\.{@,}', `\.{@/}', `\.{@|}', `\.{@\#}', 785 | `\.{@+}', `\.{@;}', `\.{@[}', and `\.{@]}') have no effect on the \CEE/ 786 | program output by \.{CTANGLE}; they merely help to improve the readability 787 | of the \TEX/-formatted \CEE/ that is output by \.{CWEAVE}, in unusual 788 | circumstances. \.{CWEAVE}'s built-in formatting method is fairly good 789 | when dealing with syntactically correct \CEE/ text, but 790 | it is incapable of handling all possible cases, because it must deal with 791 | fragments of text involving macros and section names; these fragments do 792 | not necessarily obey \CEE/'s syntax. Although \.{CWEB} allows you to 793 | override the automatic formatting, your best strategy is not to worry 794 | about such things until you have seen what \.{CWEAVE} produces automatically, 795 | since you will probably need to make only a few corrections when you are 796 | touching up your documentation. 797 | 798 | \@, [MCc] This control code inserts a thin space in \.{CWEAVE}'s output. 799 | Sometimes you need this extra space if you are using 800 | macros in an unusual way, e.g., if two identifiers are adjacent. 801 | 802 | \@/ [MC] This control code causes a line break to occur within a \CEE/ 803 | program formatted by \.{CWEAVE}. Line breaks 804 | are chosen automatically by \TEX/ according to a scheme that works 99\%\ 805 | of the time, but sometimes you will prefer to force a line break so that 806 | the program is segmented according to logical rather than visual 807 | criteria. If a comment follows, say `\.{@/@,}' to break the line 808 | before the comment. 809 | 810 | \@| [MC] This control code specifies an optional line break in the midst of 811 | an expression. For example, if you have 812 | a long expression on the right-hand side of an assignment 813 | statement, you can use `\.{@|}' to specify breakpoints more logical than 814 | the ones that \TEX/ might choose on visual grounds. 815 | 816 | \@\# [MC] This control code forces a line break, like \.{@/} does, 817 | and it also causes a little extra white space to appear between the lines at 818 | this break. You might use it, for example, 819 | between groups of macro definitions that are logically separate but within 820 | the same section. \.{CWEB} automatically inserts this extra space 821 | between functions, between external declarations and functions, and 822 | between declarations and statements within a function. 823 | 824 | \@+ [MC] This control code cancels a line break that might otherwise be 825 | inserted by \.{CWEAVE}, e.g., before the word `\&{else}', if you want to 826 | put a short if--else construction on a single line. 827 | If you say `\.{\{@+}' at the beginning of a compound statement 828 | that is the body of a function, the first declaration or 829 | statement of the function will appear on the same line as the 830 | left brace, and it will be indented by the same amount as the 831 | second declaration or statement on the next line. 832 | 833 | \@; [MC] This control code is treated like a semicolon, for formatting 834 | purposes, except that it is invisible. You can use it, for example, after 835 | a section name or macro when the \CEE/ text represented by that section or macro 836 | is a compound statement or ends 837 | with a semicolon. Consider constructions like 838 | $$\lpile{\.{if (condition) macro @;}\cr 839 | \.{else break;}\cr}$$ 840 | where \\{macro} is defined to be a compound statement (enclosed in braces). 841 | This is a well-known infelicity of \CEE/ syntax. 842 | 843 | \@{[} [MC] See \.{@]}. 844 | 845 | \@] [MC] Place \.{@[...@]} brackets around program text that \.{CWEAVE} is 846 | supposed to format as an expression, if it doesn't already do so. (This 847 | occasionally applies to unusual macro arguments.) Also 848 | insert `\.{@[@]}' between a simple type name and a left parenthesis 849 | when declaring a pointer to a function, as in 850 | $$\.{int @[@] (*f)();}$$ 851 | otherwise \.{CWEAVE} will confuse the first part of that declaration with 852 | the \CPLUSPLUS/ expression `\&{int}($*f$)'. Another example, for people 853 | who want to use low-level \.{\#define} commands in the midst of \CEE/ code 854 | and the definition begins with a cast: 855 | $$\.{\#define foo @[(int)(bar)@]}$$ 856 | 857 | \subsec 858 | The remaining control codes govern the input that \.{CWEB} sees. 859 | 860 | \@{x @y @z}[\\{change\_file}] 861 | \.{CWEAVE} and \.{CTANGLE} are designed to work with two input files, 862 | called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains 863 | data that overrides selected portions of \\{web\_file}. The resulting merged 864 | text is actually what has been called the \.{CWEB} file elsewhere in this 865 | report. 866 | 867 | \more Here's how it works: The change file consists of zero or more ``changes,'' 868 | where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$% 869 | new lines$\rangle$\.{@z}'. The special control codes \.{@x}, \.{@y}, \.{@z}, 870 | which are allowed only in change files, must appear at the beginning of a line; 871 | the remainder of such a line is ignored. 872 | The $\langle$old lines$\rangle$ represent material that exactly matches 873 | consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$ 874 | represent zero or more lines that are supposed to replace the old. Whenever 875 | the first ``old line'' of a change is found to match a line in the 876 | \\{web\_file}, all the other lines in that change must match too. 877 | 878 | \more Between changes, before the first change, and after the last change, 879 | the change file can have any number of lines that do not begin with 880 | `\.{@x}', `\.{@y}', or~`\.{@z}'. Such lines are bypassed and not used for 881 | matching purposes. 882 | 883 | \more This dual-input feature is useful when working with a master \.{CWEB} 884 | file that has been received from elsewhere (e.g., \.{tangle.w} or 885 | \.{weave.w} or \.{tex.web}), when changes are desirable to customize the 886 | program for your local computer system. You will be able to debug your 887 | system-dependent changes without clobbering the master web file; and once 888 | your changes are working, you will be able to incorporate them readily 889 | into new releases of the master web file that you might receive from time 890 | to time. 891 | 892 | \@i [\\{web\_file}] 893 | Furthermore the \\{web\_file} itself can be a combination of 894 | several files. When either \.{CWEAVE} or \.{CTANGLE} is reading a file and 895 | encounters the control code \.{@i} at the beginning of a line, it 896 | interrupts normal reading and starts looking at the file named after the 897 | \.{@i}, much as the \CEE/ preprocessor does when it encounters an \.{\#include} 898 | line. After the included file has been entirely read, the program 899 | goes back to the next line 900 | of the original file. The file name following \.{@i} can be 901 | surrounded by \." characters, but such delimiters are 902 | optional. Include files can nest. 903 | 904 | \more 905 | Change files can have lines starting with \.{@i}. In this way 906 | you can replace one included file with another. Conceptually, the 907 | replacement mechanism described above does its work first, and 908 | its output is then checked for \.{@i} lines. If \.{@i} \.{foo} 909 | occurs between \.{@y} and \.{@z} in a change file, individual lines 910 | of file \.{foo} and files it includes are not changeable; but changes 911 | can be made to lines from files that were included by unchanged input. 912 | 913 | \more On \UNIX/ systems (and others that support environment variables), 914 | if the environment variable \.{CWEBINPUTS} is set, or if the compiler flag 915 | of the same name was defined at compile time, 916 | \.{CWEB} will look for include files in the directory thus named, if 917 | it cannot find them in the current directory. 918 | 919 | \section Additional features and caveats. 920 | 921 | 1. In certain installations of \.{CWEB} that 922 | {\def\\#1#2{`{\tentex\char'#1#2}'}% 923 | have an extended character set, the characters 924 | \\13, \\01, \\31, \\32, \\34, \\35, 925 | \\36, \\37, \\04, \\20, and \\21} 926 | can be typed as abbreviations for `\.{++}', `\.{--}', `\.{->}', 927 | `\.{!=}', `\.{<=}', `\.{>=}', `\.{==}', `\.{\v\v}', `\.{\&\&}', 928 | `\.{<<}', and `\.{>>}', 929 | respectively. 930 | 931 | 2. If you have an extended character set, you can use it with only minimal 932 | restrictions, as discussed under the rules for \.{@l} above. But you should 933 | stick to standard ASCII characters if you want to write programs that will 934 | be useful to all the poor souls out there who don't have extended 935 | character sets. 936 | 937 | 3. The \TEX/ file output by \.{CWEAVE} is broken into lines having at most 938 | 80 characters each. When 939 | \TEX/ text is being copied, the existing line breaks are copied as well. 940 | If you aren't doing anything too tricky, \.{CWEAVE} will recognize when 941 | a \TEX/ comment is being split across two or more lines, and it will 942 | append `\.\%' to the beginning of such continued comments. 943 | 944 | 4. \CEE/ text is translated by a ``bottom up'' procedure that 945 | identifies each token as a ``part of speech'' and combines parts of speech 946 | into larger and larger phrases as much as possible according to a special 947 | grammar that is explained in the documentation of \.{CWEAVE}. It is easy to 948 | learn the translation scheme for simple constructions like single 949 | identifiers and short expressions, just by looking at a few examples of 950 | what \.{CWEAVE} does, but the general mechanism is somewhat complex because 951 | it must handle much more than \CEE/ itself. Furthermore the output 952 | contains embedded codes that cause \TEX/ to indent and break lines as 953 | necessary, depending on the fonts used and the desired page width. For 954 | best results it is wise to avoid enclosing long \CEE/ texts in \pb, since the 955 | indentation and line breaking codes are omitted when the \pb\ text is 956 | translated from \CEE/ to \TEX/. Stick to simple expressions or 957 | statements. If a \CEE/ preprocessor command is enclosed in \pb, 958 | the \.\# that introduces it must be at the beginning of a line, 959 | or \.{CWEAVE} won't print it correctly. 960 | 961 | 5. Comments are not permitted in \pb\ text. After a `\.|' 962 | signals the change from \TEX/ text to \CEE/ text, the next `\.|' that is 963 | not part of a string or control text or section name ends the \CEE/ text. 964 | 965 | 6. A comment must have properly nested occurrences of left and right 966 | braces, otherwise \.{CWEAVE} will complain. But it 967 | does try to balance the braces, so that \TEX/ won't foul up too much. 968 | 969 | 7. When you're debugging a program and decide to omit some of your 970 | \CEE/ code, do NOT simply ``comment it out.'' Such comments are not 971 | in the spirit of \.{CWEB} documentation; they will appear to readers 972 | as if they were explanations of the uncommented-out instructions. 973 | Furthermore, comments of a program must be valid \TEX/ text; hence 974 | \.{CWEAVE} will get confused if you enclose \CEE/ statements in 975 | \.{/*...*/} instead of in \.{/*|...|*/}. If you must comment out 976 | \CEE/ code, you can surround it with preprocessor commands 977 | like \.{\#if 0==1} and \.{\#endif}. 978 | 979 | 8. The \.{@f} feature allows you to define one identifier to act like 980 | another, and these format definitions are carried out sequentially. 981 | In general, a given identifier has only one printed format 982 | throughout the entire document, and this format is used even before 983 | the \.{@f} that defines it. The reason is that \.{CWEAVE} operates in two 984 | passes; it processes \.{@f}'s and cross-references on the first pass and 985 | it does the output on the second. (However, identifiers that 986 | implicitly get a boldface format, thanks to a \.{typedef} declaration, 987 | don't obey this rule; they are printed differently before and after 988 | the relevant \.{typedef}. This is unfortunate, but hard to fix. You can 989 | get around the restriction by saying, say, `\.{@s} \.{foo} \.{int}', 990 | before or after the \.{typedef}.) 991 | 992 | 9. Sometimes it is desirable to insert spacing into formatted \CEE/ code that 993 | is more general than the thin space provided by `\.{@,}'. The \.{@t} feature 994 | can be used for this purpose; e.g., `\.{@t\\hskip 1in@>}' will 995 | leave one inch of blank space. Furthermore, `\.{@t\\4@>}' can be 996 | used to backspace by one unit of indentation, since the control sequence 997 | \.{\\4} is defined in \.{cwebmac} to be such a backspace. (This 998 | control sequence is used, for example, at the beginning of lines that 999 | contain labeled statements, so that the label will stick out a little at 1000 | the left.) You can also use `\.{@t\}\\3\{-5@>}' to force a break 1001 | in the middle of an expression. 1002 | 1003 | 10. Each identifier in \.{CWEB} has a single formatting convention. Therefore 1004 | you shouldn't use the same identifier to denote, say, both a type name and 1005 | part of a \.{struct}, even though \CEE/ does allow this. 1006 | 1007 | \section Running the programs. 1008 | The \UNIX/ command line for \.{CTANGLE} is 1009 | $$\.{ctangle [options] web\_file[.w] [\{change\_file[.ch]|-\} [out\_file]]}$$ 1010 | and the same conventions apply to \.{CWEAVE}. If `\.-' or no change file is 1011 | specified, the change file is null. The extensions \.{.w} and \.{.ch} 1012 | are appended only if the given file names contain no dot. If the 1013 | web file defined in this way cannot be found, the extension \.{.web} 1014 | will be tried. For example, `\.{cweave} \.{cob}' will try to read 1015 | \.{cob.w}; failing that, it will try \.{cob.web} before giving up. 1016 | If no output file name is specified, the name of the \CEE/ file output by 1017 | \.{CTANGLE} is obtained by appending the extension \.{.c}; 1018 | the name of the \TEX/ file output by \.{CWEAVE} gets the extension \.{.tex}. 1019 | Index files output by \.{CWEAVE} replace \.{.tex} by \.{.idx} and \.{.scn}. 1020 | 1021 | Programmers who like terseness might choose to set up their 1022 | operating shell so that `\.{wv}' expands to 1023 | `\.{cweave -bhp}'; this will suppress most terminal output from \.{CWEAVE} 1024 | except for error messages. 1025 | 1026 | Options are introduced either by a \.- sign, to turn an option off, 1027 | or by a \.+ sign to turn one on. For example, `\.{-fb}' turns off 1028 | options \.f and \.b; `\.{+s}' turns on option \.s. Options can be 1029 | specified before the file names, after the file names, or both. The following 1030 | options are currently implemented: 1031 | 1032 | \yskip 1033 | \def\option#1 {\textindent{\.#1}\hangindent2\parindent} 1034 | 1035 | \option b Print a banner line at the beginning of execution. (On 1036 | by default.) 1037 | 1038 | \option e Enclose \CEE/ material formatted by \.{CWEAVE} in 1039 | brackets \.{\\PB\{...\}}, so that special hooks can be used. 1040 | (Off by default; has no effect on \.{CTANGLE}.) 1041 | 1042 | \option f Force line breaks after each \CEE/ statement formatted 1043 | by \.{CWEAVE}. (On by default; \.{-f} saves paper but looks less \CEE/-like 1044 | to some people.) (Has no effect on \.{CTANGLE}.) 1045 | 1046 | \option h Print a happy message at the conclusion of a successful 1047 | run. (On by default.) 1048 | 1049 | \option p Give progress reports as the program runs. (On by default.) 1050 | 1051 | \option s Show statistics about memory usage after the program 1052 | runs to completion. (Off by default.) 1053 | If you 1054 | have large \.{CWEB} files or sections, you may need to see 1055 | how close you come to exceeding the capacity of \.{CTANGLE} and/or \.{CWEAVE}. 1056 | 1057 | \option x Include indexes and a table of contents in the \TEX/ file 1058 | output by \.{CWEAVE}. (On by default.) (Has no effect on \.{CTANGLE}.) 1059 | 1060 | \section Further details about formatting. 1061 | You may not like the way \.{CWEAVE} handles certain 1062 | situations. If you're desperate, you can customize \.{CWEAVE} 1063 | by changing its grammar. This means changing the source code, 1064 | a task that you might find amusing. A table of grammar rules 1065 | appears in the \.{CWEAVE} source listing, and you can make a separate 1066 | copy of that table by copying the file \.{prod.w} found in the \.{CWEB} 1067 | sources and saying `\.{cweave}~\.{-x}~\.{prod}', followed by 1068 | `\.{tex}~\.{prod}'. 1069 | 1070 | You can see exactly 1071 | how \.{CWEAVE} is parsing your \CEE/ code by preceding 1072 | it with the line `\.{@ @c @2}'. (The control code `\.{@2}' 1073 | turns on a ``peeping'' mode, and `\.{@0}' turns it off.) 1074 | For example, if you run \.{CWEAVE} on the file 1075 | \medskip 1076 | \begingroup 1077 | \verbatim 1078 | @ @c @2 1079 | main (argc,argv) 1080 | char **argv; 1081 | { for (;argc>0;argc--) printf("%s\n",argv[argc-1]); } 1082 | !endgroup 1083 | \endgroup 1084 | \medskip\noindent 1085 | you get the following gibberish on your screen: 1086 | \medskip 1087 | \begingroup 1088 | \verbatim 1089 | [...] 1090 | 4:*exp ( +exp+ )... 1091 | 11:*exp +exp+ int... 1092 | 5:*+exp+ int +unorbinop+... 1093 | [...] 1094 | 60: +fn_decl+*+{+ -stmt- +}- 1095 | 55:*+fn_decl+ -stmt- 1096 | 52:*+function- 1097 | [...] 1098 | !endgroup 1099 | \endgroup 1100 | \medskip 1101 | The first line says that grammar rule 4 has just been applied, and \.{CWEAVE} 1102 | currently has in its memory a sequence of chunks of \TEX/ code (called 1103 | ``scraps'') that are respectively 1104 | of type \\{exp} (for expression), open-parenthesis, 1105 | \\{exp} again, close-parenthesis, and further scraps that haven't yet 1106 | been considered by the parser. (The \.+ and \.- signs stipulate that 1107 | \TEX/ should be in or out of math mode at the scrap boundaries. The \.* shows 1108 | the parser's current position.) 1109 | Then rule 11 is applied, and 1110 | the sequence $(\,exp\,)$ becomes an \\{exp} and so on. In the 1111 | end the whole \CEE/ text has become one big scrap of type \\{function}. 1112 | 1113 | Sometimes things don't work as smoothly, and you get a bunch of 1114 | lines lumped together. This means that \.{CWEAVE} could not 1115 | digest something in your \CEE/ code. For instance, suppose 1116 | `\.{@}' had appeared instead of 1117 | `\.{char **argv;}' in the program above. Then \.{CWEAVE} would have 1118 | been somewhat mystified, since it thinks that section names 1119 | are just \\{exp}s. Thus it would tell \TEX/ to format 1120 | `\X2:Argument declarations\X' on the same line as 1121 | `$\\{main}(\\{argc},\39\\{argv}{}$)'. 1122 | In this case you should help \.{CWEAVE} by putting `\.{@/}' after 1123 | `\.{main(argc,argv)}'. 1124 | 1125 | \.{CWEAVE} automatically inserts a bit of extra space between declarations 1126 | and the first apparent statement of a block. One way to defeat this 1127 | spacing locally is 1128 | $$\vbox{\halign{#\hfil\cr 1129 | \.{int x;@+@t\}\\6\{@>}\cr 1130 | \.{@@;@\#}\cr}}$$ 1131 | the `\.{@\#}' will put extra space after `$\langle\,$Other locals$\,\rangle$'. 1132 | 1133 | \section Hypertext and hyperdocumentation. 1134 | 1135 | Many people have of course noticed analogies between \.{CWEB} and the 1136 | World Wide Web. The \.{CWEB} macros are in fact set up so that the output of 1137 | \.{CWEAVE} can be converted easily into Portable Document Format, 1138 | with clickable hyperlinks that can be read with Adobe's Acrobat Reader, 1139 | using a widely available open-source program called \.{dvipdfm} developed 1140 | by Mark~A. Wicks. After using \.{CWEAVE} to convert \.{cob.w} into 1141 | \.{cob.tex}, you can prepare and view a hypertext version of the program 1142 | by giving the commands 1143 | $$\vbox{\halign{\.{#}\hfil\cr 1144 | tex "\\let\\pdf+ \\input cob"\cr 1145 | dvipdfm cob\cr 1146 | acroread cob.pdf\cr}}$$ 1147 | instead of invoking \TeX\ in the normal way. (Thanks to Hans Hagen, 1148 | C\'esar Augusto Rorato Crusius, and Julian Gilbey 1149 | for the macros that make this work.) 1150 | Alternatively, thanks to H\`an Th\^e\kern-.3em\raise.3ex\hbox{\'{}} Th\`anh 1151 | and Andreas Scherer, you can generate \.{cob.pdf} in one step by simply 1152 | saying `\.{pdftex}~\.{cob}'. 1153 | 1154 | A more elaborate system called \.{CTWILL}, which extends the usual cross 1155 | references of \.{CWEAVE} by preparing links from the uses of identifiers 1156 | to their definitions, is also available---provided that you are willing 1157 | to work a bit harder in cases where an identifier is multiply defined. 1158 | \.{CTWILL} is intended primarily for hardcopy output, but its principles 1159 | could be used for hypertext as well. 1160 | See Chapter 11 of {\sl Digital Typography\/} by D.~E. Knuth (1999), and 1161 | the program sources at \.{ftp://ftp.cs.stanford.edu/pub/ctwill}. 1162 | 1163 | \section Appendices. 1164 | 1165 | As an example of a real program written in \.{CWEB}, Appendix~A 1166 | contains an excerpt from the \.{CWEB} program itself. The reader who 1167 | examines the listings in this appendix carefully will get a good 1168 | feeling for the basic ideas of \.{CWEB}. 1169 | 1170 | Appendix B is the file that sets \TEX/ up to accept 1171 | the output of \.{CWEAVE}, and Appendix~C discusses how to use some of those 1172 | macros to vary the output formats. 1173 | 1174 | A ``long'' version of this manual, which can be produced from the \.{CWEB} 1175 | sources via the \UNIX/ command \.{make} \.{fullmanual}, also contains 1176 | appendices D, E, and~F, which exhibit the complete source code for 1177 | \.{CTANGLE} and \.{CWEAVE}. 1178 | 1179 | \vfil\eject\titletrue 1180 | 1181 | \def\runninghead{APPENDIX A --- {\tentt CWEB} FILE FORMAT} 1182 | \section Appendix A: Excerpts from a \.{CWEB} Program. 1183 | 1184 | This appendix consists 1185 | of four listings. The first shows the \.{CWEB} input that 1186 | generated sections 12--15 of the file \.{common.w}, which contains 1187 | routines common to \.{CWEAVE} and \.{CTANGLE}. 1188 | Note that some of the lines are indented to show the program structure; 1189 | the indentation is ignored by \.{CWEAVE} and \.{CTANGLE}, but users find 1190 | that \.{CWEB} files are quite readable if they have some such indentation. 1191 | 1192 | The second and third listings 1193 | show corresponding parts 1194 | of the \CEE/ code output by \.{CTANGLE} and of 1195 | the corresponding \TEX/ code output by \.{CWEAVE}, when run on \.{common.w}. 1196 | The fourth listing shows how that output looks when printed out. 1197 | 1198 | \vskip 6pt 1199 | \begingroup \def\tt{\eighttt} \baselineskip9pt 1200 | \verbatim 1201 | @ Procedure |prime_the_change_buffer| 1202 | sets |change_buffer| in preparation for the next matching operation. 1203 | Since blank lines in the change file are not used for matching, we have 1204 | |(change_limit==change_buffer && !!changing)| if and only if 1205 | the change file is exhausted. This procedure is called only when 1206 | |changing| is 1; hence error messages will be reported correctly. 1207 | 1208 | @c 1209 | void 1210 | prime_the_change_buffer() 1211 | { 1212 | change_limit=change_buffer; /* this value is used if the change file ends */ 1213 | @; 1214 | @; 1215 | @; 1216 | } 1217 | 1218 | @ While looking for a line that begins with \.{@@x} in the change file, we 1219 | allow lines that begin with \.{@@}, as long as they don't begin with \.{@@y}, 1220 | \.{@@z}, or \.{@@i} (which would probably mean that the change file is fouled up). 1221 | 1222 | @= 1223 | while(1) { 1224 | change_line++; 1225 | if (!!input_ln(change_file)) return; 1226 | if (limit 1234 | } 1235 | } 1236 | 1237 | @ Here we are looking at lines following the \.{@@x}. 1238 | 1239 | @= 1240 | do { 1241 | change_line++; 1242 | if (!!input_ln(change_file)) { 1243 | err_print("!! Change file ended after @@x"); 1244 | @.Change file ended...@> 1245 | return; 1246 | } 1247 | } while (limit==buffer); 1248 | 1249 | @ @= 1250 | { 1251 | change_limit=change_buffer-buffer+limit; 1252 | strncpy(change_buffer,buffer,limit-buffer+1); 1253 | } 1254 | 1255 | !endgroup 1256 | \endgroup 1257 | \vfill\eject 1258 | 1259 | \def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CTANGLE}} 1260 | 1261 | Here's the portion of the \CEE/ code generated by \.{CTANGLE} that corresponds 1262 | to the source on the preceding page. Notice that sections~13, 14 and~15 1263 | have been tangled into section~12. 1264 | 1265 | \vskip6pt 1266 | \begingroup \def\tt{\eighttt} \baselineskip9pt 1267 | \verbatim 1268 | /*:9*//*12:*/ 1269 | #line 247 "common.w" 1270 | 1271 | void 1272 | prime_the_change_buffer() 1273 | { 1274 | change_limit= change_buffer; 1275 | /*13:*/ 1276 | #line 261 "common.w" 1277 | 1278 | while(1){ 1279 | change_line++; 1280 | if(!!input_ln(change_file))return; 1281 | if(limit}', the backslash character gets in the way, 1641 | and this entry wouldn't appear in the index with the T's. 1642 | 1643 | The solution is to use the `\.{@:}' feature, declaring a macro that 1644 | simply removes a sort key as follows: 1645 | $$\.{\\def\\9\#1\{\}}$$ 1646 | Now you can say, e.g., `\.{@:TeX\}\{\\TeX@>}' in your \.{CWEB} file; \.{CWEAVE} 1647 | puts it into the index alphabetically, based on the sort key, and 1648 | produces the macro call `\.{\\9\{TeX\}\{\\TeX\}}' which will ensure that 1649 | the sort key isn't printed. 1650 | 1651 | A similar idea can be used to insert hidden material into section 1652 | names so that they are alphabetized in whatever way you might wish. 1653 | Some people call these tricks ``special refinements''; others call 1654 | them ``kludges.'' 1655 | 1656 | \point 12. The control sequence \.{\\secno} is set to the number of the 1657 | section being typeset. 1658 | 1659 | \point 13. If you want to list only the sections that have changed, 1660 | together with the index, put the command `\.{\\let\\maybe=\\iffalse}' in 1661 | the limbo section before the first section of your \.{CWEB} file. It's 1662 | customary to make this the first change in your change file. 1663 | 1664 | This feature has a \TeX nical limitation, however: You cannot use it 1665 | together with control sequences like \.{\\proclaim} or \.{\\+} or 1666 | \.{\\newcount} that plain \TeX\ has declared to be `\.{\\outer}', 1667 | because \TeX\ refuses to skip silently over such control sequences. 1668 | One way to work around this limitation is to say 1669 | $$\.{\\fi \\let\\proclaim\\relax \\def\\proclaim\{...\} \\ifon}$$ 1670 | where \.{\\proclaim} is redefined to be the same as usual but without 1671 | an \.{\\outer} qualification. (The \.{\\fi} here stops the conditional 1672 | skipping, and the \.{\\ifon} turns it back on again.) Similarly, 1673 | $$\.{\\fi \\newcount\\n \\ifon}$$ 1674 | is a safe way to use \.{\\newcount}. Plain \TeX\ already provides a 1675 | non-outer macro \.{\\tabalign} that does the work of \.{\\+}; you can say 1676 | $$\postdisplaypenalty=10000 1677 | \.{\\fi \\let\\+\\tabalign \\ifon}$$ 1678 | if you prefer the shorter notation \.{\\+}. 1679 | 1680 | \point 14. To get output in languages other than English, redefine the 1681 | macros \.{\\A}, \.{\\As}, \.{\\ATH}, 1682 | \.{\\ET}, \.{\\ETs}, \.{\\Q}, \.{\\Qs}, \.{\\U}, 1683 | \.{\\Us}, \.{\\ch}, \.{\\fin}, \.{\\con}, \.{\\today}, \.{\\datethis}, and 1684 | \.{\\datecontentspage}. \.{CWEAVE} itself need not be changed. 1685 | 1686 | \point 15. Some output can be selectively suppressed with the macros 1687 | \.{\\noatl}, \.{\\noinx}, \.{\\nosecs}, \.{\\nocon}. 1688 | 1689 | \point 16. All accents and special text symbols of plain \TEX/ format 1690 | will work in \.{CWEB} documents just as they are described in 1691 | Chapter~9 of {\sl The \TEX/book}, with one exception. 1692 | The dot accent (normally \.{\\.}) must be typed \.{\\:} instead. 1693 | 1694 | \point 17. Several commented-out lines in \.{cwebmac.tex} are suggestions 1695 | that users may wish to adopt. For example, one such line inserts a blank page 1696 | if you have a duplex printer. Appendices D, E, and F of the complete 1697 | version of this manual are printed using a commented-out option that 1698 | substitutes `$\gets$' for `$=$' in the program listings. Looking at those 1699 | appendices might help you decide which format you like better. 1700 | 1701 | \point 18. Andreas Scherer has contributed a macro called \.{\\pdfURL} 1702 | with which one can say things like the following, anywhere in the \TeX\ parts 1703 | or the \CEE/ comments of a \.{CWEB} file: 1704 | $$\vbox{\halign{\.{#}\hfil\cr 1705 | You can send email to 1706 | \\pdfURL\{the author\}\{mailto:andreas.scherer@@pobox.com\}\cr 1707 | or visit \\pdfURL\{his home page\}\{http://www.pobox.com/% 1708 | \\TILDE/scherer\}.\cr}}$$ 1709 | In a {\mc PDF} document, the first argument will appear in blue as 1710 | clickable text; the Acrobat reader, if correctly configured, will then 1711 | redirect those links to the user's browser and open either the 1712 | email client or the HTML viewer. In a hardcopy document, both arguments 1713 | will be printed ({\tt the second in parentheses and typewriter type}). 1714 | Certain special characters in an Internet address need to be handled 1715 | in a somewhat awkward way, so that \.{CWEAVE} and/or \TeX\ 1716 | will not confuse them with formatting controls: Use \.{@@} for \.@ 1717 | and \.{\\TILDE/} for \.\~ and \.{\\UNDER/} for \.\_. 1718 | 1719 | \point 19. {\mc PDF} documents contain bookmarks that list all the major group 1720 | titles in the table of contents, some of which will be subsidiary to 1721 | others if the depth feature of \.{@*} has been used. 1722 | Such bookmark entries are also known as ``outlines.'' 1723 | Moreover, the final group title, `Names of the sections', 1724 | can be opened up to list every section name; Acrobat users can therefore 1725 | navigate easily to any desired section. 1726 | 1727 | The macros of \.{cwebmac.tex} are careful to ``sanitize'' all the names 1728 | that appear as bookmarks, by removing special characters and 1729 | formatting codes that are inappropriate for the limited typographic 1730 | capabilities of {\mc PDF} outlines. For example, one section of \.{CWEAVE} 1731 | is named `Cases for \\{case\_like}', which is represented by the \TeX\ code 1732 | `\.{Cases} \.{for} \.{\\PB\{\\\\\{case\\\_like\}\}}' in \.{cweave.tex}; its 1733 | sanitized name is simply `\.{Cases} \.{for} \.{case\_like}'. 1734 | (When \.{.pdf} files are produced, the fifth parameter of every \.{\\ZZ} in 1735 | the \.{.toc} file is set to the sanitized form of the first parameter; 1736 | see point~9 above and point~20 below.) 1737 | 1738 | In general, sanitization removes \TeX\ control sequences and braces, 1739 | except for control sequences defined by \.{CWEB} itself. Such a translation 1740 | works most of the time, but you can override the defaults and obtain any 1741 | translation that you want by using \TeX nical tricks. For example, after 1742 | $$\.{\\sanitizecommand\\foo\{bar\}}$$ 1743 | the control sequence \.{\\foo} will sanitize to `\.{bar}'. And after 1744 | $$\.{\\def\\kluj\#1\\\\\{foo\}}$$ 1745 | the \TeX\ code `\.{\\kluj bar\\\\}' will print as `foo' but sanitize 1746 | to `\.{bar}', because the control sequences \.{\\kluj} and 1747 | \.{\\\\} are removed by sanitization. 1748 | 1749 | \point 20. Furthermore, group titles can be converted to an arbitrary 1750 | sanitized text while also changing their form in running headlines, by 1751 | using \.{\\ifheader}. Consider, for example, a \.{CWEB} source file that 1752 | begins with the two lines 1753 | $$\lpile{\.{\\def\\klujj\#1\\\\\{\\ifheader FOO\\else foo\\fi\}}\cr 1754 | \.{@*Chinese \\klujj bar\\.}\cr}$$ 1755 | This coding introduces a major group entitled `{\bf Chinese foo}', with 1756 | running headline `{\eightrm CHINESE FOO}' and table-of-contents entry 1757 | `Chinese foo'. The corresponding bookmark is, however, `\.{Chinese} \.{bar}'. 1758 | And the corresponding \.{.toc} file entry is 1759 | `\.{\\ZZ \{Chinese \\klujj bar\\\\\}\{1\}\{1\}\{1\}\{Chinese bar\}}'. 1760 | 1761 | \vfill\end 1762 | 1763 | -------------------------------------------------------------------------------- /installit: -------------------------------------------------------------------------------- 1 | #! /bin/sh 2 | 3 | VERSION=2.0 4 | OWNER=${OWNER:-root} 5 | GROUP=${GROUP:-root} 6 | 7 | INSTALLBIN="install -g $GROUP -o $OWNER -m 755" 8 | INSTALLDOC="install -g $GROUP -o $OWNER -m 644" 9 | 10 | if [ -z $1 ]; then 11 | echo "Usage: installit " 12 | echo "You will want to set the following environment variables:" 13 | echo "" 14 | echo " Name Description (Default)" 15 | echo " ─────────────────────────────────" 16 | echo " TEXDIR Your texmf-local directory (/share/texmf-local)" 17 | echo " DOCDIR Documentation (/doc/chezweb-$VERSION)" 18 | echo " BINDIR Binaries (/bin)" 19 | echo " LIBDIR Libraries (/lib/chezweb)" 20 | exit 1 21 | fi 22 | 23 | PREFIX=$1 24 | TEXDIR=${TEXDIR:-$PREFIX/share/texmf-local} 25 | DOCDIR=${DOCDIR:-$PREFIX/doc/chezweb-$VERSION} 26 | BINDIR=${BINDIR:-$PREFIX/bin} 27 | LIBDIR=${LIBDIR:-$PREFIX/lib/chezweb} 28 | TEXSUB=${TEXDIR}/tex/generic 29 | 30 | echo "Installing to $PREFIX" 31 | echo "Tex Macros installed to $TEXDIR" 32 | echo "Documentation installed to $DOCDIR" 33 | echo "Binaries installed to $BINDIR" 34 | echo "Libraries installed to $LIBDIR" 35 | 36 | set -e 37 | 38 | echo -n "Making directories..." 39 | mkdir -p $TEXSUB $DOCDIR $BINDIR $LIBDIR 40 | echo "Done." 41 | 42 | # Copy documentation 43 | echo -n "Installing documentation..." 44 | $INSTALLDOC README chezweb.pdf doc/cwebman.pdf $DOCDIR 45 | echo "Done." 46 | 47 | # Install libraries 48 | echo -n "Installing libraries..." 49 | if [ -e runtime.so ]; then 50 | $INSTALLDOC runtime.so $LIBDIR 51 | fi 52 | $INSTALLDOC runtime.sls $LIBDIR 53 | $INSTALLDOC runtime.ss $LIBDIR 54 | $INSTALLDOC chezweb.ss $LIBDIR 55 | echo "Done." 56 | 57 | # Install binaries 58 | echo -n "Installing binaries..." 59 | $INSTALLBIN chezweave cheztangle $BINDIR 60 | echo "Done." 61 | 62 | # Install tex macros 63 | echo -n "Installing tex macros..." 64 | $INSTALLDOC chezwebmac.tex $TEXSUB 65 | echo "Done." 66 | -------------------------------------------------------------------------------- /tangleit: -------------------------------------------------------------------------------- 1 | #! /bin/sh 2 | 3 | set -e 4 | 5 | ./cheztangle.ss chezweb.w 6 | chmod +x cheztangle.ss 7 | chmod +x chezweave.ss 8 | 9 | if test "petite" = "$1"; then 10 | echo "Copying cheztangle.ss to cheztangle" 11 | cp cheztangle.ss cheztangle 12 | echo "Copying chezweave.ss to chezweave" 13 | cp chezweave.ss chezweave 14 | echo "Setting executable bit" 15 | chmod +x cheztangle chezweave 16 | else 17 | echo '(compile-program "cheztangle.ss")' | scheme -q 18 | echo '(compile-program "chezweave.ss")' | scheme -q 19 | echo "Renaming cheztangle.so to cheztangle" 20 | mv cheztangle.so cheztangle 21 | echo "Renaming chezweave.so to chezweave" 22 | mv chezweave.so chezweave 23 | echo '(compile-library "runtime.sls")' | scheme -q 24 | fi 25 | -------------------------------------------------------------------------------- /weaveit: -------------------------------------------------------------------------------- 1 | #! /bin/sh 2 | 3 | set -e 4 | mpost chezweb.mp 5 | echo "Renaming ChezWEB MetaPost diagrams." 6 | ./chezweave chezweb.w 7 | pdftex chezweb 8 | cd doc && pdftex cwebman && cd .. 9 | -------------------------------------------------------------------------------- /www/chezweb_screen.css: -------------------------------------------------------------------------------- 1 | @import "../../style.css"; 2 | 3 | .info_bar { 4 | float: right; 5 | width: 2in; 6 | border: 1px solid darkbrown; 7 | padding: 10px; 8 | margin: 0px 0px 10px 25px; 9 | background-color: rgb(155, 155, 140); 10 | } 11 | 12 | .info_bar dt { 13 | font-weight: bold; 14 | } 15 | 16 | .info_bar a { 17 | color: darkblue; 18 | } -------------------------------------------------------------------------------- /www/index.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 4 | 8 | 9 | 10 | ChezWEB: Hygienic Literate Programming — Sacrideo 11 | 13 | 15 | 16 | 17 | 18 |

19 | 20 | Sacrideo: Programming, Philosophy, &c. 21 | 22 |

23 | 24 |

ChezWEB: Hygienic Literate Programming

25 | 26 |
27 | Aaron W. Hsu 28 |  <arcfide@sacrideo.us> 29 |
30 | 31 |

17 February 2012

32 | 33 |
34 | 35 |

Introduction

36 | 37 |
38 |
Current Version
39 |
2.0
40 |
License
41 |
ISC
42 |
Download
43 |
44 | Source 45 |
46 | 47 | Threaded 64-bit Linux 48 | 49 |
50 | 51 | 64-bit Linux 52 | 53 |
54 |
Documentation
55 |
56 | 57 | Developer 58 | 59 |
60 | 61 | User's Guide (CWEB) 62 | 63 |
64 |
Project Site
65 |
GitHub
66 |
67 | 68 |

ChezWEB is a Knuthian style WEB programming system that is very compatible 69 | with the CWEB syntax. However, it supports a number of interesting 70 | features that are not included in the CWEB system, including hygienic 71 | preserving named sections. This means that you can relocate code in a 72 | WEB document without actually breaking the scoping rules of the Scheme 73 | language. ChezWEB is written for Chez Scheme and runs on the latest 74 | versions.

75 | 76 |

ChezWEB provides a unique perspective on documentation and code, 77 | extending the idea that code and documentation should not be separate 78 | things, but rather, that a program should be written like an essay, with 79 | formal and informal elements. The latter is written in TeX, and the 80 | former is written in the formal language of choice, in this case, 81 | Chez Scheme. This means that updating documentation is not an external 82 | matter done after the fact, when the important points are probably all 83 | forgotten. Instead, documentation becomes a part of the code artifact, 84 | and you can more easily keep the two synchronized and accurate.

85 | 86 |

ChezWEB encourages you to document the important things, such as why 87 | you wrote the code you did, the high-level architecture, and the details 88 | about why certain things were necessary or not, rather than the what. 89 | By writing code in small, manageable sections, your code should become more 90 | obvious and more modular, leaving you free to document the ideas and 91 | reasons behind your code, rather than the code itself. Documentation 92 | and code become intertwined in an useful path that makes it easier for 93 | people to read and understand you code as they go through it.

94 | 95 |

Together with this fundamental element of literate programming, 96 | ChezWEB follows the WEB tradition by providing a host of other useful 97 | features such as cross-referencing and indexing that are done automatically. 98 | You can also insert your own index entries, making it easy to get a 99 | picture of your code in different forms. ChezWEB also generates a 100 | table of contents based on your code so that you can get a high-level over 101 | view in pretty format.

102 | 103 |

The output of ChezWEB is a print quality document that makes it easy 104 | to read through code.

105 | 106 |

Combined with the hygienic guarantees of the ChezWEB system, 107 | literate programming gives you the opportunity to create more reliable, 108 | and, importantly, more readable programs that are actually enjoyable to 109 | go through, rather than painful. ChezWEB provides the guarantees you 110 | expect from working in Scheme (hygiene and referential transparency) in 111 | ways that make it convenient to write non-trivial programs.

112 | 113 |

Take a look, we think you'll find literate programming an enlightening 114 | and fulfilling programming paradigm.

115 | 116 |

Getting Started

117 | 118 |

The best way to get started with ChezWEB is to download one of the 119 | binary packages listed in the side bar. From there, you can read the 120 | chezweb developer documenation and the CWEB manual, as well as install 121 | the binaries for ChezWEB without needing to compile anything.

122 | 123 |

You can use the source distribution with either Chez Scheme or Petite 124 | Chez Scheme, if you prefer, or if you do not see your machine type listed. 125 |

126 | 127 |
128 | 129 |
130 | 131 | 135 | 136 |

137 | Hackers 138 |

139 | 140 | 141 | 142 | 143 | --------------------------------------------------------------------------------