diff options
Diffstat (limited to 'skribe/doc')
84 files changed, 4720 insertions, 0 deletions
diff --git a/skribe/doc/Makefile b/skribe/doc/Makefile new file mode 100644 index 0000000..934389e --- /dev/null +++ b/skribe/doc/Makefile @@ -0,0 +1,233 @@ +#*=====================================================================*/ +#* serrano/prgm/project/skribe/doc/Makefile */ +#* ------------------------------------------------------------- */ +#* Author : Manuel Serrano */ +#* Creation : Mon Sep 1 10:29:28 2003 */ +#* Last change : Wed Mar 10 11:16:48 2004 (serrano) */ +#* Copyright : 2003-04 Manuel Serrano */ +#* ------------------------------------------------------------- */ +#* The Makefile to build the Skribe documentation. */ +#*=====================================================================*/ +include ../etc/Makefile.config +include ../etc/$(SYSTEM)/Makefile.skb + +#*---------------------------------------------------------------------*/ +#* Compiler and tools */ +#*---------------------------------------------------------------------*/ +BINDIR = ../bin +LIBDIR = ../lib +LATEX = latex +DVIPS = dvips + +SKRIBEVERBOSE = -v1 +SKRIBEWARNING = -w1 +SFLAGS = $(SKRIBEVERBOSE) $(SKRIBEWARNING) \ + -I ../skr \ + -I skr \ + -P img \ + -S .. \ + --custom emit-sui=yes \ + --eval '(define *skribe-bin* "$(SKRIBE)")' \ + --eval '(define *skribebibtex-bin* "$(SKRIBEBIBTEX)")' + +#*---------------------------------------------------------------------*/ +#* Doc skr */ +#*---------------------------------------------------------------------*/ +_SKR = manual.skr env.skr api.skr extension.skr +SKR = $(_SKR:%=skr/%) + +#*---------------------------------------------------------------------*/ +#* Images */ +#*---------------------------------------------------------------------*/ +_IMG = bsd.gif lambda.gif linux.gif +IMG = $(_IMG:%=img/%) + +#*---------------------------------------------------------------------*/ +#* User document */ +#*---------------------------------------------------------------------*/ +_USERMAIN = user.skb +_USEROTHERS = start.skb syntax.skb \ + markup.skb document.skb \ + sectioning.skb toc.skb ornament.skb line.skb font.skb \ + justify.skb enumeration.skb \ + examples.skb colframe.skb figure.skb image.skb table.skb \ + footnote.skb char.skb \ + links.skb index.skb bib.skb prgm.skb \ + engine.skb htmle.skb latexe.skb xmle.skb \ + emacs.skb skribec.skb skribe-config.skb \ + lib.skb slide.skb package.skb +_USERSRC = start1.skb start2.skb start3.skb start4.skb start5.skb \ + api1.skb api2.skb api3.skb api4.skb api5.skb \ + api6.skb api7.skb api8.skb api9.skb api10.skb \ + api11.skb api12.skb api13.skb api14.skb api15.skb \ + api16.skb api17.skb api18.skb api19.skb api20.skb \ + links1.skb links2.skb \ + index1.skb index2.skb index3.skb \ + bib1.sbib bib2.skb bib3.skb bib4.skb bib5.skb bib6.skb \ + prgm1.skb prgm2.skb prgm3.skb slides.skb + +USERMAIN = $(_USERMAIN:%=user/%) +USEROTHERS = $(_USEROTHERS:%=user/%) +USERSRC = $(_USERSRC:%=user/src/%) +USERSKB = $(USERMAIN) $(USEROTHERS) $(USERSRC) + +#*---------------------------------------------------------------------*/ +#* User document */ +#*---------------------------------------------------------------------*/ +_DIRMAIN = dir.skb +_DIROTHERS = +_DIRSRC = + +DIRMAIN = $(_DIRMAIN:%=dir/%) +DIROTHERS = $(_DIROTHERS:%=dir/%) +DIRSRC = $(_DIRSRC:%=dir/src/%) +DIRSKB = $(DIRMAIN) $(DIROTHERS) $(DIRSRC) + +#*---------------------------------------------------------------------*/ +#* Suffixes */ +#*---------------------------------------------------------------------*/ +.SUFFIXES: +.SUFFIXES: .skb .man .html .sui + +#*---------------------------------------------------------------------*/ +#* All */ +#*---------------------------------------------------------------------*/ +.PHONY: user dir + +all: user dir +re: re.html re.dir + +#*---------------------------------------------------------------------*/ +#* pop */ +#*---------------------------------------------------------------------*/ +.PHONY: pop + +pop: + @ echo doc/Makefile doc/Makefile.dir + @ echo $(USERSKB:%=doc/%) + @ echo $(DIRSKB:%=doc/%) + @ echo $(SKR:%=doc/%) + @ echo $(IMG:%=doc/%) + +#*---------------------------------------------------------------------*/ +#* user */ +#*---------------------------------------------------------------------*/ +.PHONY: user re.html user.html + +user: user.html user.sui +user.html: html/user.html html/img/lambda.gif html/img/bsd.gif html/img/linux.gif +user.sui: html/user.sui + +user.ps: tex/user.dvi + (cd tex; $(DVIPS) user.dvi -o user.ps) + +user.dvi: tex/user.dvi +tex/user.dvi: tex/user.tex + (cd tex; $(LATEX) user.tex) + +html/user.html html/user.sui: html $(USERSKB) $(SKR) + $(MAKE) re.html + +tex/user.tex: tex $(USERSKB) $(SKR) tex/img/lambda.eps tex/img/bsd.eps tex/img/linux.eps + $(MAKE) re.tex + +# gif +html/img/lambda.gif: html/img img/lambda.gif + cp img/lambda.gif html/img/lambda.gif + +html/img/linux.gif: html/img img/linux.gif + cp img/linux.gif html/img/linux.gif + +html/img/bsd.gif: html/img img/bsd.gif + cp img/bsd.gif html/img/bsd.gif + +# eps image +tex/img/lambda.eps: tex/img img/lambda.gif + convert img/lambda.gif tex/img/lambda.eps + +tex/img/linux.eps: tex/img img/linux.gif + convert img/linux.gif tex/img/linux.eps + +tex/img/bsd.eps: tex/img img/bsd.gif + convert img/bsd.gif tex/img/bsd.eps + +re.html: + $(SKRIBE) $(SFLAGS) $(USERMAIN) \ + --base html -I user -S user \ + -o html/user.html + +re.tex: + $(SKRIBE) $(SFLAGS) $(USERMAIN) \ + --base tex -I user -S user \ + -o tex/user.tex + +#*---------------------------------------------------------------------*/ +#* dir */ +#*---------------------------------------------------------------------*/ +.PHONY: dir re.dir dir.html + +dir: dir.html +dir.html: html/dir.html + +html/dir.html: html $(DIRSKB) $(SKR) + $(MAKE) re.dir + +re.dir: + $(MAKE) -f Makefile.dir SKRIBE="$(SKRIBE)" BASE=html + +#*---------------------------------------------------------------------*/ +#* Misc */ +#*---------------------------------------------------------------------*/ +html: + mkdir -p html + +html/img: + mkdir -p html/img + +tex: + mkdir -p tex + +tex/img: + mkdir -p tex/img + +gethtml: + @ echo "html/user.html" + +#*---------------------------------------------------------------------*/ +#* install/uinstall */ +#*---------------------------------------------------------------------*/ +.PHONY: install uninstall + +install: $(DESTDIR)$(INSTALL_DOCDIR) $(DESTDIR)$(INSTALL_SKRDIR)/doc/skr + cp -r html/* $(DESTDIR)$(INSTALL_DOCDIR) \ + && chmod $(BMASK) $(DESTDIR)$(INSTALL_DOCDIR)/* \ + && chmod a+rx $(DESTDIR)$(INSTALL_DOCDIR)/img + cp -r skr/* $(DESTDIR)$(INSTALL_SKRDIR)/doc/skr \ + && chmod a+rx $(DESTDIR)$(INSTALL_SKRDIR)/doc \ + && chmod a+rx $(DESTDIR)$(INSTALL_SKRDIR)/doc/skr \ + && chmod $(BMASK) $(DESTDIR)$(INSTALL_SKRDIR)/doc/skr/* + cp Makefile.dir $(DESTDIR)$(INSTALL_DOCDIR) \ + && chmod $(BMASK) $(DESTDIR)$(INSTALL_DOCDIR)/Makefile.dir + cp dir/dir.skb $(DESTDIR)$(INSTALL_DOCDIR) \ + && chmod $(BMASK) $(DESTDIR)$(INSTALL_DOCDIR)/dir.skb + +uninstall: + $(RM) -rf $(DESTDIR)$(INSTALL_DOCDIR) + +$(DESTDIR)$(INSTALL_DOCDIR): + mkdir -p $(DESTDIR)$(INSTALL_DOCDIR) && chmod a+rx $(DESTDIR)$(INSTALL_DOCDIR) + + +$(DESTDIR)$(INSTALL_SKRDIR)/doc/skr: + mkdir -p $(DESTDIR)$(INSTALL_SKRDIR)/doc/skr \ + && chmod -R a+rx $(DESTDIR)$(INSTALL_SKRDIR)/doc + +#*---------------------------------------------------------------------*/ +#* Clean */ +#*---------------------------------------------------------------------*/ +.PHONY: clean + +clean: + $(RM) -rf html + $(RM) -rf tex + $(RM) -f img/bsd.eps img/linux.eps diff --git a/skribe/doc/Makefile.dir b/skribe/doc/Makefile.dir new file mode 100644 index 0000000..e35cf0b --- /dev/null +++ b/skribe/doc/Makefile.dir @@ -0,0 +1,22 @@ +#*=====================================================================*/ +#* serrano/prgm/project/skribe/doc/Makefile.dir */ +#* ------------------------------------------------------------- */ +#* Author : Manuel Serrano */ +#* Creation : Thu Jan 1 15:30:39 2004 */ +#* Last change : Wed Feb 4 09:19:03 2004 (serrano) */ +#* Copyright : 2004 Manuel Serrano */ +#* ------------------------------------------------------------- */ +#* The Makefile to build the Skribe directory. */ +#*=====================================================================*/ + +SKRIBE = skribe +SFLAGS = -I ../skr -I skr -P img -S .. -w0 +BASE = . +SPATH = + +.PHONY: re.dir + +re.dir: + $(SKRIBE) $(SFLAGS) $(SPATH) dir.skb \ + --base $(BASE) -I dir -S dir \ + -o $(BASE)/dir.html diff --git a/skribe/doc/dir/dir.skb b/skribe/doc/dir/dir.skb new file mode 100644 index 0000000..8c6d377 --- /dev/null +++ b/skribe/doc/dir/dir.skb @@ -0,0 +1,113 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/dir/dir.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Nov 28 10:37:39 2001 */ +;* Last change : Thu Jan 1 17:12:43 2004 (serrano) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe directory */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The Skribe documentation style */ +;*---------------------------------------------------------------------*/ +(skribe-load "web-book.skr") +(skribe-load "skr/env.skr") +(skribe-load "skr/manual.skr") +(skribe-load "skr/api.skr") + +;*---------------------------------------------------------------------*/ +;* Html configuration */ +;*---------------------------------------------------------------------*/ +(let ((he (find-engine 'html))) + (engine-custom-set! he 'web-book-main-browsing-extra + (lambda (n e) + (table :width 100. :border 0 :cellspacing 0 :cellpadding 0 + (tr (td :align 'left :valign 'top (bold "Skribe: ")) + (td :align 'right :valign 'top + (ref :url *skribe-user-doc-url* + :text "User Manual"))))))) + +;*---------------------------------------------------------------------*/ +;* The global index */ +;*---------------------------------------------------------------------*/ +(define *sui-index* (make-index "sui")) + +;*---------------------------------------------------------------------*/ +;* index-sui ... */ +;*---------------------------------------------------------------------*/ +(define (index-sui sui dir) + (sui-filter sui + (lambda (s) + (and (pair? s) (eq? (car s) 'marks))) + (lambda (e) + (let ((f (memq :file e)) + (k (memq :mark e)) + (c (memq :class e))) + (when (and (pair? f) + (pair? k) + (pair? c) + (string=? (cadr c) "public-definition")) + (index :index *sui-index* + :url (format "~a/~a#~a" dir (cadr f) (cadr k)) + (cadr k))) + #f)))) + +;*---------------------------------------------------------------------*/ +;* Intern all the sui files */ +;*---------------------------------------------------------------------*/ +(define extensions '()) + +(let loop ((files (directory->list "html"))) + (when (pair? files) + (if (string=? (suffix (car files)) "sui") + (let* ((f (string-append "html/" (car files))) + (sui (load-sui f))) + (if (not (string=? (car files) "user.sui")) + (set! extensions (cons sui extensions))) + (index-sui sui (dirname (car files))))) + (loop (cdr files)))) +(let loop ((files (directory->list "."))) + (when (pair? files) + (if (string=? (suffix (car files)) "sui") + (let* ((f (car files)) + (sui (load-sui f))) + (if (not (string=? (car files) "user.sui")) + (set! extensions (cons sui extensions))) + (index-sui sui (dirname f)))) + (loop (cdr files)))) + +;*---------------------------------------------------------------------*/ +;* The document */ +;*---------------------------------------------------------------------*/ +(document :title "Skribe directory" + :author (list (author :name "Erick Gallesio" + :affiliation "Université de Nice - Sophia Antipolis" + :address '("930 route des Colles, BP 145" + "F-06903 Sophia Antipolis, Cedex" + "France") + :email (mailto "eg@essi.fr")) + (author :name "Manuel Serrano" + :affiliation "Inria Sophia-Antipolis" + :address `("2004 route des Lucioles - BP 93" + "F-06902 Sophia Antipolis, Cedex" + "France") + :url (ref :url *serrano-url*) + :email (mailto *serrano-mail*))) + + (linebreak 1) + +;;; extensions +(if (pair? extensions) + (section :title "Installed extensions" :number #f + (itemize (map (lambda (e) + (item :key (ref :url (sui-file e) :text (sui-title e)) + (let ((d (sui-key e :description))) + (if d (list ": " d) #f)))) + extensions)))) + +;;; global Index +(section :title "Global Markup Index" :number #f + (mark "global index") + (the-index :column 3 *sui-index*))) diff --git a/skribe/doc/img/bsd.gif b/skribe/doc/img/bsd.gif Binary files differnew file mode 100644 index 0000000..e406ba6 --- /dev/null +++ b/skribe/doc/img/bsd.gif diff --git a/skribe/doc/img/lambda.gif b/skribe/doc/img/lambda.gif Binary files differnew file mode 100644 index 0000000..9c46b7d --- /dev/null +++ b/skribe/doc/img/lambda.gif diff --git a/skribe/doc/img/linux.gif b/skribe/doc/img/linux.gif Binary files differnew file mode 100644 index 0000000..fa764bd --- /dev/null +++ b/skribe/doc/img/linux.gif diff --git a/skribe/doc/skr/api.skr b/skribe/doc/skr/api.skr new file mode 100644 index 0000000..a27c3a4 --- /dev/null +++ b/skribe/doc/skr/api.skr @@ -0,0 +1,575 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/skr/api.skr */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 07:45:33 2003 */ +;* Last change : Tue Apr 6 06:51:34 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe style for documenting Lisp APIs. */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Html configuration */ +;*---------------------------------------------------------------------*/ +(let* ((he (find-engine 'html)) + (tro (markup-writer-get 'tr he))) + (markup-writer 'tr he + :class 'api-table-header + :options '(:width :bg) + :action (lambda (n e) + (let ((c (engine-custom e 'section-title-background))) + (markup-option-add! n :bg c) + (output n e tro)))) + (markup-writer 'tr he + :class 'api-table-prototype + :options '(:width :bg) + :action (lambda (n e) + (let ((c (engine-custom e 'title-background))) + (markup-option-add! n :bg c) + (output n e tro)))) + (markup-writer 'tr he + :class 'api-symbol-prototype + :options '(:width :bg) + :action (lambda (n e) + (let ((c (engine-custom e 'title-background))) + (markup-option-add! n :bg c) + (output n e tro))))) + +;*---------------------------------------------------------------------*/ +;* LaTeX configuration */ +;*---------------------------------------------------------------------*/ +(let* ((le (find-engine 'latex)) + (tro (markup-writer-get 'tr le))) + (markup-writer 'tr le + :class 'api-table-prototype + :options '(:width :bg) + :action #f) + (markup-writer 'tr le + :class 'api-table-header + :options '(:width :bg) + :action (lambda (n e) + (let ((c (engine-custom e 'section-title-background))) + (markup-option-add! n :bg c) + (output n e tro))))) + +;*---------------------------------------------------------------------*/ +;* api-search-definition ... */ +;* ------------------------------------------------------------- */ +;* Find a definition inside a source file. */ +;*---------------------------------------------------------------------*/ +(define (api-search-definition id file pred) + (let ((f (find-file/path file *skribe-source-path*))) + (if (not (string? f)) + (skribe-error 'api-search-definition + (format "Can't find source file `~a' in path" file) + *skribe-source-path*) + (with-input-from-file f + (lambda () + (let loop ((exp (read))) + (if (eof-object? exp) + (skribe-error 'api-search-definition + (format "Can't find `~a' definition" id) + file) + (or (pred id exp) (loop (read)))))))))) + +;*---------------------------------------------------------------------*/ +;* api-compare-set ... */ +;* ------------------------------------------------------------- */ +;* This function compares two sets. It returns either #t */ +;* is they are equal, or two subsets which contain elements */ +;* not present in the arguments. For instance: */ +;* (api-compare-set '(foo bar) '(bar foo)) ==> #t */ +;* (api-compare-set '(foo gee) '(gee bar)) ==> '((foo) (bar)) */ +;*---------------------------------------------------------------------*/ +(define (api-compare-set s1 s2) + (let ((d1 (filter (lambda (x) (not (memq x s2))) s1)) + (d2 (filter (lambda (x) (not (memq x s1))) s2))) + (or (and (null? d1) (null? d2)) + (list d1 d2)))) + +;*---------------------------------------------------------------------*/ +;* keyword->symbol ... */ +;*---------------------------------------------------------------------*/ +(define (keyword->symbol kwd) + (let ((s (keyword->string kwd))) + (if (char=? #\: (string-ref s 0)) + ;; Bigloo + (string->symbol (substring s 1 (string-length s))) + ;; STklos + (string->symbol s)))) + +;*---------------------------------------------------------------------*/ +;* define-markup? ... */ +;*---------------------------------------------------------------------*/ +(define (define-markup? id o) + (match-case o + (((or define-markup define define-inline) + ((? (lambda (x) (eq? x id))) . (? (lambda (x) (or (pair? x) (null? x))))) . ?-) + o) + ((define-simple-markup (? (lambda (x) (eq? x id)))) + o) + ((define-simple-container (? (lambda (x) (eq? x id)))) + o) + (else + #f))) + +;*---------------------------------------------------------------------*/ +;* make-engine? ... */ +;*---------------------------------------------------------------------*/ +(define (make-engine? id o) + (match-case o + (((or make-engine copy-engine) (quote (? (lambda (x) (eq? x id)))) . ?-) + o) + ((quasiquote . ?-) + #f) + ((quote . ?-) + #f) + ((?a . ?d) + (or (make-engine? id a) (make-engine? id d))) + (else + #f))) + +;*---------------------------------------------------------------------*/ +;* make-engine-custom ... */ +;*---------------------------------------------------------------------*/ +(define (make-engine-custom def) + (match-case (memq :custom def) + ((:custom (quote ?custom) . ?-) + custom) + ((:custom ?custom . ?-) + (eval custom)) + (else + '()))) + +;*---------------------------------------------------------------------*/ +;* define-markup-formals ... */ +;* ------------------------------------------------------------- */ +;* Returns the formal parameters of a define-markup (not the */ +;* options). */ +;*---------------------------------------------------------------------*/ +(define (define-markup-formals def) + (match-case def + ((?- (?- . ?args) . ?-) + (if (symbol? args) + (list args) + (let loop ((args args) + (res '())) + (cond + ((null? args) + (reverse! res)) + ((symbol? args) + (reverse! (cons args res))) + ((not (symbol? (car args))) + (reverse! res)) + (else + (loop (cdr args) (cons (car args) res))))))) + ((define-simple-markup ?-) + '()) + ((define-simple-container ?-) + '()) + (else + (skribe-error 'define-markup-formals + "Illegal `define-markup' form" + def)))) + +;*---------------------------------------------------------------------*/ +;* define-markup-options ... */ +;* ------------------------------------------------------------- */ +;* Returns the options parameters of a define-markup. */ +;*---------------------------------------------------------------------*/ +(define (define-markup-options def) + (match-case def + ((?- (?- . ?args) . ?-) + (if (not (list? args)) + '() + (let ((keys (memq #!key args))) + (if (pair? keys) + (cdr keys) + '())))) + ((define-simple-markup ?-) + '((ident #f) (class #f))) + ((define-simple-container ?-) + '((ident #f) (class #f))) + (else + (skribe-error 'define-markup-formals + "Illegal `define-markup' form" + def)))) + +;*---------------------------------------------------------------------*/ +;* define-markup-rest ... */ +;* ------------------------------------------------------------- */ +;* Returns the rest parameter of a define-markup. */ +;*---------------------------------------------------------------------*/ +(define (define-markup-rest def) + (match-case def + ((?- (?- . ?args) . ?-) + (if (not (pair? args)) + args + (let ((l (last-pair args))) + (if (symbol? (cdr l)) + (cdr l) + (let ((rest (memq #!rest args))) + (if (pair? rest) + (if (or (not (pair? (cdr rest))) + (not (symbol? (cadr rest)))) + (skribe-error 'define-markup-rest + "Illegal `define-markup' form" + def) + (cadr rest)) + #f)))))) + ((define-simple-markup ?-) + 'node) + ((define-simple-container ?-) + 'node) + (else + (skribe-error 'define-markup-formals + "Illegal `define-markup' form" + def)))) + +;*---------------------------------------------------------------------*/ +;* doc-check-arguments ... */ +;*---------------------------------------------------------------------*/ +(define (doc-check-arguments id args dargs) + (if (not args) + (skribe-error 'doc-check-arguments id args)) + (if (not dargs) + (skribe-error 'doc-check-arguments id dargs)) + (let* ((s1 (map (lambda (x) (if (pair? x) (car x) x)) args)) + (s2 (map (lambda (x) + (let ((i (car x))) + (if (keyword? i) + (keyword->symbol i) + i))) + dargs)) + (d (api-compare-set s1 s2))) + (if (pair? d) + (let ((d1 (car d)) + (d2 (cadr d))) + (if (pair? d1) + (skribe-error 'doc-markup + (format "~a: missing descriptions" id) + d1) + (skribe-error 'doc-markup + (format "~a: extra descriptions" id) + d2)))))) + +;*---------------------------------------------------------------------*/ +;* exp->skribe ... */ +;*---------------------------------------------------------------------*/ +(define (exp->skribe exp) + (cond + ((number? exp) exp) + ((string? exp) (string-append "\"" exp "\"")) + ((eq? exp #f) "#f") + ((eq? exp #t) "#t") + ((symbol? exp) (symbol->string exp)) + ((equal? exp '(quote ())) "'()") + ((ast? exp) + (table :cellpadding 0 :cellspacing 0 + (tr (td :align 'left exp)))) + (else + (match-case exp + ((quote (and ?sym (? symbol?))) + (string-append "'" (symbol->string sym))) + (else + (with-output-to-string (lambda () (write exp)))))))) + +;*---------------------------------------------------------------------*/ +;* doc-markup-proto ... */ +;*---------------------------------------------------------------------*/ +(define (doc-markup-proto id options formals rest) + (define (option opt) + (if (pair? opt) + (if (eq? (cadr opt) #f) + (list " [" (keyword (car opt)) "]") + (list " [" (keyword (car opt)) " " + (code (exp->skribe (cadr opt))) "]")) + (list " " (keyword opt)))) + (define (formal f) + (list " " (param f))) + (code (list (bold "(") (bold :class 'api-proto-ident (format "~a" id))) + (map option (sort options + (lambda (s1 s2) + (cond + ((and (pair? s1) (not (pair? s2))) + #f) + ((and (pair? s2) (not (pair? s1))) + #t) + (else + #t))))) + (if (pair? formals) + (map formal formals)) + (if rest (list " " (param rest))) + (bold ")"))) + +;*---------------------------------------------------------------------*/ +;* doc-markup ... */ +;*---------------------------------------------------------------------*/ +(define-markup (doc-markup id args + #!rest + opts + #!key + (writer-id #f) + (common-args '((:ident "The node identifier.") + (:class "The node class."))) + (ignore-args '(&skribe-eval-location)) + (force-args '()) + (idx *markup-index*) + (idx-note "definition") + (idx-suffix #f) + (source "src/common/api.scm") + (def #f) + (see-also '()) + (others '()) + (force-engines '()) + (engines *api-engines*) + (sui #f) + &skribe-eval-location) + (define (opt-engine-support opt) + ;; find the engines providing a writer for id + (map (lambda (e) + (let* ((id (engine-ident e)) + (s (symbol->string id))) + (if (engine-format? "latex") + (list s " ") + (list (if sui + (ref :skribe sui + :mark (string-append s "-engine") + :text s) + (ref :mark (string-append s "-engine") + :text s)) + " ")))) + (if (pair? force-engines) + force-engines + (filter (lambda (e) + (or (memq opt '(:ident :class)) + (memq opt force-args) + (let ((w (markup-writer-get (or writer-id id) + e))) + (cond + ((not (writer? w)) + #f) + (else + (let ((o (writer-options w))) + (cond + ((eq? o 'all) + #t) + ((not (pair? o)) + #f) + (else + (memq opt o))))))))) + engines)))) + (cond + ((and def source) + (skribe-error 'doc-markup "source and def both specified" id)) + ((and (not def) (not source)) + (skribe-error 'doc-markup "source or def must be specified" id)) + (else + (let* ((d (or def (api-search-definition id source define-markup?))) + (od (map (lambda (o) + (api-search-definition o source define-markup?)) + others)) + (args (append common-args args)) + (formals (define-markup-formals d)) + (fformals (filter (lambda (s) + (let ((c (assq s args))) + (not + (and (pair? c) + (eq? (cadr c) 'ignore))))) + formals)) + (options (filter (lambda (s) + (not (memq s ignore-args))) + (define-markup-options d))) + (dformals (filter (lambda (x) + (symbol? (car x))) + args)) + (doptions (filter (lambda (x) + (and (keyword? (car x)) + ;; useful for STklos only + (not (eq? (car x) #!rest)))) + args)) + (drest (filter (lambda (x) + (eq? #!rest (car x))) + args)) + (dargs (and (pair? drest) (cadr (car drest)))) + (p+ (cons (doc-markup-proto id options fformals dargs) + (map (lambda (id def) + (doc-markup-proto + id + (define-markup-options def) + (define-markup-formals def) + dargs)) + others od)))) + ;; doc table + (define (doc-markup.html) + (let ((df (map (lambda (f) + (tr :bg *prgm-skribe-color* + (td :colspan 2 :width 20. :align 'left + (param (car f)) ) + (td :align 'left :width 80. (cadr f)))) + dformals)) + (dr (and (pair? drest) + (tr :bg *prgm-skribe-color* + (td :align 'left + :valign 'top + :colspan 2 + :width 20. + (param (cadr (car drest)))) + (td :align 'left :width 80. + (caddr (car drest)))))) + (do (map (lambda (f) + (tr :bg *prgm-skribe-color* + (td :align 'left + :valign 'top + :width 10. + (param (car f))) + (td :align 'left + :valign 'top + :width 20. + (opt-engine-support (car f))) + (td :align 'left :width 70. (cadr f)))) + doptions)) + (so (map (lambda (x) + (let ((s (symbol->string x))) + (list + (ref :mark s :text (code s)) + " "))) + see-also))) + (table :border (if (engine-format? "latex") 1 0) + :width (if (engine-format? "latex") #f *prgm-width*) + `(,(tr :class 'api-table-prototype + (th :colspan 3 :align 'left :width *prgm-width* + "prototype")) + ,@(map (lambda (p) + (tr :bg *prgm-skribe-color* + (td :colspan 3 :width *prgm-width* + :align 'left p))) + p+) + ,@(if (pair? do) + `(,(tr :class 'api-table-header + (th :align 'left "option" + :width 10.) + (th :align 'center "engines" + :width 20.) + (th "description")) + ,@do) + '()) + ,@(if (or (pair? df) dr) + `(,(tr :class 'api-table-header + (th :colspan 2 + :align 'left + :width 30. + "argument") + (th "description")) + ,@(if (pair? df) df '()) + ,@(if dr (list dr) '())) + '()) + ,@(if (pair? so) + `(,(tr :class 'api-table-header + (th :colspan 3 :align 'left + (it "See also"))) + ,(tr :bg *prgm-skribe-color* + (td :colspan 3 :align 'left so))) + '()))))) + ;; doc enumerate + (define (doc-markup.latex) + (let ((df (map (lambda (f) + (item :key (param (car f)) (cadr f))) + dformals)) + (dr (if (pair? drest) + (list (item :key (param (cadr (car drest))) + (caddr (car drest)))) + '())) + (do (map (lambda (f) + (item :key (param (car f)) + (list (opt-engine-support (car f)) + (cadr f)))) + doptions)) + (so (map (lambda (x) + (let ((s (symbol->string x))) + (list + (ref :mark s :page #t + :text [,(code s), p.]) + " "))) + see-also))) + (list (center + (frame :margin 5 :border 0 :width *prgm-width* + (color :class 'api-table-prototype + :margin 5 :width 100. :bg "#ccccff" + p+))) + (when (pair? do) + (subsubsection :title "Options" :number #f :toc #f + (description do))) + (when (or (pair? df) (pair? dr)) + (subsubsection :title "Parameters" :number #f :toc #f + (description (append df dr)))) + (when (pair? so) + (subsubsection :title "See also" :number #f :toc #f + (p so) + (! "\\noindent")))))) + ;; check all the descriptions + (doc-check-arguments id formals dformals) + (doc-check-arguments id options doptions) + (if (and (pair? drest) (not (define-markup-rest d))) + (skribe-error 'doc-markup "No rest argument for" id) + options) + (list (mark :class "public-definition" (symbol->string id)) + (map (lambda (i) (mark (symbol->string i))) others) + (map (lambda (i) + (let ((is (symbol->string i))) + (index (if (string? idx-suffix) + (string-append is idx-suffix) + is) + :index idx + :note idx-note))) + (cons id others)) + (cond + ((engine-format? "latex") + (doc-markup.latex)) + (else + (center (doc-markup.html))))))))) + +;*---------------------------------------------------------------------*/ +;* doc-engine ... */ +;*---------------------------------------------------------------------*/ +(define-markup (doc-engine id args + #!rest + opts + #!key + (idx *custom-index*) + source + (def #f)) + (cond + ((and def source) + (skribe-error 'doc-engine "source and def both specified" id)) + ((and (not def) (not source)) + (skribe-error 'doc-engine "source or def must be specified" id)) + (else + (let* ((d (or def (api-search-definition id source make-engine?))) + (c (make-engine-custom d))) + (doc-check-arguments id c args) + (cond + ((engine-format? "latex") + #f) + (else + (center + (apply table + :width *prgm-width* + (tr :class 'api-table-header + (th :align 'left :width 20. "custom") + (th :width 10. "default") + (th "description")) + (map (lambda (r) + (tr :bg *prgm-skribe-color* + (td :align 'left :valign 'top + (list (index (symbol->string (car r)) + :index idx + :note (format "~a custom" id)) + (symbol->string (car r)))) + (let ((def (assq (car r) c))) + (td :valign 'top + (code (exp->skribe (cadr def))))) + (td :align 'left :valign 'top (cadr r)))) + (filter cadr args)))))))))) + diff --git a/skribe/doc/skr/env.skr b/skribe/doc/skr/env.skr new file mode 100644 index 0000000..09d5146 --- /dev/null +++ b/skribe/doc/skr/env.skr @@ -0,0 +1,32 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/skr/env.skr */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Mon Sep 1 10:22:42 2003 */ +;* Last change : Thu Jan 29 06:48:54 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The environment variables for the documentation. */ +;*=====================================================================*/ + +(define *serrano-url* "http://www.inria.fr/mimosa/Manuel.Serrano") +(define *serrano-mail* "Manuel.Serrano@sophia.inria.fr") +(define *html-url* "http://www.w3.org/TR/html4") +(define *html-form* "interact/forms.html") +(define *emacs-url* "http://www.gnu.org/software/emacs") +(define *xemacs-url* "http://www.xemacs.org") +(define *texinfo-url* "http://www.texinfo.org") +(define *r5rs-url* "http://www.inria.fr/mimosa/fp/Bigloo/doc/r5rs.html") +(define *bigloo-url* "http://www.inria.fr/mimosa/fp/Bigloo") +(define *skribe-user-doc-url* (string-append (skribe-doc-dir) "/user.html")) +(define *skribe-dir-doc-url* (string-append (skribe-doc-dir) "/dir.html")) + +(define *prgm-width* 97.) +(define *prgm-skribe-color* "#ffffcc") +(define *prgm-default-color* "#ffffcc") +(define *prgm-xml-color* "#ffcccc") +(define *prgm-example-color* "#ccccff") +(define *disp-color* "#ccffcc") +(define *header-color* "#cccccc") + +(define *api-engines* (map find-engine '(html latex xml))) diff --git a/skribe/doc/skr/extension.skr b/skribe/doc/skr/extension.skr new file mode 100644 index 0000000..ce10ce7 --- /dev/null +++ b/skribe/doc/skr/extension.skr @@ -0,0 +1,95 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/skr/extension.skr */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Tue Dec 23 07:18:36 2003 */ +;* Last change : Fri Jan 2 21:25:49 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe package for documenting extensions */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* extension */ +;*---------------------------------------------------------------------*/ +(define-markup (extension #!rest opt + #!key (ident (symbol->string (gensym 'extension))) + (class "extension") + title html-title ending author description + (env '())) + (new document + (markup 'extension) + (ident ident) + (class class) + (options (the-options opt)) + (body (the-body opt)) + (env (append env + (list (list 'example-counter 0) (list 'example-env '()) + (list 'chapter-counter 0) (list 'chapter-env '()) + (list 'section-counter 0) (list 'section-env '()) + (list 'footnote-counter 0) (list 'footnote-env '()) + (list 'figure-counter 0) (list 'figure-env '())))))) + +;*---------------------------------------------------------------------*/ +;* html engine */ +;*---------------------------------------------------------------------*/ +(let ((he (find-engine 'html))) + (engine-custom-set! he 'web-book-main-browsing-extra + (lambda (n e) + (let ((i (let ((m (find-markup-ident "Index"))) + (and (pair? m) (car m))))) + (if (not i) + (table :width 100. :border 0 :cellspacing 0 :cellpadding 0 + (tr (td :align 'left :valign 'top (bold "Skribe: ")) + (td :align 'right :valign 'top + (ref :url *skribe-dir-doc-url* + :text "Directory"))) + (tr (td) + (td :align 'right :valign 'top + (ref :url *skribe-user-doc-url* + :text "User Manual")))) + (table :width 100. :border 0 :cellspacing 0 :cellpadding 0 + (tr (td :align 'left :valign 'top (bold "index:")) + (td :align 'right (ref :handle (handle i)))) + (tr (td :align 'left :valign 'top (bold "Skribe: ")) + (td :align 'right :valign 'top + (ref :url *skribe-dir-doc-url* + :text "Directory"))) + (tr (td) + (td :align 'right :valign 'top + (ref :url *skribe-user-doc-url* + :text "User Manual")))))))) + (default-engine-set! he)) + +;*---------------------------------------------------------------------*/ +;* extension-sui ... */ +;*---------------------------------------------------------------------*/ +(define (extension-sui n e) + (define (sui) + (display "(sui \"") + (skribe-eval (markup-option n :title) html-title-engine) + (display "\"\n") + (printf " :file ~s\n" (sui-referenced-file n e)) + (printf " :description ~s\n" (markup-option n :description)) + (sui-marks n e) + (display " )\n")) + (if (string? *skribe-dest*) + (let ((f (format "~a.sui" (prefix *skribe-dest*)))) + (with-output-to-file f sui)) + (sui))) + +;*---------------------------------------------------------------------*/ +;* project ... */ +;*---------------------------------------------------------------------*/ +(markup-writer 'extension + :options '(:title :html-title :ending :author :description) + :action (lambda (n e) + (output n e (markup-writer-get 'document he))) + :after (lambda (n e) + (if (engine-custom e 'emit-sui) + (extension-sui n e)))) + +;*---------------------------------------------------------------------*/ +;* Restore the base engine */ +;*---------------------------------------------------------------------*/ +(default-engine-set! (find-engine 'base)) diff --git a/skribe/doc/skr/manual.skr b/skribe/doc/skr/manual.skr new file mode 100644 index 0000000..1982237 --- /dev/null +++ b/skribe/doc/skr/manual.skr @@ -0,0 +1,281 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/skr/manual.skr */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Mon Sep 1 11:24:19 2003 */ +;* Last change : Mon Sep 13 19:18:48 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe manuals and documentation pages style */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Base configuration */ +;*---------------------------------------------------------------------*/ +(let ((be (find-engine 'base))) + (markup-writer 'example be + :options '(:legend :number) + :action (lambda (n e) + (let ((ident (markup-ident n)) + (number (markup-option n :number)) + (legend (markup-option n :legend))) + (skribe-eval (mark ident) e) + (skribe-eval (center + (markup-body n) + (if number (bold (format "Ex. ~a: " number))) + legend) + e))))) + +;*---------------------------------------------------------------------*/ +;* html-browsing-extra ... */ +;*---------------------------------------------------------------------*/ +(define (html-browsing-extra n e) + (let ((i1 (let ((m (find-markup-ident "Index"))) + (and (pair? m) (car m)))) + (i2 (let ((m (find-markup-ident "markups-index"))) + (and (pair? m) (car m))))) + (cond + ((not i1) + (skribe-error 'left-margin "Can't find section" "Index")) + ((not i2) + (skribe-error 'left-margin "Can't find chapter" "Standard Markups")) + (else + (table :width 100. + :border 0 + :cellspacing 0 :cellpadding 0 + (tr (td :align 'left :valign 'top (bold "index:")) + (td :align 'right (ref :handle (handle i1) :text "Global"))) + (tr (td :align 'left :valign 'top (bold "markups:")) + (td :align 'right (ref :handle (handle i2) :text "Index"))) + (tr (td :align 'left :valign 'top (bold "extensions:")) + (td :align 'right (ref :url *skribe-dir-doc-url* + :text "Directory")))))))) + +;*---------------------------------------------------------------------*/ +;* Html configuration */ +;*---------------------------------------------------------------------*/ +(let* ((he (find-engine 'html)) + (bd (markup-writer-get 'bold he))) + (markup-writer 'bold he + :class 'api-proto-ident + :before "<font color=\"red\">" + :action (lambda (n e) (output n e bd)) + :after "</font>") + (engine-custom-set! he 'web-book-main-browsing-extra html-browsing-extra) + (engine-custom-set! he 'favicon "lambda.gif")) + +;*---------------------------------------------------------------------*/ +;* LaTeX */ +;*---------------------------------------------------------------------*/ +(let* ((le (find-engine 'latex)) + (opckg (engine-custom le 'usepackage)) + (lpckg "\\usepackage{fullpage}\n\\usepackage{eurosym}\n") + (npckg (if (string? opckg) + (string-append lpckg opckg) + lpckg))) + (engine-custom-set! le 'documentclass "\\documentclass{book}") + (engine-custom-set! le 'usepackage npckg)) + +;*---------------------------------------------------------------------*/ +;* prgm ... */ +;*---------------------------------------------------------------------*/ +(define-markup (prgm #!rest opts #!key (language skribe) (line #f) (file #f) (definition #f)) + (let* ((c (cond + ((eq? language skribe) *prgm-skribe-color*) + ((eq? language xml) *prgm-xml-color*) + (else *prgm-default-color*))) + (sc (cond + ((and file definition) + (source :language language :file file :definition definition)) + (file + (source :language language :file file)) + (else + (source :language language (the-body opts))))) + (pr (cond + (line + (prog :line line sc)) + (else + (pre sc))))) + (center + (frame :margin 5 :border 0 :width *prgm-width* + (color :margin 5 :width 100. :bg c pr))))) + +;*---------------------------------------------------------------------*/ +;* disp ... */ +;*---------------------------------------------------------------------*/ +(define-markup (disp #!rest opts #!key (verb #f) (line #f) (bg *disp-color*)) + (if (engine-format? "latex") + (if verb + (pre (the-body opts)) + (the-body opts)) + (center + (frame :margin 5 :border 0 :width *prgm-width* + (color :margin 5 :width 100. :bg bg + (if verb + (pre (the-body opts)) + (the-body opts))))))) + +;*---------------------------------------------------------------------*/ +;* keyword ... */ +;*---------------------------------------------------------------------*/ +(define-markup (keyword arg) + (new markup + (markup '&source-key) + (body (cond + ((keyword? arg) + (keyword->string arg)) + ((symbol? arg) + (string-append ":" (symbol->string arg))) + (else + arg))))) + +;*---------------------------------------------------------------------*/ +;* param ... */ +;*---------------------------------------------------------------------*/ +(define-markup (param arg) + (cond + ((keyword? arg) + (keyword arg)) + ((symbol? arg) + (code (symbol->string arg))) + (else + arg))) + +;*---------------------------------------------------------------------*/ +;* example ... */ +;*---------------------------------------------------------------------*/ +(define-markup (example #!rest opts #!key legend class) + (new container + (markup 'example) + (ident (symbol->string (gensym 'example))) + (class class) + (required-options '(:legend :number)) + (options `((:number + ,(new unresolved + (proc (lambda (n e env) + (resolve-counter n env 'example #t))))) + ,@(the-options opts :ident :class))) + (body (the-body opts)))) + +;*---------------------------------------------------------------------*/ +;* example-produce ... */ +;*---------------------------------------------------------------------*/ +(define-markup (example-produce example . produce) + (list (it "Example:") + example + (if (pair? produce) + (list (paragraph "Produces:") (car produce))))) + +;*---------------------------------------------------------------------*/ +;* markup-ref ... */ +;*---------------------------------------------------------------------*/ +(define-markup (markup-ref mk) + (ref :mark mk :text (code mk))) + +;*---------------------------------------------------------------------*/ +;* &the-index ... */ +;*---------------------------------------------------------------------*/ +(markup-writer '&the-index + :class 'markup-index + :options '(:column) + :before (lambda (n e) + (output (markup-option n 'header) e)) + :action (lambda (n e) + (define (make-mark-entry n fst) + (let ((l (tr :class 'index-mark-entry + (td :colspan 2 :align 'left + (bold (it (sf n))))))) + (if fst + (list l) + (list (tr (td :colspan 2)) l)))) + (define (make-primary-entry n p) + (let* ((note (markup-option n :note)) + (b (markup-body n))) + (when p + (markup-option-add! b :text + (list (markup-option b :text) + ", p.")) + (markup-option-add! b :page #t)) + (tr :class 'index-primary-entry + (td :colspan 2 :valign 'top :align 'left b)))) + (define (make-column ie p) + (let loop ((ie ie) + (f #t)) + (cond + ((null? ie) + '()) + ((not (pair? (car ie))) + (append (make-mark-entry (car ie) f) + (loop (cdr ie) #f))) + (else + (cons (make-primary-entry (caar ie) p) + (loop (cdr ie) #f)))))) + (define (make-sub-tables ie nc p) + (define (split-list l num) + (let loop ((l l) + (i 0) + (acc '()) + (res '())) + (cond + ((null? l) + (reverse! (cons (reverse! acc) res))) + ((= i num) + (loop l + 0 + '() + (cons (reverse! acc) res))) + (else + (loop (cdr l) + (+ i 1) + (cons (car l) acc) + res))))) + (let* ((l (length ie)) + (w (/ 100. nc)) + (iepc (let ((d (/ l nc))) + (if (integer? d) + (inexact->exact d) + (+ 1 (inexact->exact (truncate d)))))) + (split (split-list ie iepc))) + (tr (map (lambda (ies) + (td :valign 'top :width w + (if (pair? ies) + (table :width 100. (make-column ies p)) + ""))) + split)))) + (let* ((ie (markup-body n)) + (nc (markup-option n :column)) + (pref (eq? (engine-custom e 'index-page-ref) #t)) + (loc (ast-loc n)) + (t (cond + ((null? ie) + "") + ((or (not (integer? nc)) (= nc 1)) + (table :width 100. :&skribe-eval-location loc + (make-column ie pref))) + (else + (table :width 100. :&skribe-eval-location loc + (make-sub-tables ie nc pref)))))) + (output (skribe-eval t e) e)))) + +;*---------------------------------------------------------------------*/ +;* compiler-command ... */ +;*---------------------------------------------------------------------*/ +(define-markup (compiler-command bin . opts) + (disp :verb #t + (color :fg "red" (bold bin)) + (map (lambda (o) + (list " [" (it o) "]")) + opts) + "...")) + +;*---------------------------------------------------------------------*/ +;* compiler-options ... */ +;*---------------------------------------------------------------------*/ +(define-markup (compiler-options bin) + (skribe-message " [executing: ~a --options]\n" bin) + (let ((port (open-input-file (format "| ~a --options" bin)))) + (let ((opts (read port))) + (close-input-port port) + (apply description (map (lambda (opt) (item :key (bold (car opt)) + (cadr opt) ".")) + opts))))) diff --git a/skribe/doc/user/bib.skb b/skribe/doc/user/bib.skb new file mode 100644 index 0000000..a006a9b --- /dev/null +++ b/skribe/doc/user/bib.skb @@ -0,0 +1,252 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/bib.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sun Dec 2 10:02:56 2001 */ +;* Last change : Tue Oct 26 21:41:19 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe index */ +;*=====================================================================*/ + +(bibliography "user/src/bib1.sbib") + +;*---------------------------------------------------------------------*/ +;* Index */ +;*---------------------------------------------------------------------*/ +(chapter :title "Bibliographies" + + (p [ +Skribe supports bibliographies. In order to use bibliography +,(markup-ref "ref") it is needed to:]) + (itemize + (item [ +Use the default pre-existing ,(emph "bibliography table") or create a +custom one.]) + (item [ +Provide a ,(emph "bibliography database").]) + (item [ +Load the database by the mean of the ,(markup-ref "bibliography") +Skribe function call.]) + (item [ +Reference to a bibliography entry, with a ,(markup-ref "ref") Skribe +function call.])) + +;*---------------------------------------------------------------------*/ +;* Bibliography tables */ +;*---------------------------------------------------------------------*/ +(section :title "Bibliography tables" + + (p [ +This section describes the function of using and creating bibliography +tables.]) + + (p [The predicate ,(code "bib-table?") returns ,(code "#t") if and only +if its argument is a bibliography table as returned by +,(markup-ref "make-bib-table") or ,(markup-ref "default-bib-table"). Otherwise +,(code "bib-table?") returns ,(code "#f").]) + + (doc-markup 'bib-table? + '((obj [The value to be tested])) + :see-also '(make-bib-table default-bib-table bibliography the-bibliography) + :force-engines *api-engines* + :common-args '() + :source "../src/bigloo/bib.bgl") + + (p [The function ,(code "default-bib-table") returns a global, pre-existing +bibliography-table:]) + (doc-markup 'default-bib-table + '() + :see-also '(bib-table? make-bib-table bibliography the-bibliography) + :force-engines *api-engines* + :common-args '() + :source "../src/bigloo/bib.bgl") + + (p [The function ,(code "make-bib-table") constructs a new +bibliography-table:]) + (doc-markup 'make-bib-table + '((ident [The name of the bibliography table.])) + :see-also '(bib-table? default-bib-table bibliography the-bibliography) + :force-engines *api-engines* + :common-args '() + :source "../src/bigloo/bib.bgl")) + +;*---------------------------------------------------------------------*/ +;* bibliography ... @label bibliography@ */ +;*---------------------------------------------------------------------*/ +(section :title "Bibliography" + +(p [The function ,(code "bibliography") loads bibliography ,(param 'entries) +into the Skribe memory. An ,(emph "entry") is either a list +representing one entry (such as an article or book reference) or a +string which denotes a file name that contains several +entries. All the entries loaded in memory are available for the function +,(ref :ident "ref" :node "references"). A bibliography database must be loaded +,(emph "before") any reference is introduced. It is advised to place +the ,(code "bibliography") Skribe function call before the call to the +,(markup-ref "document") function call.]) + +(doc-markup 'bibliography + `((:command ,[An external command to be applied when loading + the bibliography entries. The sequence ,(code "~a") is replaced + with the name of the file when the command is invoked.]) + (:bib-table ,[The ,(ref :mark "make-bib-table" :text "table") + where entry is searched.]) + (#!rest entry... ,[If ,(param 'entry) is a string, it denotes + a file containing the entry (see ,(ref :mark "skribe-bib-path" + :text "bibliograph path")). Otherwise, it is a list described + by the ,(ref :subsection "Bibliography syntax" :text "syntax") + below.])) + :see-also '(bib-table? make-bib-table default-bib-table the-bibliography) + :force-engines *api-engines* + :common-args '()) + +(p [The ,(param :command) option can be used to import foreign bibliography. +The following example, shows how to directly use a Bibtex bibliography +using the ,(ref :section "Skribebibtex") translator.]) + +(example-produce + (example :legend "Printing a bibliography" (prgm :file "src/bib6.skb"))) + + +;; bibliography syntax +(subsection :title "Bibliography syntax" + +(p [The Skribe bibliography database uses a format very close to +the Bibtex one. It is a parenthetic version of Bibtex. Here is the +syntax of an entry:]) + +(disp :verb #t :bg *prgm-skribe-color* [ +<entry> --> ,(bold "(")<kind> <key> <field>+,(bold ")") +<kind> --> techreport | article | inproceedings | book +<key> --> <symbol> | <string> +<field> --> ,(bold "(")<symbol> <string>,(bold ")")]) + +(p [Bibtex files cannot be directly loaded in Skribe but the tool +,(ref :section "Skribebibtex" :text (tt "skribebibtex")) can be use to +automatically convert Bibtex format to Skribe bibliography format. +Here is an example of a simple Skribe database.]) + +(prgm :file "src/bib1.sbib"))) + +;*---------------------------------------------------------------------*/ +;* the-bibliography ... @label the-bibliography@ */ +;*---------------------------------------------------------------------*/ +(section :title "Printing a bibliography" + +(p [The function ,(code "the-bibliography") displays the bibliography. ]) + +(doc-markup 'the-bibliography + `((:bib-table [The bibliography + ,(ref :mark "make-bib-table" :text "table") to be displayed.]) + (:pred [A predicate filtering the bibliography entries. It takes + two parameters: the bibliography entry and the + ,(code "the-bibliography") node.]) + (:sort [A function sorting a list of entries.]) + (:count ,[The symbol ,(code "partial") or ,(code "full") + specifies the numbering to be applied. The value + ,(code "partial") tells Skribe to count only the entries + filtered in by ,(param :pred). The value ,(code "full") + tells Skribe to count all entries, event those filtered out + by ,(param :pred).])) + :see-also '(bib-table? make-bib-table default-bib-table bibliography) + :force-engines *api-engines* + :common-args '()) + +(example-produce + (example :legend "Printing a bibliography" (prgm :file "src/bib2.skb")) + (disp (include "src/bib2.skb"))) + +;; filtering bibliography +(subsection :title "Filtering bibliography entries" +(index "the-bibliography" :note "filtering") + +(p [The ,(param :pred) option is bound to a function of one argument +that filters bibliography entries. It is used to control which entries +must appears on a bibliography. The default behavior is to display +only the entries referenced to in the text. For instance, in order to +display ,(emph "all") the entries of a bibliography, is it needed to +print the bibliography with a predicate returning always ,(code "#t").]) + +(example-produce + (example :legend "Unfiltering bibliography entries" (prgm :file "src/bib3.skb")) + (disp (include "src/bib3.skb"))) + +(p [The second example, filters out the entries that are not ,(emph "book") +or that are not referenced to from the document.]) + +(example-produce + (example :legend "Unfiltering bibliography entries" (prgm :file "src/bib4.skb")) + (disp (include "src/bib4.skb"))) + +(p [The last example, illustrates how to change the rendering of a +bibliography. It uses the ,(markup-ref "processor") construction +and it defines two ,(ref :ident "writer" :text "writers") for +displaying ,(code "&bib-entry-ident") and ,(code "&bib-entry-title") +markups. These two markups are introduced by Skribe when it loads a +bibliography. All fields of bibliography entries are represented by +markups whose prefix are ,(code "&bib-entry-"). The parent of all these +markups is the bibliography entry itself. The ,(code "&bib-entry-") markups +are options of there parent.]) + +(example-produce + (example :legend "Unfiltering bibliography entries" (prgm :file "src/bib5.skb")) + (disp (include "src/bib5.skb")))) + +;; sorting bibliography +(subsection :title "Sorting bibliography entries" +(index "the-bibliography" :note "sorting") + +(p [The ,(param :sort) option of the ,(markup-ref "the-bibliography") +markup is used for sorting the bibliography entries. There are three +pre-existing functions for sorting entries:]) + +(doc-markup 'bib-sort/authors + '((l [The list of entries.])) + :force-engines *api-engines* + :source "../src/common/bib.scm" + :others '(bib-sort/idents bib-sort/dates) + :common-args '()) + +(p [The first function sorts the entries according to an alphabetic ordering +on authors. The second sorts according to an alphabetic ordering on +entries identifier. The last one sorts according to entries date.]) + +(example-produce + (example :legend "Sorting bibliography entries" + (prgm :file "src/common/bib.scm" :definition 'bib-sort/idents))))) + +;*---------------------------------------------------------------------*/ +;* skribebibtex */ +;*---------------------------------------------------------------------*/ +(section :title "Skribebibtex" +(index "skribebibtex" :note "manual page") +(index "bibtex") +(p [ +In this section we present the Skribebibtex translator that compiles Bibtex +source files into a Skribe bibliography.]) + +;; Synopsis +(subsection :title "SYNOPSIS" :number #f + (compiler-command *skribebibtex-bin* "options" "input")) + +;; Description +(subsection :title "DESCRIPTION" :number #f [ +This manual page is not meant to be exhaustive. It +documents the ,(tt "skribebibtex"), a tool that translates +,(bold "Bibtex") files into ,(it "Skribe"), bibliography format. These +files can be used by the ,(bold "skribe") compiler to produce +bibliography entries.]) + +;; Suffixes +(subsection :title "SUFFIXES" :number #f [ +The ,(ref :chapter "Skribe compiler" :text "skribe") compiler uses file +suffixes in order to select amongst its possible targets which to choose. +These suffixes are: + +,(description (item :key (it ".bib") [a ,(bold "Bibtex") source file.]))]) + +;; Options +(subsection :title "OPTIONS" :number #f +(compiler-options *skribebibtex-bin*)))) + diff --git a/skribe/doc/user/char.skb b/skribe/doc/user/char.skb new file mode 100644 index 0000000..85409f0 --- /dev/null +++ b/skribe/doc/user/char.skb @@ -0,0 +1,86 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/char.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sat Sep 6 16:07:08 2003 */ +;* Last change : Mon Feb 2 11:16:57 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Characters, strings and symbols */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Footnote ... */ +;*---------------------------------------------------------------------*/ +(section :title "Characters, Strings and Symbols" :file #t + +;*--- characters ------------------------------------------------------*/ +(subsection :title "Characters" + +(p [The function ,(code "char") introduces a ,(emph "character") in +the produced document. The purpose of this function is to introduce +escape characters or to introduce characters that cannot be typesetted +in the document (for instance because the editors does not support +them). The escapes characters are ,(code (char 91)), ,(code (char 93)) +and ,(code (char 59)).]) + +(doc-markup 'char + '((char [The character to be introduced. Specified value can be +a character, a string or an integer])) + :common-args '()) + +(example-produce + (example :legend "Some characters" (prgm :file "src/api19.skb")) + (disp (include "src/api19.skb")))) + + +;*--- Strings ---------------------------------------------------------*/ +(subsection :title "Strings" + +(p [the function ,(code "!") introduces raw strings in the target. +That is, the strings introduced by ,(code "!") are written ,(emph "as is"), +without any transformation from the engine.]) + +(doc-markup '! + '((format [The format of the command.]) + (#!rest node... "The arguments.")) + :common-args '()) + +(p [The sequences ,(code "$1"), ,(code "$2"), ... in the ,(param 'format) +are replaced with the actual values of the arguments ,(param 'node).]) + +(example-produce + (example :legend "Some characters" (prgm :file "src/api20.skb")) + (disp (include "src/api20.skb")))) + +;*--- Symbols ---------------------------------------------------------*/ +(subsection :title "Symbols" + +(p [The function ,(code "symbol") introduces special symbols in the +produced file. Note that the rendering of symbols is unportable. It depends +of the capacity of the targeted format.]) + +(doc-markup 'symbol + '((symbol [The symbol to introduce.])) + :common-args '()) + +(p [Here is the list of recognized symbols:]) + +(center + (apply table + :width *prgm-width* + (tr :class 'api-symbol-prototype (th "Symbol name") (th "Rendering")) + (map (lambda (s) + (tr :bg *prgm-skribe-color* + (td :align 'left s) + (td :align 'left (symbol s)))) + (sort (let ((t (make-hashtable))) + (for-each (lambda (e) + (for-each (lambda (s) + (hashtable-put! t (car s) (car s))) + (engine-symbol-table e))) + *api-engines*) + (hashtable->list t)) + string<?)))))) + + diff --git a/skribe/doc/user/colframe.skb b/skribe/doc/user/colframe.skb new file mode 100644 index 0000000..79b32f9 --- /dev/null +++ b/skribe/doc/user/colframe.skb @@ -0,0 +1,57 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/colframe.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Mon Apr 5 11:51:08 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe color and frame */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Frame and color */ +;*---------------------------------------------------------------------*/ +(section :title "Frame and color" :file #t + +(p [The function ,(code "frame") embeds a text inside a frame. +The function ,(code "color") may also use the same purpose when it is +specified a ,(code "bg") option. This is why both functions are included +in the same Skribe manual section.]) + +;*--- Frame -----------------------------------------------------------*/ +(subsection :title "Frame" + +(doc-markup 'frame + `((:width ,[The ,(ref :mark "width") of the frame.]) + (:margin [The margin pixel size of the frame.]) + (:border [The border pixel of the frame.]) + (#!rest node... "The items of the enumeration.")) + :see-also '(color table)) + +(example-produce + (example :legend "The frame markup" (prgm :file "src/api12.skb")) + (disp (include "src/api12.skb")))) + +;*--- color -----------------------------------------------------------*/ +(subsection :title "Color" + +(p [The ,(code "color") markup enables changing ,(emph "locally") the +text of the document. If the ,(code "bg") color is used, then, ,(code "color") +acts as a container. Otherwise, it acts as an ,(ref :section "Ornaments").]) + +(doc-markup 'color + `((:width ,[The ,(ref :mark "width") of the frame.]) + (:margin [The margin pixel size of the frame.]) + (:bg [The background color]) + (:fg [The foreground color]) + (#!rest node... "The items of the enumeration.")) + :see-also '(frame table)) +(example-produce + (example :legend "The color markup" (prgm :file "src/api13.skb")) + (disp (include "src/api13.skb"))))) + + + + + diff --git a/skribe/doc/user/document.skb b/skribe/doc/user/document.skb new file mode 100644 index 0000000..09f8cb3 --- /dev/null +++ b/skribe/doc/user/document.skb @@ -0,0 +1,80 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/document.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Tue Sep 2 11:39:07 2003 */ +;* Last change : Wed Feb 4 14:51:12 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Document and author */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* dummy-document-output ... */ +;*---------------------------------------------------------------------*/ +(define dummy-document-output + (lambda (n e) + (let* ((a (markup-option n :author)) + (t (markup-option n :title)) + (b (markup-body n)) + (ta (table (tr (map (lambda (n) + (td :valign 'top :align 'center n)) + a))))) + (skribe-eval (center (bold t)) e) + (skribe-eval (center ta) e) + (output b e)))) + +;*---------------------------------------------------------------------*/ +;* Document */ +;*---------------------------------------------------------------------*/ +(section :title "Building documents" :file #t + +;*--- document --------------------------------------------------------*/ +(subsection :title "Document" + +(p [The ,(tt "document") function defines a Skribe document.]) + +(doc-markup 'document + '((:title "The title of the document.") + (:html-title "The title of window of the HTML browser.") + (:author "The authors of the document.") + (:ending "An ending text.") + (:env "A counter environment.") + (#!rest node... "The document nodes.")) + :see-also '(author chapter toc)) + +(example-produce + (example :legend "The document markup" (prgm :file "src/api2.skb")) + (disp + (processor :combinator + (lambda (e1 e2) + (let ((e (copy-engine 'document-engine e2))) + (markup-writer 'document e + :options '(:title :author :ending) + :action dummy-document-output) + e)) + (include "src/api2.skb"))))) + +;*---------------------------------------------------------------------*/ +;* Author ... */ +;*---------------------------------------------------------------------*/ +(subsection :title "Author" + +(p [The ,(tt "author") function is used to specify the authors of a Skribe +document.]) + +(doc-markup 'author + '((:name "The name of the author.") + (:title "His title.") + (:affiliation "His affiliation.") + (:email "His email.") + (:url "His web page.") + (:address "His address.") + (:phone "His phone number.") + (:photo "His photograph.") + (:align "The author item alignment.")) + :see-also '(mailto ref)) + +(example-produce + (example :legend "The author markup" (prgm :file "src/api3.skb")) + (disp (include "src/api3.skb"))))) diff --git a/skribe/doc/user/emacs.skb b/skribe/doc/user/emacs.skb new file mode 100644 index 0000000..742fa87 --- /dev/null +++ b/skribe/doc/user/emacs.skb @@ -0,0 +1,58 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/emacs.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 13:36:44 2001 */ +;* Last change : Sun Feb 29 16:12:32 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Editing Skribe programs */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Editing Skribe programs */ +;*---------------------------------------------------------------------*/ +(chapter :title "Editing Skribe Programs" (p [ +Skribe sources can be automatically generated from +,(ref :url *texinfo-url* :text "Texinfo") by the ,(tt "skribeinfo") compiler. +They can also be typed in. For this task, it is highly recommended to +use ,(ref :url *emacs-url* :text "GNU Emacs") or +,(ref :url *xemacs-url* :text "Xemacs"). +These editors provide parentheses matching and Skribe expressions +handling.]) + +;*---------------------------------------------------------------------*/ +;* Skribe emacs mode */ +;*---------------------------------------------------------------------*/ +(section :title "Skribe Emacs mode" [ +,(index "emacs" :note "skribe mode") + +The Skribe distribution contains a minor mode dedicated to +Skribe edition. This mode provides ,(emph "fontification") and +indentation of Skribe programs. In this manual, we present +the two most important key bindings specific to this mode. + +,(itemize (item [,(color :fg "#007700" (kbd "tab")) Indents the current line.]) + (item [,(color :fg "#007700" (kbd "M-C-q")) Indents a whole Skribe +expression.])) + +,(p [In order to install the Skribe emacs mode, you need to specify that +when the emacs Lisp ,(tt "skribe-mode") function is needed +it has to be loaded from the ,(tt "skribe.el") file:]) + + +,(disp :verb #t (source :language lisp [ +(autoload 'skribe-mode "skribe.el" "Skribe mode." t)])) + +,(p [The ,(tt "skribe.el") file must in the path described by the Emacs Lisp +,(tt "load-path") variable.]) + +,(p [ +The ,(code "skribe") mode is a minor mode. It is intended to be used with +a Lisp or Scheme mode. Hence, to use the ,(code "skribe") mode you will +have to use the following Emacs commands:]) + +,(disp :vert #t (source :language lisp [ +ESC-x: scheme-mode +ESC-x: skribe-mode +]))])) diff --git a/skribe/doc/user/engine.skb b/skribe/doc/user/engine.skb new file mode 100644 index 0000000..06be3c4 --- /dev/null +++ b/skribe/doc/user/engine.skb @@ -0,0 +1,135 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/engine.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 11:19:21 2003 */ +;* Last change : Mon Nov 8 15:07:35 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The description of the Skribe engines */ +;*=====================================================================*/ +;; @indent: (put 'doc-markup 'skribe-indent 'skribe-indent-function)@ + +(cond-expand + (bigloo + (define *engine-src* "../src/bigloo/engine.scm") + (define *types-src* "../src/bigloo/types.scm")) + (stklos + (define *engine-src* "../src/stklos/engine.stk") + (define *types-src* "../src/stklos/types.stk"))) + +;*---------------------------------------------------------------------*/ +;* Engine */ +;*---------------------------------------------------------------------*/ +(chapter :title "Engines" + + (p [When Skribe produces a document in a given format, it uses a +specialize engine. For instance, when a Web page is made from a Skribe +document, the HTML engine is used. The engines provided by Skribe are +given below:]) + + (resolve (lambda (n e env) + (let* ((current-chapter (ast-chapter n)) + (body (map (lambda (x) (if (pair? x) (car x) x)) + (markup-body current-chapter))) + (sects (filter (lambda (x) (is-markup? x 'section)) + body))) + (itemize + (map (lambda (x) + (let ((title (markup-option x :title))) + (item (ref :text title :section title)))) + sects))))) + + (section :title "Functions dealing with engines" + + (subsection :title "Creating engines" + (p [The function ,(code "make-engine") creates a brand new engine.]) + + (doc-markup 'make-engine + '((ident [The name (a symbol) of the new engine.]) + (:version [The version number.]) + (:format [The output format (a string) of this engine.]) + (:filter [A string filter (a function).]) + (:delegate [A delegate engine.]) + (:symbol-table [The engine symbol table.]) + (:custom [The engine custom list.]) + (:info [Miscellaneous.])) + :common-args '() + :source *engine-src* + :idx *function-index*) + + (p [The function ,(code "copy-engine") duplicates an existing engine.]) + (doc-markup 'copy-engine + '((ident [The name (a symbol) of the new engine.]) + (e [The old engine to be duplicated.]) + (:version [The version number.]) + (:filter [A string filter (a function).]) + (:delegate [A delegate engine.]) + (:symbol-table [The engine symbol table.]) + (:custom [The engine custom list.])) + :common-args '() + :source *engine-src* + :idx *function-index*)) + + (subsection :title "Retrieving engines" + + (p [The ,(code "find-engine") function searches in the list of defined +engines. It returns an ,(code "engine") object on success and ,(code "#f") +on failure.]) + (doc-markup 'find-engine + '((id [The name (a symbol) of the engine to be searched.]) + (:version [An optional version number for the searched engine.])) + :common-args '() + :source *engine-src* + :idx *function-index*)) + + (subsection :title "Engine accessors" + (p [The predicate ,(code "engine?") returns ,(code "#t") if its +argument is an engine. Otherwise, it returns ,(code "#f"). In other words, +,(code "engine?") returns ,(code "#t") for objects created by +,(code "make-engine"), ,(code "copy-engine"), and ,(code "find-engine").]) + (doc-markup 'engine? + '((obj [The checked object.])) + :common-args '() + :source *types-src* + :idx *function-index*) + + (p [The following functions return information about engines.]) + + (doc-markup 'engine-ident + '((obj [The engine.])) + :common-args '() + :others '(engine-format engine-customs engine-filter engine-symbol-table) + :source *types-src* + :idx *function-index*)) + + (subsection :title "Engine customs" + + (p [Engine customs are locations where dynamic informations relative +to engines can be stored. Engine custom can be seen a global variables that +are specific to engines. The function ,(code "engine-custom") returns the +value of a custom or ,(code "#f") if that custom is not defined. The +function ,(code "engine-custom-set!") defines or sets a new value for +a custom.]) + + (doc-markup 'engine-custom + `((e ,[The engine (as returned by +,(ref :mark "find-engine" :text (code "find-engine"))).]) + (id [The name of the custom.])) + :common-args '() + :source *engine-src* + :idx *function-index*) + + (doc-markup 'engine-custom-set! + `((e ,[The engine (as returned by +,(ref :mark "find-engine" :text (code "find-engine"))).]) + (id [The name of the custom.]) + (val [The new value of the custom.])) + :common-args '() + :source *engine-src* + :idx *function-index*))) + + ;; existing engines + (include "htmle.skb") + (include "latexe.skb") + (include "xmle.skb")) diff --git a/skribe/doc/user/enumeration.skb b/skribe/doc/user/enumeration.skb new file mode 100644 index 0000000..01155e2 --- /dev/null +++ b/skribe/doc/user/enumeration.skb @@ -0,0 +1,33 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/enumeration.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Fri Sep 12 15:31:37 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe enumerations */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Justification */ +;*---------------------------------------------------------------------*/ +(section :title "Enumeration" :file #t + +(p [These functions implements three various style of enumerations.]) + +(doc-markup 'itemize + '((:symbol [The symbol that prefixes the items.]) + (#!rest item... "The items of the enumeration.")) + :others '(enumerate description)) + +(p [Items are introduce by the means of the ,(code "item") markup:]) + +(doc-markup 'item + '((:key [The item key.]))) + +;; FIXME: Rien n'est fait en html sur le type de bullet. Mais peut on faire? +(example-produce + (example :legend "The enumeration markups" (prgm :file "src/api11.skb")) + (disp (include "src/api11.skb")))) + diff --git a/skribe/doc/user/examples.skb b/skribe/doc/user/examples.skb new file mode 100644 index 0000000..a37ece4 --- /dev/null +++ b/skribe/doc/user/examples.skb @@ -0,0 +1,34 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/examples.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 13:35:34 2003 */ +;* Last change : Tue Feb 3 14:52:33 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The list of examples */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Examples */ +;*---------------------------------------------------------------------*/ +(chapter :title "List of examples" + +(resolve (lambda (n e env) + (let* ((d (ast-document n)) + (ex (container-env-get d 'example-env))) + (table (map (lambda (e) + (tr (td :align 'left + (markup-option e :number) + ". " + (ref :handle (handle e) + :text (markup-option e :legend)) + " (chapter " + (let ((c (ast-chapter e))) + (ref :handle (handle c) + :text (markup-option c :title))) + ")"))) + (sort ex + (lambda (e1 e2) + (< (markup-option e1 :number) + (markup-option e2 :number)))))))))) diff --git a/skribe/doc/user/figure.skb b/skribe/doc/user/figure.skb new file mode 100644 index 0000000..08fbdd5 --- /dev/null +++ b/skribe/doc/user/figure.skb @@ -0,0 +1,58 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/figure.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Fri Sep 12 15:31:48 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe figures */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Figure ... @label figure@ */ +;*---------------------------------------------------------------------*/ +(section :title "Figure" :file #t + +(doc-markup 'figure + `((:legend ,[The legend of the figure. If no ,(param :ident) is + provided to the figure, it uses the legend value as an + identifier. In consequence, it is possible to use the + ,(param :legend) value in + ,(ref :mark "ref" :text "references").]) + (:number ,[If the optional argument ,(param :number) is a number, + that number is used as the new Scribe compiler figure + counter. If it is ,(tt "#t") the compiler automatically + sets a number for that figure. If it is ,(tt "#f") the + figure is numberless.]) + (:multicolumns ,[A boolean that indicates, for back-ends + supporting multi-columns rendering (e.g., "TeX"), if the figure + spans over all the columns.]) + (#!rest body [The body of the figure.])) + + :see-also '(ref document)) + +(example-produce + (example :legend "The figure markup" (prgm :file "src/api14.skb")) + (disp (include "src/api14.skb"))) + +;*--- List of figures -------------------------------------------------*/ +(subsection :title "List of figures" +(index "figure" :note "list of figures") + +(p [Skribe has no builtin facility for displaying the list of figures. +Instead, it provides a general machinery for displaying any kind of lists +contained in the document. This is described in the section ,(ref +:section "Resolve") and ,(ref :section "Introspection") but for the +sake of the coherence, this section also contains an example that +shows how to display the list of figures of a document.]) + +(example-produce + (example :legend "The figure markup" (prgm :file "src/api15.skb")) + (disp (include "src/api15.skb"))))) + + + + + + diff --git a/skribe/doc/user/font.skb b/skribe/doc/user/font.skb new file mode 100644 index 0000000..df0bfed --- /dev/null +++ b/skribe/doc/user/font.skb @@ -0,0 +1,30 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/font.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Fri Sep 12 15:31:25 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe font */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Font */ +;*---------------------------------------------------------------------*/ +(section :title "Font" :file #t + +(p [The function ,(code "font") enables font selection.]) + +(doc-markup 'font + '((:size [The size of the font. The size may be ,(emph "relative") +(with respect to the current font size) or absolute. A relative +font is either specified with a floating point value or a negative +integer value. A positive integer value specifies an absolute font size.]) + (:face [The name of the font to be used.]) + (#!rest node... "The nodes of the font."))) + +(example-produce + (example :legend "The font markup" (prgm :file "src/api9.skb")) + (disp (include "src/api9.skb")))) + diff --git a/skribe/doc/user/footnote.skb b/skribe/doc/user/footnote.skb new file mode 100644 index 0000000..96101f3 --- /dev/null +++ b/skribe/doc/user/footnote.skb @@ -0,0 +1,28 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/footnote.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sat Sep 6 15:43:24 2003 */ +;* Last change : Fri Sep 12 15:32:13 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe footnotes. */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Footnote ... */ +;*---------------------------------------------------------------------*/ +(section :title "Footnote" :file #t + +(p [By default, footnotes appear at the bottom of the page that contains +the reference to the footnote.]) + +(doc-markup 'footnote + `((:number [The number of the footnote.]) + (#!rest text... [The text of the footnote.])) + :see-also '(document chapter section)) + +(example-produce + (example :legend "A footnote" (prgm :file "src/api18.skb")) + (disp (include "src/api18.skb")))) + diff --git a/skribe/doc/user/htmle.skb b/skribe/doc/user/htmle.skb new file mode 100644 index 0000000..b5d0b0e --- /dev/null +++ b/skribe/doc/user/htmle.skb @@ -0,0 +1,111 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/htmle.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 11:20:49 2003 */ +;* Last change : Wed Oct 27 12:05:53 2004 (eg) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The documentation of the html engine */ +;*=====================================================================*/ +;; @indent: (put 'doc-engine 'skribe-indent 'skribe-indent-function)@ + +;*---------------------------------------------------------------------*/ +;* Document */ +;*---------------------------------------------------------------------*/ +(section :title "Html engine" :file #t + (mark "html-engine") + (index "Html" :note "Engine") + (p [The html engine...]) + + (subsection :title "The HTML customization" + + (doc-engine 'html + `((favicon ,[The name of an image file of the URL image. The +,(code "favicon") custom can be either bound to a string +which is the name of the image, or to a procedure of +two arguments, a node and an engine that returns the file name +of the icon. This can be used to use different icons per +chapter or section.]) + (charset [The character set used for the document.]) + (javascript [Enable/disable Javascript support.]) + (head [A string included in the HTML header.]) + (css ,[The URL or a list of URLs of +,(ref :url "http://www.w3.org/TR/REC-CSS2/" :text "CSS") +used by the document.]) + (inline-css ,[The file or a list of files inlined +inside the header's style section. The custom ,(code "inline-css") should be +used in replacement of the ,(code "css") custom in order to produce +stand alone HTML documents.]) + (js ,[A URL or a list of URLs of JavaScript programs used by +the document.]) + (emit-sui [Emit a SUI file for this document.]) + (background "The background color of the document.") + (foreground "The foreground color of the document.") + ;; the margins + (margin-padding "Margins padding.") + (left-margin "A procedure of two arguments producing the left margin of the document.") + (chapter-left-margin "A procedure of two arguments producing the left margin of the document.") + (section-left-margin "A procedure of two arguments producing the left margin of the document.") + (left-margin-font "The font of the left margin.") + (left-margin-size ,[The ,(ref :mark "width" :text "width") of the left margin.]) + (left-margin-background "The background color of the left margin.") + (left-margin-foreground "The foreground color of the left margin.") + (right-margin "A procedure of two arguments producing the right margin of the document.") + (chapter-right-margin "A procedure of two arguments producing the right margin of the document.") + (section-right-margin "A procedure of two arguments producing the right margin of the document.") + (right-margin-font "The font of the right margin.") + (right-margin-size ,[The ,(ref :mark "width" :text "width") of the right margin.]) + (right-margin-background "The background color of the right margin.") + (right-margin-foreground "The foreground color of the right margin.") + ;; author configuration + (author-font "The author font.") + ;; title configuration + (title-font "The title font.") + (title-background "The title background color.") + (title-foreground "The title foreground color.") + (file-title-separator "A text to be inserted in between the document title and the chapter or section title when the chapter or section is rendered in a separate file.") + ;; index configuration + (index-header-font-size "The index header font size.") + ;; chapter configuration + (chapter-number->string "A procedure of one argument for rendering chapter numbers.") + (chapter-file ,[A boolean specifying if chapters are rendered in speparate html file (see ,(markup-ref "chapter") markup).]) + ;; section configuration + (section-title-start "The HTML sequence for starting section title.") + (section-title-stop "The HTML sequence for stopping section title.") + (section-title-background "The background color of section title.") + (section-title-foreground "The foreground color of section title.") + (section-title-number-separator "The section title number separator.") + (section-number->string "A procedure of one argument for rendering section numbers.") + (section-file ,[A boolean specifying if sections are rendered in speparate html file (see ,(markup-ref "section") markup).]) + ;; subsection configuration + (subsection-title-start "The HTML sequence for starting subsection title.") + (subsection-title-stop "The HTML sequence for stopping subsection title.") + (subsection-title-background "The background color of subsection title.") + (subsection-title-foreground "The foreground color of subsection title.") + (subsection-title-number-separator "The subsection title number separator.") + (subsection-number->string "A procedure of one argument for rendering subsection numbers.") + (subsection-file ,[A boolean specifying if subsections are rendered in speparate html file (see ,(markup-ref "subsection") markup).]) + ;; subsubsection configuration + (subsubsection-title-start "The HTML sequence for starting subsubsection title.") + (subsubsection-title-stop "The HTML sequence for stopping subsubsection title.") + (subsubsection-title-background "The background color of subsubsection title.") + (subsubsection-title-foreground "The foreground color of subsubsection title.") + (subsubsection-title-number-separator "The subsubsection title number separator.") + (subsubsection-number->string "A procedure of one argument for rendering subsubsection numbers.") + (subsubsection-file ,[A boolean specifying if subsubsections are rendered in speparate html file (see ,(markup-ref "subsubsection") markup).]) + ;; source fontification + (source-color ,[A boolean enabling/disabling color of source code (see ,(markup-ref "source") markup).]) + (source-comment-color "The source comment color.") + (source-error-color "The source error color.") + (source-define-color "The source define color.") + (source-module-color "The source module color.") + (source-markup-color "The source markup color.") + (source-thread-color "The source thread color.") + (source-string-color "The source string color.") + (source-bracket-color "The source bracket color.") + (source-type-color "The source type color.") + (image-format "The image formats for this engine.")) + :source "skr/html.skr"))) + + diff --git a/skribe/doc/user/image.skb b/skribe/doc/user/image.skb new file mode 100644 index 0000000..d08ad18 --- /dev/null +++ b/skribe/doc/user/image.skb @@ -0,0 +1,79 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/image.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Sat Jan 17 18:08:15 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe images */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Image ... @label image@ */ +;*---------------------------------------------------------------------*/ +(section :title "Image" :file #t + +(p [Images are defined by the means of the ,(code "image") function]) + +(doc-markup 'image + `((:file ,[The file where the image is stored on the disk + (see ,(ref :mark "skribe-image-path" + :text "image path")). + The image is converted + (see ,(markup-ref "convert-image")) into a format + supported by the engine. This option is exclusive + with the ,(param :url) option.]) + (:url [The URL of the file. This option is exclusive with the + ,(param :file) option.]) + (:width [The width of the image. It may be an integer for a pixel + size or a floating point number for a percentage.]) + (:height [The height of the image. It may be an integer for a + pixel size or a floating point number for a + percentage.]) + (:zoom [A zoom factor.]) + (#!rest comment [A text describing the image.])) + :see-also '(skribe-image-path convert-image)) + +(example-produce + (example :legend "The image markup" (prgm :file "src/api16.skb")) + (disp (include "src/api16.skb"))) + +;*--- Image format ----------------------------------------------------*/ +(subsection :title "Image formats" + (index "image" :note "conversion") + + (p [ +Images are unfortunately ,(emph "unportable"). The various Skribe output +formats support different image formats. For instance, HTML supports +,(code "gif") and ,(code "jpeg") while the LaTeX back-end only supports +,(code "ps"). Skribe tries, only when needed, to automatically +,(emph "convert") images to a format supported by the target +to be produced. For this, it uses external tools. The default Skribe +translation scheme is:]) +(itemize (item [Do not translate an image that needs no conversion.]) + (item [Uses the ,(code "fig2dev") external tool to translate + ,(code "Xfig") images.]) + (item [Uses the ,(code "convert") external tools to translate all + other formats.])) + + (p [,(ref :chapter "Engines" :text "Engines") support different image +formats. Each engine may specify a converter to be applied to an image. +The engine custom ,(code "image-format") specifies the list of supported +image formats. This list is composed of a suffix such as ,(code "jpeg") or +,(code "gif").]) + + (p [The function ,(code "convert-image") tries to convert an +image according to a list of formats. All the specified formats are +successively tried. On the first success, the function ,(code "convert-image") +returns the name of the new converted image. On failure, it returns +,(code "#f").]) + (doc-markup 'convert-image + `((file [The image file to be converted. The file is +searched in the ,(ref :mark "skribe-image-path" :text "image path").]) + (formats [A list of formats into which images are converted to.])) + :common-args '() + :source "../src/bigloo/lib.bgl" + :see-also '(skribe-image-path) + :idx *function-index*))) + diff --git a/skribe/doc/user/index.skb b/skribe/doc/user/index.skb new file mode 100644 index 0000000..dd5e8fa --- /dev/null +++ b/skribe/doc/user/index.skb @@ -0,0 +1,118 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/index.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sun Dec 2 10:02:56 2001 */ +;* Last change : Mon Feb 23 18:59:00 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe indexes */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Index */ +;*---------------------------------------------------------------------*/ +(chapter :title "Indexes" (p [ +Skribe support indexes. One may accumulate all entries inside one +unique index or dispatch them amongst user declared indexes. Indexes +may be ,(emph "monolithic") or ,(emph "split"). They only differ in +the way they are rendered by the back-ends. For a split index a sectioning +based on the specific (e.g., "the first one") character of +index entries is deployed.]) + +;*---------------------------------------------------------------------*/ +;* make-index ... @label make-index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Making indexes" + +(p [The function ,(code "make-index") declares a new index.]) + +(doc-markup 'make-index + '((ident "A string, the name the index (currently unused).")) + :common-args '() + :see-also '(default-index index the-index ref mark)) + +(p [For instance, the following Skribe expression declares an index named +,(tt "*index1*"):]) + +(example-produce + (example :legend "Creation of a new index" (prgm :file "src/index1.skb"))) + +(include "src/index1.skb") + +(p [This example produces no output but enables entries to be added to that +index. In general it is convenient to declare indexes ,(emph "before") +the call to the ,(markup-ref "document") function.]) + +(p [The function ,(code "default-index") returns the default index +that pre-exists to all execution.]) + +(doc-markup 'default-index + '() + :common-args '() + :source "src/common/index.scm")) + +;*---------------------------------------------------------------------*/ +;* Index ... @label index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Adding entries to an index" + +(p [The function ,(code "index") adds a new entry into one existing +index and sets a mark in the text where the index will point to. It is +an error to add an entry into an index that is not already declared.]) + +(doc-markup 'index + '((:index [The name of the index whose index entry belongs to. + A value of ,(tt "#f") means that the + ,(markup-ref :mark "default-index") owns this entry.]) + (:note [An optional note added to the index entry. This note + will be displayed in the index printing.]) + (:shape [An optional shape to be used for rendering the entry.]) + (:url [An optional URL that is referenced in the index table + instead of the location of the ,(code "index").]) + (#!rest name [The name of the entry. This must be a string.])) + :see-also '(make-index default-index the-index)) + +(p [The following expressions add entries to the index ,(code "*index1*"):]) + +(example-produce + (example :legend "Adding entries to an index" (prgm :file "src/index2.skb"))) + +(include "src/index2.skb") + +(p [There is no output associated with these expressions.])) + +;*---------------------------------------------------------------------*/ +;* Print-index ... @label the-index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Printing indexes" + + (p [The function ,(code "the-index") displays indexes in the produced +document.]) + + (doc-markup 'the-index + '((:split [If ,(tt "#t"), character based sectioning is deployed. + Otherwise all the index entries are displayed one next to + the other.]) + (:char-offset [The character number to use when split is + required. This option may be useful when printing index whose + items share a common prefix. The ,(param :char-offset) + argument can be used to skip this prefix.]) + (:header-limit [The number of entries from which an index header + is introduced.]) + (:column [The number of columns of the index.]) + (#!rest index... [The indexes to be displayed. If index + is provided, the global index ,(markup-ref "default-index") + is printed.]))) + + (p [If the engine custom +,(ref :chapter "Engines" :text (code "index-page-ref")) is true when a +index is rendered then, page reference framework is used instead of +a direct reference framework.]) + +(example-produce + (example :legend "Printing indexes" (prgm :file "src/index3.skb")) + (disp (include "src/index3.skb"))) + +(p [See the Skribe ,(ref :mark "global index" :text "global index") for +a real life index example.]))) diff --git a/skribe/doc/user/justify.skb b/skribe/doc/user/justify.skb new file mode 100644 index 0000000..94db7d5 --- /dev/null +++ b/skribe/doc/user/justify.skb @@ -0,0 +1,30 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/justify.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 11:53:32 2003 */ +;* Last change : Fri Sep 12 15:31:31 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe justification */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Justification */ +;*---------------------------------------------------------------------*/ +(section :title "Justification" :file #t + +(p [These functions control the text layout. The default layout is text +justification.]) + +(doc-markup 'flush + '((:side [The possible values for the side justification + are ,(tt "left"), ,(tt "center") or ,(tt "right").]) + (#!rest node... "The nodes of the font.")) + :others '(center pre) + :see-also '(linebreak table prog)) + +(example-produce + (example :legend "The justification markups" (prgm :file "src/api10.skb")) + (disp (include "src/api10.skb")))) + diff --git a/skribe/doc/user/latexe.skb b/skribe/doc/user/latexe.skb new file mode 100644 index 0000000..f53737b --- /dev/null +++ b/skribe/doc/user/latexe.skb @@ -0,0 +1,60 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/latexe.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 11:20:49 2003 */ +;* Last change : Tue Apr 6 06:28:59 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The documentation of the html engine */ +;*=====================================================================*/ +;; @indent: (put 'doc-engine 'skribe-indent 'skribe-indent-function)@ + +;*---------------------------------------------------------------------*/ +;* Document */ +;*---------------------------------------------------------------------*/ +(section :title "LaTeX engine" :file #t + (mark "latex-engine") + (index "LaTeX" :note "Engine") + (p [The LaTeX engine...]) + + + (subsection :title "The LaTeX customization" + + (doc-engine 'latex + `((documentclass ,[A string declaring The LaTeX document class.]) + (usepackage ,[The boolean ,(code "#f") if no package is used or a string declaring The LaTeX packages.]) + (predocument ,[The boolean ,(code "#f") or a string to be written before the \\begin{document} statement.]) + (postdocument ,[The boolean ,(code "#f") or a string to be written after the \\begin{document} statement.]) + (maketitle ,[The boolean ,(code "#f") or a string to be written after the \\begin{document} statement for emitting the document title.]) + (color [Enable/disable colors.]) + (%font-size #f) + ;; source fontification + (source-color ,[A boolean enabling/disabling color of source code (see ,(markup-ref "source") markup).]) + (source-comment-color "The source comment color.") + (source-error-color "The source error color.") + (source-define-color "The source define color.") + (source-module-color "The source module color.") + (source-markup-color "The source markup color.") + (source-thread-color "The source thread color.") + (source-string-color "The source string color.") + (source-bracket-color "The source bracket color.") + (source-type-color "The source type color.") + (color-usepackage "The LaTeX package for coloring.") + (hyperref "Enables/disables hypererrf.") + (hyperref-usepackage "The LaTeX package for hyperref.") + (image-format "The image formats for this engine.") + (index-page-ref "Indexes use page references.")) + :source "skr/latex.skr")) + + (subsection :title "LaTeX documentclass" + + (p [The default setting of the Skribe LaTeX engine is to produce +a document using the ,(code "article") document class. In order to +generate a document using ,(code "chapter") this must be changed because +this LaTeX style does not define any ,(code "\\chapter") function. For +instance, one may use the LaTeX ,(code "book") document class. Changing +this setting can be done with expressions such as: +,(prgm :language skribe [ +(let ((le (find-engine 'latex))) + (engine-custom-set! le 'documentclass "\\\\documentclass{book}"))])]))) diff --git a/skribe/doc/user/lib.skb b/skribe/doc/user/lib.skb new file mode 100644 index 0000000..499ca61 --- /dev/null +++ b/skribe/doc/user/lib.skb @@ -0,0 +1,156 @@ +;;;; +;;;; Standard Library +;;;; +;;;; +;;;; Author: Erick Gallesio [eg@essi.fr] +;;;; Creation date: 21-Nov-2003 07:20 (eg) +;;;; Last file update: 21-Nov-2003 10:17 (eg) + + +(chapter :title "Standard Library" + + (p [This section describes the Skribe standard library]) + +;;; +(section :title "File functions" + + (p [The function ,(code "include") is particularily useful to spread a +long document amongst several files.]) + + (doc-markup 'include + '((file [The file containing the nodes to be included. +These nodes are included in the document in place of the ,(code "include") +call.])) + :common-args '() + :see-also '(skribe-load skribe-path skribe-path-set!) + :idx *function-index*) + + (p [The given file is searched in the current +,(ref :mark "skribe-path" :text "Skribe path")]) + + (p [The function ,(code "skribe-load") is generally used to load in the +Skribe memory, a package or an extension. In general the prelude of a +Skribe document (the expressions placed before the ,(markup-ref "document") +call) contains several ,(code "skribe-load"). The file is search +in the ,(ref :mark "skribe-path" :text "Skribe path").]) + + (doc-markup 'skribe-load + `((file [The file containing the expressions to be loaded.]) + (:engine [The engine used to evaluate the expressions.]) + (:path ,[The optional path where to find the file. The default + path is ,(markup-ref "skribe-path").]) + (#!rest opt... [Additional user options.])) + :source "../src/bigloo/eval.scm" + :common-args '() + :see-also '(skribe-load-options skribe-path skribe-path-set!) + :idx *function-index*) + + (p [Returns the user of options of the last call to +,(markup-ref "skribe-load")]) + (doc-markup 'skribe-load-options + '() + :source "../src/bigloo/eval.scm" + :common-args '() + :see-also '(skribe-load) + :idx *function-index*) + + (p [Skribe provides functions for dealing with paths. These functions +are related to the path that can be specified on the command line, +when the Skribe compiler is invoked (see Chapter +,(ref :chapter "Skribe compiler").)]) + + (doc-markup 'skribe-path + '() + :source "../src/bigloo/eval.scm" + :common-args '() + :others '(skribe-image-path skribe-bib-path skribe-source-path) + :see-also '(include skribe-load image source bibliography skribe-path-set! skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!) + :idx *function-index*) + + (p [The function ,(code "skribe-path-set!") sets a new path.]) + (doc-markup 'skribe-path-set! + '((path [A list of strings which is the new Skribe search path.])) + :source "../src/bigloo/eval.scm" + :common-args '() + :others '(skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!) + :see-also '(skribe-path skribe-image-path skribe-bib-path skribe-source-path) + :idx *function-index*)) + +;;; Misc +(section :title "Misc. Functions" + + (p [The function ,(code "skribe-release") returns the Skribe version +as a string]) + (doc-markup 'skribe-release + '() + :common-args '() + :source #f + :def '(define (skribe-release) ...) + :idx *function-index*) + + (p [For instance, the following piece of code:]) + (prgm :language skribe + "[This manual documents the ,(bold (skribe-release)) Skribe release]") + (p [produces the following output]) + (disp [This manual documents the ,(bold (skribe-release)) Skribe release])) + + (p [The function ,(code "skribe-configure") accesses the whole +Skribe configuration. It can be used to ,(emph "get") or ,(emph "check") +the configuration.]) + + (doc-markup 'skribe-configure + '((opt... [Optional arguments.])) + :common-args '() + :source #f + :def '(define (skribe-configure . opt...) ...) + :idx *function-index*) + + (p [The function ,(code "skribe-configure") can be used in three distinct +ways depending on the number of provided arguments:]) + + (enumerate + (item [If no argument is provided, ,(code "skribe-configure") returns +a fresh list of Skribe configuration.]) + (item [If one keyword argument is provided, ,(code "skribe-configure") +returns the value associated with this keyword in the configuration list. +If this value does not exist, it returns the symbol ,(code "void").]) + (item [(code "skribe-configure") is invoked with a list composed +of ,(emph "keyword") ,(emph "value"). The actual configuration is checked +against the provided values. Values are compared with ,(code "equal") except +if the value to check has to be compared with a procedure. In that particular +case the value of the check is the value produces by ,(emph "applying") the +function to the actual value. The result of ,(code "skribe-configure") is a +boolean.])) + + (p [Here are some examples.]) + (prgm :language skribe [ +;; fetch the whole configuration list +(skribe-configure) + +;; fetch the release number +(skribe-configure :release) + +;; test if the release number is 1.0b +(skribe-configure :release "1.0b") + +;; test if the release number is greater or equal than "1.0b" +(skribe-configure :release (lambda (v) (string>=? v "1.0b"))) + +;; test if the release number is greater or equal than "1.0b" +;; and the implementation is bigloo +(skribe-configure :release (lambda (v) (string>=? v "1.0b")) :scheme "bigloo")]) + + (p [The function ,(code "skribe-enforce-configure") checks for the Skribe +configuration. In case of mismatch, it raises an error. The syntax of the +arguments if the same as that of ,(code "skribe-configure") when invoked +with several arguments.]) + + (doc-markup 'skribe-enforce-configure + '((opt... [Optional arguments.])) + :common-args '() + :source #f + :def '(define (skribe-enforce-configure . opt...) ...) + :idx *function-index*)) + + + diff --git a/skribe/doc/user/line.skb b/skribe/doc/user/line.skb new file mode 100644 index 0000000..85f84dd --- /dev/null +++ b/skribe/doc/user/line.skb @@ -0,0 +1,39 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/line.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 4 10:08:08 2003 */ +;* Last change : Thu Sep 4 13:29:49 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Line breaks */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Line breaks */ +;*---------------------------------------------------------------------*/ +(section :title "Line breaks" :file #t + +(p [Line breaks and horizontal rules enable text cutting.]) + +;*--- linebreak -------------------------------------------------------*/ +(subsection :title "Linebreak" + +(p [The Skribe function ,(code "linebreak") is unportable. Even if +most engines handle it for their code production, using ,(code "linebreak") +generally produces expected result. For instance, using ,(code "linebreak") +with an engine producing LaTeX code is bound to fail. In consequence, +as much as possible, one should prefer other ways for splitting a text]) + +(doc-markup 'linebreak + '((#!rest num "The number of line breaks.")) + :see-also '(paragraph table))) + +;*--- Horizontal rule -------------------------------------------------*/ +(subsection :title "Horizontal rule" + +(doc-markup 'hrule + `((:width ,[The ,(ref :mark "width") of the horizontal rule.]) + (:height [The thickness of the rule. A positive integer + value stands for a number of pixels.]))))) + diff --git a/skribe/doc/user/links.skb b/skribe/doc/user/links.skb new file mode 100644 index 0000000..b454f28 --- /dev/null +++ b/skribe/doc/user/links.skb @@ -0,0 +1,152 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/links.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Thu Sep 11 06:10:44 2003 */ +;* Last change : Thu Feb 26 20:56:48 2004 (eg) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe links */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Links and references */ +;*---------------------------------------------------------------------*/ +(chapter :title "References and Hyperlinks" [ +Skribe supports traditional ,(emph "references") (that is, references to some +part of documents) and ,(emph "hyperlinks") (that is visual marks enriching +texts that enable interactive browsing). Hyperlinks may point to + +,(itemize (item [Inner parts of a document, such as a section or a figure.]) + (item [Other documents, such as Web documents.]) + (item [Other Skribe documents.]) + (item [Specific part of other Skribe documents, such as a chapter + of another Skribe document.])) + +,(paragraph [In order to use hyperlinks, Skribe documents must:]) + +,(itemize (item [,(emph "Refer to") marks. This is the role of the ,(tt "ref") + Skribe function.]) + (item [,(emph "Set") marks. This is the role of the ,(tt "mark") + function. However, most Skribe functions that introduce text + structures (e.g., chapters, sections, figures, ...) + automatically introduce marks as well. So, it is + useless to ,(emph "explicitly") introduce a mark at the + beginning of these constructions in order to refer to them + with an hyperlink.]))] + +;*---------------------------------------------------------------------*/ +;* mark ... @label mark@ */ +;*---------------------------------------------------------------------*/ +(section :title "Mark" + +(p [The ,(code "mark") function sets a mark in the produced document +that can be referenced to with the ,(markup-ref "ref") +function. Unless a ,(param :text) option is specified, no visible text +in associated with the mark in the generated document.]) + +(doc-markup 'mark + '((:text "A text associated with the markup.") + (#!rest mark [A string that will be used in a + ,(markup-ref "ref") function call to point to that mark.]))) + +(p [The Skribe functions + ,(map (lambda (x y) + (list (markup-ref x) y)) + '("chapter" "section" "subsection" "subsubsection") + '(", " ", " ", " " ")) +Skribe automatically set a mark whose value is the title of the section. +The Skribe function ,(markup-ref "figure") +automatically sets a mark whose value is the legend of the figure.])) + +;*---------------------------------------------------------------------*/ +;* ref ... @label ref@ */ +;*---------------------------------------------------------------------*/ +(section :title "Reference" + +(p [Skribe proposes only one single function for all the references. +This same ,(code "ref") function is used for introducing references to +section, to bibliographic entries, to source code line number, etc.]) + +(doc-markup 'ref + `((:text [The text that is the visual part the links for + engines that support hyperlinks.]) + (:url [An URL, that is, a location of another file, + such as an HTML file.]) + (:mark [A string that is the name of a mark. That mark has + been introduced by a ,(markup-ref "mark") markup.]) + (:handle [A Skribe node ,(markup-ref "handle").]) + (:ident [A reference to a node who has been specified + an ,(param :ident) value.]) + (:figure [The name of a ,(markup-ref "figure").]) + (:chapter [The name of a ,(markup-ref "chapter").]) + (:section [The name of a ,(markup-ref "section").]) + (:subsection [The name of a ,(markup-ref "subsection").]) + (:subsubsection [The name of a ,(markup-ref "subsubsection").]) + (:page [A boolean enabling/disabling page reference.]) + (:bib ,[A name or a list of names of + ,(ref :chapter "Bibliographies" :text "bibliographic") entry.]) + (:bib-table ,[The + ,(ref :chapter "Bibliographies" :text "bibliography") where + searching the entry.]) + (:line [A reference to a ,(ref :mark "prog" :text "program") + line number.]) + (:skribe [The name of a + ,(ref :section "Skribe Url Index" :text "Skribe Url Index") + ,(var "file") that contains the reference. The + reference can be a ,(tt "chapter"), ,(tt "section"), + ,(tt "subsection"), ,(tt "subsubsection") or even + a ,(tt "mark") located in the Skribe document + described by the ,(var "file") ,(sc "sui").])) + :force-args '(:url :bib :line :skribe) + :see-also '(index)) + + +(example-produce + (example :legend "Some references" (prgm :file "src/links1.skb")) + (disp (include "src/links1.skb")))) + +;*---------------------------------------------------------------------*/ +;* mailto ... @label mailto@ */ +;*---------------------------------------------------------------------*/ +(section :title "Electronic mails" + +(p [The ,(code "mailto") function is mainly useful for electronic +output formats that are able to run a mailing agent. The function ,(tt "mailto") +introduces mail annotation in a Skribe document.]) + +(doc-markup 'mailto + '((:text [The text that is the visual part the links.]) + (#!rest email [The electronic address.]))) + +(example-produce + (example :legend "Mail address reference" (prgm :file "src/links2.skb")) + (disp (include "src/links2.skb")))) + +;*---------------------------------------------------------------------*/ +;* Skribe Url Index ... */ +;*---------------------------------------------------------------------*/ +(section :title "Skribe Url Index" [ +,(p [A ,(emph "Skribe Url Index") (henceforth ,(sc "Sui")) describes the +marks that are available in a Skribe document. It is to be used to +make Skribe marks available to other Skribe documents. The syntax +of a ,(sc "Sui") file is:]) + +,(disp :verb #t :bg *prgm-skribe-color* [ +<sui> --> (skribe-url-index <title> + :file <file-name> + (marks <sui-ref>*) + (chapters <sui-ref>*) + (section <sui-ref>*) + (subsection <sui-ref>*) + (subsubsection <sui-ref>*)) +<sui-ref> --> (<string> :file <file-name> :mark <string>)]) + +,(p [,(sc "Sui") files can be automatically produced by the Skribe compiler. +For instance, in order to produce the ,(sc "Sui") file of this user +manual, one should write:]) + +,(disp :verb #t [ +$ skribe user.skb -o user.sui])])) + +;; LocalWords: Hyperlinks HTML URL url diff --git a/skribe/doc/user/markup.skb b/skribe/doc/user/markup.skb new file mode 100644 index 0000000..272bfbe --- /dev/null +++ b/skribe/doc/user/markup.skb @@ -0,0 +1,83 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/markup.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Tue Sep 2 06:09:18 2003 */ +;* Last change : Wed Feb 4 06:11:45 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe standard markups */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* API */ +;*---------------------------------------------------------------------*/ +(chapter :title "Standard Markups" [ + +This chapter describes the forms composing Skribe texts. In XML/HTML +these forms are called ,(emph "markups"). In LaTeX they are called +,(emph "macros"). In Skribe these forms are called ,(emph +"functions"). In this manual, we will say that we ,(emph "call a +function") when a function is used in a form. The values used in a +function call are named the ,(emph "actual parameters") of the +function or ,(emph "parameters") in short. When calling a function +with parameters we say that we are ,(emph "passing") arguments to the +function. + +,(p [ In this documentation function names are typesetted in bold +face. We call a ,(emph "keyword argument"), an argument whose +identifier starts with the ,(tt ":") character. Arguments whose +identifier does not start with this character are called ,(emph "plain +arguments") or ,(emph "arguments") in short. An ,(emph "optional +argument") is represented by a list, starting with the character ,(q +(char 91)) and ending with the character ,(q (char 93)), whose first +element is a keyword argument and the optional second (,(code "#f") +when not specified) element is the default value used if the optional +argument value is not provided on a function call. Arguments that are +not optional are said ,(emph "mandatory"). If a plain argument is +preceeded with a ,(tt ".") character, this argument may be used to +accumulate several values. There are two ways to pass actual arguments +to a function.]) + +,(itemize (item [for keyword arguments: the value of the parameter +must be preceeded by the name of the argument.]) + (item [for plain arguments: a value is provided.])) + +Example: Let us consider the function ,(tt "section") defined as follows: +,(prgm "(section :title [:number #t] [:toc #t] . body)") + +,(p [ +The argument ,(param :title) is a mandatory keyword argument. +The keyword arguments ,(param :number) and ,(param :toc) are +optional. The plain argument ,(param 'body) is preceeded with a +,(tt ".") character so it may receive several values. All the following +calls are legal ,(tt "section") calls:]) + +,(prgm (source :file "src/api1.skb"))] + +;*---------------------------------------------------------------------*/ +;* Markup index ... */ +;*---------------------------------------------------------------------*/ +(section :title "Markup index" :ident "markups-index" :file #f :number #f :toc #t + (the-index :class 'markup-index + :column (if (engine-format? "latex") 2 4) + :split #f + *markup-index*)) + +;*---------------------------------------------------------------------*/ +;* Markups */ +;*---------------------------------------------------------------------*/ +(include "document.skb") +(include "sectioning.skb") +(include "toc.skb") +(include "ornament.skb") +(include "line.skb") +(include "font.skb") +(include "justify.skb") +(include "enumeration.skb") +(include "colframe.skb") +(include "figure.skb") +(include "image.skb") +(include "table.skb") +(include "footnote.skb") +(include "char.skb")) diff --git a/skribe/doc/user/ornament.skb b/skribe/doc/user/ornament.skb new file mode 100644 index 0000000..e65b9d1 --- /dev/null +++ b/skribe/doc/user/ornament.skb @@ -0,0 +1,25 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/ornament.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 14:00:52 2003 */ +;* Last change : Fri Sep 12 15:31:19 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The skribe ornaments */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Ornaments */ +;*---------------------------------------------------------------------*/ +(section :title "Ornaments" :file #t + +(p [Skribe supports the standard text ornaments.]) + +(doc-markup 'bold + '((#!rest node... "The nodes of the ornament.")) + :others '(code emph it kbd roman sc sf sub sup tt underline var)) + +(example-produce + (example :legend "The ornament markups" (prgm :file "src/api8.skb")) + (disp (include "src/api8.skb")))) diff --git a/skribe/doc/user/package.skb b/skribe/doc/user/package.skb new file mode 100644 index 0000000..ad989d0 --- /dev/null +++ b/skribe/doc/user/package.skb @@ -0,0 +1,139 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/package.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sat Feb 21 08:26:44 2004 */ +;* Last change : Fri Jun 3 16:51:30 2005 (serrano) */ +;* Copyright : 2004-05 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Packages */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Standard packages */ +;*---------------------------------------------------------------------*/ +(chapter :title "Standard Packages" + + (p [ +This chapter describes the standard Skribe packages. Additional +packages can be found from the +,(ref :url (skribe-url) :text "Skribe web page"). +This chapter only describes the packages that are contained in the standard +Skribe distribution.]) + + (p [ +In order to use the facilities described in the following sections, the +Skribe source file must contains expressions such as:]) + +(prgm [(skribe-load ,(it "package.skr") ...)]) + +[where ,(it (tt "package.skr")) is the described package.] + +;*---------------------------------------------------------------------*/ +;* jfp */ +;*---------------------------------------------------------------------*/ +(section :title "Articles" + + (subsection :title (tt "acmproc.skr") :ident "acmproc" + (index :index *package-index* "acmproc.skr" :note "package") + (p [ +This package enables producing LaTeX documents conforming to the +,(emph "ACM proceeding") (ACMPROC) style. It introduces the +markup ,(code "abstract"):]) + (doc-markup 'abstract + `((:class "The node class.") + (:postscript [The URL of the PostScript version of the paper.])) + :common-args '() + :idx-note "acmproc" + :idx-suffix " (acmproc)" + :force-engines *api-engines* + :source "../skr/acmproc.skr")) + + (subsection :title (tt "jfp.skr") :ident "jfp" + (index :index *package-index* "jfp.skr" :note "package") + (p [ +This package enables producing LaTeX documents conforming to the +,(emph "Journal of Functional Programming") (JFP) style. It introduces the +markup ,(code "abstract"):]) + (doc-markup 'abstract + `((:postscript [The URL of the PostScript version of the paper.])) + :common-args '() + :idx-note "jfp" + :idx-suffix " (jfp)" + :force-engines *api-engines* + :source "../skr/jfp.skr")) + + (subsection :title (tt "lncs.skr") :ident "lncs" + (index :index *package-index* "lncs.skr" :note "package") + (p [ +This package enables producing LaTeX documents conforming to the +,(emph "Lecture Notes on Computer Science") (LNCS) style. It introduces the +markup ,(code "abstract"):]) + (doc-markup 'abstract + `((:postscript [The URL of the PostScript version of the paper.])) + :common-args '() + :idx-note "lncs" + :idx-suffix " (lncs)" + :force-engines *api-engines* + :source "../skr/lncs.skr"))) + +;*---------------------------------------------------------------------*/ +;* french */ +;*---------------------------------------------------------------------*/ +(section :title "Languages" + (subsection :title (tt "french.skr") + (index :index *package-index* "french.skr" :note "package") + (p [ +Enables French typesetting and typographical rules.]))) + +;*---------------------------------------------------------------------*/ +;* letter */ +;*---------------------------------------------------------------------*/ +(section :title (tt "letter.skr") + (index :index *package-index* "letter.skr" :note "package") + (p [ +This package is to be used to authoring simple letters. It redefines the +,(markup-ref "document") markup.]) + + (doc-markup 'document + `((:where [The location where the letter is posted.]) + (:date [The date of the letter.]) + (:author [The author of the letter.])) + :idx-note "letter" + :idx-suffix " (letter)" + :force-engines *api-engines* + :source "../skr/letter.skr")) + +;*---------------------------------------------------------------------*/ +;* Web */ +;*---------------------------------------------------------------------*/ +(section :title "Web" + + (subsection :title (tt "web-article.skr") + (index :index *package-index* "web-article.skr" :note "package") + (p [ +A convenient mode for rendering articles (i.e., documents made of +sections) in HTML. The Slide package supports two ,(markup-ref "skribe-load") +user options: +,(param :style) and ,(param :css). The ,(param :style) option can either +be ,(code "'traditional") which forces traditional HTML code +emission or ,(code "'css") which forces HTML code emission using CSS +annotations. The CSS style used is specified in the (code "css") +HTML engine ,(ref :subsection "The HTML customization" :text "custom"). +The ,(param :css) is a shorthand for ,(param :style). For instance:]) +(prgm [(skribe-load "web-article.skr" :css "style.css")]) +[is equivalent to:] +(prgm [(skribe-load "web-article.skr" :style 'css) +(engine-custom-set! (find-engine 'html) :css "style.css")])) + + (subsection :title (tt "web-book.skr") + (index :index *package-index* "web-book.skr" :note "package") + (p [ +A convenient mode for rendering books (i.e., documents made of +chapters and sections) in HTML.])))) + +;*---------------------------------------------------------------------*/ +;* Emacs indentation */ +;*---------------------------------------------------------------------*/ +;; @indent: (put 'doc-markup 'skribe-indent 'skribe-indent-function)@* + diff --git a/skribe/doc/user/prgm.skb b/skribe/doc/user/prgm.skb new file mode 100644 index 0000000..c894614 --- /dev/null +++ b/skribe/doc/user/prgm.skb @@ -0,0 +1,121 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/prgm.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 09:21:11 2001 */ +;* Last change : Wed Sep 22 02:11:49 2004 (serrano) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Computer programs */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* fib ... */ +;*---------------------------------------------------------------------*/ +(define (fib x) ;!fib + (if (< x 2) + 1 + (+ (fib (- x 1)) (fib (- x 2))))) + +;*---------------------------------------------------------------------*/ +;* Computer programs */ +;*---------------------------------------------------------------------*/ +(chapter :title "Computer programs" + +(p [It is common that some parts of a Skribe text represent other +texts. For instance, for a document describing a computer programming +language, it is frequent to include excerpt of programs. These +embedded texts are frequently displayed in a specific font and with no +justification but with a precise ,(emph "indentation"). This indentation is +important because it helps in understanding the text,(begin ";") +it is thus desirable to preserve it in the Skribe text. The +,(markup-ref "pre") text layout already enables such a +text formating. This chapter presents two new Skribe functions: +,(markup-ref "prog") and ,(markup-ref "source") that is specially +designed to represent computer programs in Skribe text.]) + +;*---------------------------------------------------------------------*/ +;* Programs ... @label prog@ */ +;*---------------------------------------------------------------------*/ +(section :title "Program" + +(p [A ,(code "prog") function call preserves the indentation of the +program. It may automatically introduce line numbers.]) + +(doc-markup 'prog + `((:line ,[Enables/disables automatic line numbering. An integer + value enables the line number and specifies the number of + the first line of the program. A value of ,(code "#f") disables + the line numbering.]) + (:linedigit ,[The number of digit for representing line + numbers.]) + (:mark ,[A string or the boolean ,(code "#f"). If this option + is a string, that string is the prefix + of line marks. These marks can be used in the + ,(markup-ref "ref") reference. A mark + identifier is defined by the regular expression: + ,(code [,(char "[")_a-zA-Z,(char "]"),(char "[")_a-zA-Z0-9,(char "]")*]). The prefix and the mark are removed from the output program.])) + :force-engines *api-engines* + :see-also '(source pre ref)) + +(example-produce + (example :legend "A program" (prgm :file "src/prgm1.skb")) + (disp (include "src/prgm1.skb")))) + +;*---------------------------------------------------------------------*/ +;* Source code ... @label source@ */ +;*---------------------------------------------------------------------*/ +(section :title "Source code" + +(p [The ,(code "source") function extracts part of the source code and +enables ,(emph "fontification"). That is, some words of the program +can be rendered using different colors or faces.]) + +;!source-start +(doc-markup 'source + `((:language ,[The ,(markup-ref "language") of the source code.]) + (:file ,[The file containing the actual source code. The file + is searched in the ,(markup-ref "skribe-source-path") path.]) + (:start [A start line number or a start marker.]) + (:stop [A stop line number or a stop marker.]) + (:definition [The identifier of the definition to extract.]) + (:tab [The tabulation width.])) + :common-args '() + :force-engines *api-engines* + :see-also '(prog language ref skribe-source-path)) +;!source-stop + +(example-produce + (example :legend "The source markup" (prgm :file "src/prgm2.skb")) + (disp (include "src/prgm2.skb")))) + +;*---------------------------------------------------------------------*/ +;* Language ... @label language@ */ +;*---------------------------------------------------------------------*/ +(section :title "Language" +(index "source" :note "fontification") +(index "fontification") + +(p [The ,(code "language") function builds a language that can be used +in ,(markup-ref "source") function call.]) + +(doc-markup 'language + `((:name [A string which denotes the name of the language.]) + (:fontifier [A function of one argument (a string), that + colorizes a line source code.]) + (:extractor [A function of three arguments: an input port, + an identifier, a tabulation size. This function ,(emph "scans") + in the input port the definition is looks for.])) + :common-args '() + :force-engines *api-engines* + :see-also '(prog source ref)) + +; **** FIXME: +(cond-expand + (bigloo + (example-produce + (example :legend "An ad-hoc fontification" + (prgm :file "src/prgm3.skb")) + (disp (include "src/prgm3.skb")))) + (else + '())))) diff --git a/skribe/doc/user/sectioning.skb b/skribe/doc/user/sectioning.skb new file mode 100644 index 0000000..48bbc45 --- /dev/null +++ b/skribe/doc/user/sectioning.skb @@ -0,0 +1,117 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/sectioning.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 12:27:03 2003 */ +;* Last change : Tue Apr 6 06:45:28 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Sectioning markups */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* dummy-section-output ... */ +;*---------------------------------------------------------------------*/ +(define dummy-section-output + (lambda (n e) + (let* ((t (markup-option n :title)) + (b (markup-body n))) + (skribe-eval (center (bold t)) e) + (output b e)))) + +;*---------------------------------------------------------------------*/ +;* Sectioning */ +;*---------------------------------------------------------------------*/ +(section :title "Sectioning" :file #t + +;*--- chapter ---------------------------------------------------------*/ +(subsection :title "Chapter" + +(p [The function ,(code "chapter") creates new chapters.]) + +(doc-markup 'chapter + `((:title [The title of the chapter.]) + (:html-title "The title of window of the HTML browser.") + (:number [This argument controls the chapter number. +A value of ,(tt "#t") means that the Skribe compiler computes the chapter +number. A value of ,(tt "#f") means that the chapter has no number.]) + (:toc ,[This argument controls if the chapter must +be referenced in the ,(ref :mark "toc" :text "table of contents").]) + (:file [The argument must be a boolean. A value of +,(tt "#t") tells the Skribe compiler to compile that chapter in a separate +file. A value of ,(tt "#f") tells the Skribe compiler to embed the chapter +in the main target file.]) + (#!rest node... [The nodes of the chapter.])) + :see-also '(document section toc)) + +(example-produce + (example :legend "The chapter markup" (prgm :file "src/api4.skb")) + (disp + (processor :combinator + (lambda (e1 e2) + (let ((e (copy-engine 'document-engine e2))) + (markup-writer 'chapter e + :options '(:title :file :number :toc) + :action dummy-section-output) + e)) + (include "src/api4.skb"))))) + +;*--- section ---------------------------------------------------------*/ +(subsection :title "Sections" + +(p [These functions create new sections.]) + +(doc-markup 'section + `((:title [The title of the chapter.]) + (:number [This argument controls the chapter number. +A value of ,(tt "#t") means that the Skribe compiler computes the chapter +number. A value of ,(tt "#f") means that the chapter has no number.]) + (:toc ,[This argument controls if the chapter must +be referenced in the ,(ref :mark "toc" :text "table of contents").]) + (:file [The argument must be a boolean. A value of +,(tt "#t") tells the Skribe compiler to compile that section in a separate +file. A value of ,(tt "#f") tells the Skribe compiler to embed the chapter +in the main target file.]) + (#!rest node... [The nodes of the section.])) + :others '(subsection subsubsection) + :see-also '(document chapter paragraph toc)) + +(example-produce + (example :legend "The chapter markup" (prgm :file "src/api5.skb")) + (disp + (processor :combinator + (lambda (e1 e2) + (let ((e (copy-engine 'document-engine e2))) + (markup-writer 'chapter e + :options '(:title :file :number :toc) + :action dummy-section-output) + e)) + (include "src/api5.skb"))))) + +;*--- paragraph -------------------------------------------------------*/ +(subsection :title "Paragraph" + +(p [The function ,(code "paragraph") (also aliased ,(code "p")) creates +paragraphs.]) + +(doc-markup 'paragraph + '((#!rest node... "The nodes of the paragraph.")) + :see-also '(document chapter section p)) + +(p [The function ,(code "p") is an alias for ,(code "paragraph").]) +(doc-markup 'p + '((#!rest node... "The nodes of the paragraph.")) + :source "../skr/skribe.skr" + :see-also '(document chapter section paragraph))) + +;*--- blockquote -----------------------------------------------------*/ +(subsection :title "Blockquote" + +(p [The function ,(code "blockquote") can be used for text +quotations. A text quotation is generally renderd as an indented block +of text.]) +(doc-markup 'blockquote + '((#!rest node... "The nodes of the quoted text."))))) + + + diff --git a/skribe/doc/user/skribe-config.skb b/skribe/doc/user/skribe-config.skb new file mode 100644 index 0000000..956af63 --- /dev/null +++ b/skribe/doc/user/skribe-config.skb @@ -0,0 +1,44 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/skribe-config.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Jan 2 21:12:24 2004 */ +;* Last change : Thu Sep 23 17:11:53 2004 (eg) */ +;* Copyright : 2004 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The skribe-config tool */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The skribe-config tool */ +;*---------------------------------------------------------------------*/ +(chapter :title "Getting Skribe configuration information" +(index "skribe-config") + +(p [ +In this chapter we present ,(code "skribe-config") that gives +information about the current Skribe configuration.]) + +;; Synopsis +(section :title "SYNOPSIS" :number #f +(compiler-command "skribe-config" "options")) + +;; Description +(section :title "DESCRIPTION" :number #f [ +The ,(code "skribe-config") gives information about the Skribe configuration. +This information can be the directories used to install Skribe, the Scheme +implementation used for compiling Skribe, etc.]) + +;; Options +(section :title "OPTIONS" :number #f [ +,(pre (let* ((proc (run-process "../etc/skribe-config" "--help" error: pipe:)) + (port (process-error-port proc))) + (let loop ((line (read-line port)) + (lines '())) + (if (eof-object? line) + (reverse! lines) + (begin + (loop (read-line port) (cons* line "\n" lines)))))))])) + + + diff --git a/skribe/doc/user/skribec.skb b/skribe/doc/user/skribec.skb new file mode 100644 index 0000000..0f00632 --- /dev/null +++ b/skribe/doc/user/skribec.skb @@ -0,0 +1,56 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/skribec.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 13:43:50 2001 */ +;* Last change : Thu Feb 26 20:58:26 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe compiler */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The Skribe compiler */ +;*---------------------------------------------------------------------*/ +(chapter :title "Skribe compiler" +(index "skribe" :note "manual page") +(p [ +In this chapter we present the Skribe compiler that compiles Skribe +source text into various output formats.]) + +;; Synopsis +(section :title "SYNOPSIS" :number #f +(linebreak 1) +(compiler-command "skribe" "options" "input")) + +;; Description +(section :title "DESCRIPTION" :number #f +(p [ +This manual page is not meant to be exhaustive. The complete documentation +for the programming language ,(bold "Skribe") can be found at the following +,(ref :url (skribe-url) :text "URL"). This manual page only documents +the ,(tt "skribe") +compiler that compiles ,(bold "Skribe") programs into ,(it "HTML"), +,(it "TeX"), ,(it "Info") or ,(it "Nroff") formats.])) + +;; Suffixes +(section :title "SUFFIXES" :number #f [ +The ,(tt "skribe") compiler uses file suffixes in order to select amongst +its possible targets which one to choose. These suffixes are: + +,(description (item :key (it ".skb") [a ,(bold "Skribe") source file.]) + (item :key (it ".html") [an ,(it "HTML") target file.]) + (item :key (it ".tex") [a ,(it "TeX") target file.]) + (item :key (it ".sui") [a ,(it "Skribe url index") file.]))]) + +;; Options +(section :title "OPTIONS" :number #f [ +,(mark "skribe compiler option") +,(compiler-options *skribe-bin*)]) + +;; Environment variables +(section :title "ENVIRONMENT VARIABLES" :number #f [ +Some shell variables control the Skribe search path: +,(description (item :key (it "SKRIBEPATH") + "Search path for source and style files."))])) + diff --git a/skribe/doc/user/skribeinfo.skb b/skribe/doc/user/skribeinfo.skb new file mode 100644 index 0000000..502cc73 --- /dev/null +++ b/skribe/doc/user/skribeinfo.skb @@ -0,0 +1,50 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/skribeinfo.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 13:43:50 2001 */ +;* Last change : Mon Dec 15 13:22:08 2003 (serrano) */ +;* Copyright : 2001-03 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribeinfo compiler */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The Skribeinfo compiler */ +;*---------------------------------------------------------------------*/ +(chapter :title "Compiling Texi documents" +(index "skribeinfo" :note "compiler") +(index "texinfo") + +(p [ +In this chapter we present the Skribeinfo compiler that compiles Texinfo +(texi) source files into Skribe source file.]) + +;; Synopsis +(section :title "SYNOPSIS" :number #f +(compiler-command "skribeinfo" "options" "input")) + +;; Description +(section :title "DESCRIPTION" :number #f [ +This manual page is not meant to be exhaustive. The complete documentation +for the programming language ,(bold "Skribe") can be found at the +following ,(ref :url (skribe-url) :text "url"). This manual page only +document the ,(tt "skribeinfo") +compiler that compiles ,(bold "Texinfo") source files into ,(it "Skribe"), +source files. These Skribe files can be compiled by the ,(bold "skribe") +compiler in order to produce ,(it "HTML"), ,(it "TeX"), ,(it "Info") +or ,(it "Nroff") target files.]) + +;; Suffixes +(section :title "SUFFIXES" :number #f [ +The ,(tt "skribe") compiler uses file suffixes in order to select amongst +its possible targets which to choose. These suffixes are: + +,(description (item :key (it ".texi") [a ,(bold "Texinfo") source file.]) + (item :key (it ".skb") [a ,(bold "Skribe") source file.]) + (item :key (it ".sui") [a ,(it "Skribe url index") file.]))]) + +;; Options +(section :title "OPTIONS" :number #f [ +,(compiler-options *skribeinfo-bin*)])) + diff --git a/skribe/doc/user/slide.skb b/skribe/doc/user/slide.skb new file mode 100644 index 0000000..c1111ee --- /dev/null +++ b/skribe/doc/user/slide.skb @@ -0,0 +1,114 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/slide.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Jan 9 06:37:47 2004 */ +;* Last change : Thu Feb 26 21:00:04 2004 (eg) */ +;* Copyright : 2004 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Slides */ +;*=====================================================================*/ +(skribe-load "slide.skr") + +;*---------------------------------------------------------------------*/ +;* Computer programs */ +;*---------------------------------------------------------------------*/ +(chapter :title "Slide Package" + + (p [ +This chapter describes the facilities Skribe offers authoring slides. +In order to access the functionalities described in this chapter, it +is require to introduce a ,(code [(skribe-load "slides.skr")]) expression +at the beginning of the document. The Slide package supports two +,(markup-ref "skribe-load") user options: ,(param :advi) and ,(param :prosper). +The first one tells Skribe to generate slides for the Advi presenter. The +second one tells Skribe to generate slides for the LaTeX prosper package.]) + +;*---------------------------------------------------------------------*/ +;* slide ... @label slide@ */ +;*---------------------------------------------------------------------*/ +(section :title "Slide" + + (p [A ,(code "slide") function call creates a slide.]) + + (doc-markup 'slide + `((:title [The title of the slide.]) + (:number [The number of the slide (a boolean or an integer).]) + (:toc [This argument controls if the slide must +be referenced in the ,(mark :mark "toc" "table of contents").]) + (:vspace [The boolean ,(code "#f") or an integer representing +the vertical space size between the title and the body of the slide.]) + (:vfill [A boolean that is used to control whether a LaTeX +,(code "\\vfill") is issued at the end of the slide.]) + (:transition [The boolean ,(code "#f") or a symbol in the +list ,(code "(split blinds box wipe dissolve glitter)").]) + (:bg [The background color of the slide.]) + (:image [The background image of the slide.])) + :source "../skr/slide.skr")) + +;*---------------------------------------------------------------------*/ +;* slide-pause */ +;*---------------------------------------------------------------------*/ +(section :title "Pause" + + (p [A ,(code "slide-pause") function call introduces a pause in the slide +projection.]) + + (doc-markup 'slide-pause + '() + :common-args '() + :source "../skr/slide.skr")) + +;*---------------------------------------------------------------------*/ +;* slide-vspace ... */ +;*---------------------------------------------------------------------*/ +(section :title "Slide Vertical Space" + + (p [The ,(code "slide-vspace") introduces a vertical space in the slide.]) + + (doc-markup 'slide-vspace + '((:unit [The unit of the space.]) + (#!rest val [The size of the vertical space.])) + :common-args '() + :source "../skr/slide.skr")) + +;*---------------------------------------------------------------------*/ +;* slide-embed ... */ +;*---------------------------------------------------------------------*/ +(section :title "Slide Embed Applications" + + (p [Embed an application inside a slide.]) + + (doc-markup 'slide-embed + `((:command [The binary file for running the embedded +application.]) + (:geometry-opt [The name of the geometry option to be sent +to the embedded application.]) + (:geometry [The geometry value to be sent.]) + (:rgeometry [A relative geometry to be sent.]) + (:transient-opt [The name of the transient option to be sent +to the embedded application.]) + (:transient [The transient value to be sent.]) + (:alt [An alternative Skribe expression to be used if the +output format does not support embedded application.])) + :common-args '() + :source "../skr/slide.skr")) + +;*---------------------------------------------------------------------*/ +;* Example */ +;*---------------------------------------------------------------------*/ +(section :title "Example" + (p [Here is a complete example of Skribe slides:]) + + (if (and (engine-format? "html") + (not (equal? (engine-custom html-engine 'html-variant) "html4"))) + ;; Show the example and its result + (example-produce + (example :legend "Example of Skribe slides" + (prgm :file "src/slides.skb")) + (disp (include "src/slides.skb"))) + ;; Show only the example (i.e. don't produce a document in a document) + (example :legend "Example of Skribe slides" + (prgm :file "src/slides.skb"))))) + + diff --git a/skribe/doc/user/src/api1.skb b/skribe/doc/user/src/api1.skb new file mode 100644 index 0000000..80c4389 --- /dev/null +++ b/skribe/doc/user/src/api1.skb @@ -0,0 +1,5 @@ +(section :title "A title" "This is the body of the section") +(section :title "A title" "This" " is" " the body of the section") +(section :title "A title" :number 3 "This" " is" " the body of the section") +(section :title "A title" :toc #f :number 3 "This" " is" " the body of the section") +(section :title "A title" :number 3 :toc #f "This" " is" " the body of the section") diff --git a/skribe/doc/user/src/api10.skb b/skribe/doc/user/src/api10.skb new file mode 100644 index 0000000..207d8a7 --- /dev/null +++ b/skribe/doc/user/src/api10.skb @@ -0,0 +1,12 @@ +(center [A ,(linebreak) multilines ,(linebreak) text]) +(hrule) +(flush :side 'left [A ,(linebreak) multilines ,(linebreak) text]) +(hrule) +(flush :side 'right [A ,(linebreak) multilines ,(linebreak) text]) +(hrule) +(pre [A text layout that + + preserves + linebreaks and spaces ,(it "(into which it is still legal") +,(it "to use Skribe markups)"). +]) diff --git a/skribe/doc/user/src/api11.skb b/skribe/doc/user/src/api11.skb new file mode 100644 index 0000000..5014e30 --- /dev/null +++ b/skribe/doc/user/src/api11.skb @@ -0,0 +1,22 @@ +(itemize (item [A first item.]) + (item [A ,(bold "second") one: + ,(itemize (item "One.") + (item "Two.") + (item "Three."))]) + (item [Lists can be nested. For instance that item contains a + ,(tt "description"): + ,(description (item :key (bold "foo") + [is a usual Lisp dummy identifier.]) + (item :key (bold "bar") + [is another one.]) + (item :key (list (bold "foo") (bold "bar")) + [A description entry may contain more than + one keyword.]))]) + (item [The last ,(tt "itemize") entry contains an ,(tt "enumerate"): + ,(enumerate (item "One.") (item "Two.") (item "Three."))])) + +(itemize :symbol "-" + (item "One.") + (item "Two.") + (item "Three.") + (item "Four.")) diff --git a/skribe/doc/user/src/api12.skb b/skribe/doc/user/src/api12.skb new file mode 100644 index 0000000..b0c68da --- /dev/null +++ b/skribe/doc/user/src/api12.skb @@ -0,0 +1 @@ +(center (frame :width 10. :margin 10 (p [This is a frame.]))) diff --git a/skribe/doc/user/src/api13.skb b/skribe/doc/user/src/api13.skb new file mode 100644 index 0000000..a9acb04 --- /dev/null +++ b/skribe/doc/user/src/api13.skb @@ -0,0 +1,10 @@ +(center + (color :bg "#aaaaaa" + :margin 10 + :width 30. + (center + (color :bg "#eeeeee" :fg "blue" :width 100. :margin 10 [This is an +example of color box that uses a color for the +background ,(emph "and") the ,(color :fg "red" "foreground"). It also specifies +a width, that is, an horizontal space, the text should +span to.])))) diff --git a/skribe/doc/user/src/api14.skb b/skribe/doc/user/src/api14.skb new file mode 100644 index 0000000..a3ede40 --- /dev/null +++ b/skribe/doc/user/src/api14.skb @@ -0,0 +1,9 @@ +(center + (figure :legend "This is a unnumbered figure" + :ident "fig1" + :number #f + (frame [Skribe is a functional programming language.]))) + +(center + (figure :legend "The great Penguin" + (image :file "linux.gif"))) diff --git a/skribe/doc/user/src/api15.skb b/skribe/doc/user/src/api15.skb new file mode 100644 index 0000000..f8f4958 --- /dev/null +++ b/skribe/doc/user/src/api15.skb @@ -0,0 +1,25 @@ +(resolve (lambda (n e env) + (let* ((d (ast-document n)) + (ex (container-env-get d 'figure-env))) + (table (map (lambda (e) + (tr (td :align 'left + (markup-option e ':number) + " " + (ref :handle (handle e) + :text (markup-option e :legend)) + " (section " + (let ((c (ast-section e))) + (ref :handle (handle c) + :text (markup-option c :title))) + ")"))) + (sort ex + (lambda (e1 e2) + (let ((n1 (markup-option e1 :number)) + (n2 (markup-option e2 :number))) + (cond + ((not (number? n1)) + #t) + ((not (number? n2)) + #f) + (else + (< n1 n2))))))))))) diff --git a/skribe/doc/user/src/api16.skb b/skribe/doc/user/src/api16.skb new file mode 100644 index 0000000..a9d5705 --- /dev/null +++ b/skribe/doc/user/src/api16.skb @@ -0,0 +1,5 @@ +(image :file "linux.gif" "A first image") +(image :height 50 :file "linux.gif" "A smaller one") +(image :file "bsd.gif" "A second image") +(image :width 50 :file "bsd.gif") +(image :width 200 :height 40 :file "bsd.gif") diff --git a/skribe/doc/user/src/api17.skb b/skribe/doc/user/src/api17.skb new file mode 100644 index 0000000..42fa54f --- /dev/null +++ b/skribe/doc/user/src/api17.skb @@ -0,0 +1,9 @@ +(center + (table :border 1 :width 50. :frame 'hsides :cellstyle 'collapse + (tr :bg "#cccccc" (th :align 'center :colspan 3 "A table")) + (tr (th "Col 1") (th "Col 2") (th "Col 3")) + (tr (td :align 'center "10") (td "-20") (td "30")) + (tr (td :align 'right :rowspan 2 :valign 'center "12") (td "21")) + (tr (td :align 'center :colspan 2 "1234")) + (tr (td :align 'center :colspan 2 "1234") (td :align 'right "5")) + (tr (td :align 'center :colspan 1 "1") (td :colspan 2 "2345")))) diff --git a/skribe/doc/user/src/api18.skb b/skribe/doc/user/src/api18.skb new file mode 100644 index 0000000..2112dc4 --- /dev/null +++ b/skribe/doc/user/src/api18.skb @@ -0,0 +1,2 @@ +[Scheme,(footnote [To be pronounced ,(char "[")Skim,(char "]")]) +is a programming language,(footnote [And a great one!]).] diff --git a/skribe/doc/user/src/api19.skb b/skribe/doc/user/src/api19.skb new file mode 100644 index 0000000..cfc11f6 --- /dev/null +++ b/skribe/doc/user/src/api19.skb @@ -0,0 +1,3 @@ +(itemize (item [The character ,(code "#\\a"): ,(char #\a).]) + (item [The character ,(code "\"a\""): ,(char "a").]) + (item [The character ,(code "97"): ,(char 97).])) diff --git a/skribe/doc/user/src/api2.skb b/skribe/doc/user/src/api2.skb new file mode 100644 index 0000000..2c20965 --- /dev/null +++ b/skribe/doc/user/src/api2.skb @@ -0,0 +1,5 @@ +(document :title "This is a Scribe document" + :author (list (author :name "Foo" :email (mailto "foo@nowhere.org")) + (author :name "Bar" :email (mailto "bar@anywhere.org")) + (author :name "Gee" :email (mailto "gee@nowhere.org"))) + "A body...") diff --git a/skribe/doc/user/src/api20.skb b/skribe/doc/user/src/api20.skb new file mode 100644 index 0000000..686efcb --- /dev/null +++ b/skribe/doc/user/src/api20.skb @@ -0,0 +1,2 @@ +[A simple ,(! "string"). A more annoying one ,(! "<strong>string</strong>"). +A last one with arguments ,(! "<u>$1 $2</u>" (bold 1) (it 2)).] diff --git a/skribe/doc/user/src/api3.skb b/skribe/doc/user/src/api3.skb new file mode 100644 index 0000000..ed46eea --- /dev/null +++ b/skribe/doc/user/src/api3.skb @@ -0,0 +1,8 @@ +(author :name "Manuel Serrano" + :affiliation "Inria Sophia-Antipolis" + :url (ref :url "http://www.inria.fr/mimosa/Manuel.Serrano") + :email (mailto "Manuel.Serrano@inria.fr") + :address `("2004 route des Lucioles - BP 93" + "F-06902 Sophia Antipolis, Cedex" + "France") + :phone "phone: (+33) 4 92 38 76 41") diff --git a/skribe/doc/user/src/api4.skb b/skribe/doc/user/src/api4.skb new file mode 100644 index 0000000..cfe13f7 --- /dev/null +++ b/skribe/doc/user/src/api4.skb @@ -0,0 +1,2 @@ +(chapter :title "This is a simple chapter" :number #f :toc #f [ +Its body is just one sentence.]) diff --git a/skribe/doc/user/src/api5.skb b/skribe/doc/user/src/api5.skb new file mode 100644 index 0000000..01188c1 --- /dev/null +++ b/skribe/doc/user/src/api5.skb @@ -0,0 +1,2 @@ +(section :title "This is a simple section" :number #f :toc #f [ +Its body is just one sentence.]) diff --git a/skribe/doc/user/src/api6.skb b/skribe/doc/user/src/api6.skb new file mode 100644 index 0000000..22a1c77 --- /dev/null +++ b/skribe/doc/user/src/api6.skb @@ -0,0 +1 @@ +(toc :chapter #t :section #f :subsection #f) diff --git a/skribe/doc/user/src/api7.skb b/skribe/doc/user/src/api7.skb new file mode 100644 index 0000000..c6aec8b --- /dev/null +++ b/skribe/doc/user/src/api7.skb @@ -0,0 +1,3 @@ +(resolve (lambda (n e env) + (toc :chapter #t :section #t :subsection #t + (handle (ast-chapter n))))) diff --git a/skribe/doc/user/src/api8.skb b/skribe/doc/user/src/api8.skb new file mode 100644 index 0000000..a4403ff --- /dev/null +++ b/skribe/doc/user/src/api8.skb @@ -0,0 +1,15 @@ +(itemize (item (roman "a roman text.")) + (item (bold "a bold text.")) + (item (it "an italic text.")) + (item (emph "an emphasized text.")) + (item (underline "an underline text.")) + (item (kbd "a keyboard description.")) + (item (tt "a typewritter text.")) + (item (code "a text representing computer code.")) + (item (var "a computer program variable description.")) + (item (samp "a sample.")) + (item (sc "a smallcaps text.")) + (item (sf "a sans-serif text.")) + (item (sup "a superscripts text.")) + (item (sub "a subscripts text.")) + (item (underline (bold (it "an underline, bold, italic text."))))) diff --git a/skribe/doc/user/src/api9.skb b/skribe/doc/user/src/api9.skb new file mode 100644 index 0000000..1f6890e --- /dev/null +++ b/skribe/doc/user/src/api9.skb @@ -0,0 +1,5 @@ +(itemize + (item (font :size -2 [A smaller font.])) + (item (font :size 6 [An absolute font size.])) + (item (font :size 4. [A larger font.])) + (item (font :face "Helvetica" [An helvetica example.]))) diff --git a/skribe/doc/user/src/bib1.sbib b/skribe/doc/user/src/bib1.sbib new file mode 100644 index 0000000..3f1c04f --- /dev/null +++ b/skribe/doc/user/src/bib1.sbib @@ -0,0 +1,39 @@ +(book queinnec:lisp + (author "Queinnec, C.") + (title "Lisp In Small Pieces") + (publisher "Cambridge University Press") + (year "1996")) + +(book scheme:ieee + (title "IEEE Standard for the Scheme Programming Language") + (author "IEEE Std 1178-1990") + (publisher "Institute of Electrical and Electronic Engineers, Inc.") + (address "New York, NY") + (year "1991")) + +(misc bigloo + (url "http://www.inria.fr/mimosa/fp/Bigloo")) + +(misc scheme:r4rs + (title "The Revised4 Report on the Algorithmic Language Scheme") + (author "Clinger, W. and Rees, J.") + (month "Nov") + (year "1991") + (url "http://www.cs.indiana.edu/scheme-repository/R4RS/r4rs_toc.html")) + +(article scheme:r5rs + (title "The Revised5 Report on the Algorithmic Language Scheme") + (author "Kelsey, R. and Clinger, W. and Rees, J.") + (journal "Higher-Order and Symbolic Computation") + (volume "11") + (number "1") + (month "Sep") + (year "1998") + (url "http://kaolin.unice.fr/Bigloo/doc/r5rs.html")) + +(book as:sicp + (author "Abelson, H. and Sussman, G.") + (title "Structure and Interpretation of Computer Programs") + (year "1985") + (publisher "MIT Press") + (address "Cambridge, Mass., USA")) diff --git a/skribe/doc/user/src/bib2.skb b/skribe/doc/user/src/bib2.skb new file mode 100644 index 0000000..25417b5 --- /dev/null +++ b/skribe/doc/user/src/bib2.skb @@ -0,0 +1,7 @@ +[Scheme ,(ref :bib 'scheme:r5rs) is functional programming language. It exists +several books about this language ,(ref :bib '(as:sicp queinnec:lisp)). + +,(linebreak 2) +,(center (bold [-- Bibliography --])) + +,(center (frame :border 1 :margin 2 :width 90. (the-bibliography)))] diff --git a/skribe/doc/user/src/bib3.skb b/skribe/doc/user/src/bib3.skb new file mode 100644 index 0000000..9cb838e --- /dev/null +++ b/skribe/doc/user/src/bib3.skb @@ -0,0 +1,3 @@ +(center + (frame :border 1 :margin 2 :width 90. + (the-bibliography :pred (lambda (m n) #t)))) diff --git a/skribe/doc/user/src/bib4.skb b/skribe/doc/user/src/bib4.skb new file mode 100644 index 0000000..81ba5df --- /dev/null +++ b/skribe/doc/user/src/bib4.skb @@ -0,0 +1,5 @@ +(center + (frame :border 1 :margin 2 :width 90. + (the-bibliography :pred (lambda (m n) + (and (eq? (markup-option m 'kind) 'book) + (pair? (markup-option m 'used))))))) diff --git a/skribe/doc/user/src/bib5.skb b/skribe/doc/user/src/bib5.skb new file mode 100644 index 0000000..a0ee361 --- /dev/null +++ b/skribe/doc/user/src/bib5.skb @@ -0,0 +1,24 @@ +(center + (frame :border 1 :margin 2 :width 90. + (processor :engine + (make-engine '_ :filter string-upcase) + :combinator + (lambda (e1 e2) + (let ((e (copy-engine '_ e2))) + (markup-writer '&bib-entry-ident e + :action + (lambda (n e) + (let* ((be (ast-parent n)) + (o (markup-option be 'author)) + (y (markup-option be 'year))) + (output (markup-body o) e1) + (display ":") + (output (markup-body y) e)))) + (markup-writer '&bib-entry-title e + :action + (lambda (n e) + (skribe-eval (it (markup-body n)) e))) + e)) + (the-bibliography :pred + (lambda (m n) + (eq? (markup-option m 'kind) 'book)))))) diff --git a/skribe/doc/user/src/bib6.skb b/skribe/doc/user/src/bib6.skb new file mode 100644 index 0000000..013ca97 --- /dev/null +++ b/skribe/doc/user/src/bib6.skb @@ -0,0 +1 @@ +(bibliography :command "gzip -d --to-stdout ~a | skribebibtex" "scheme.bib.gz") diff --git a/skribe/doc/user/src/index1.skb b/skribe/doc/user/src/index1.skb new file mode 100644 index 0000000..199428c --- /dev/null +++ b/skribe/doc/user/src/index1.skb @@ -0,0 +1 @@ +(define *index1* (make-index "a new index")) diff --git a/skribe/doc/user/src/index2.skb b/skribe/doc/user/src/index2.skb new file mode 100644 index 0000000..f49cf33 --- /dev/null +++ b/skribe/doc/user/src/index2.skb @@ -0,0 +1,11 @@ +[The identifier ,(code "Foo"),(index :index *index1* "Foo") is a usually +used as an example. When two identifiers have to used, frequently the +second choice is ,(code "Bar"),(index :index *index1* "Bar" :shape (it "Bar")). +When three are needed, some use ,(code "Baz") +,(index :index *index1* "Baz" :shape (it "Baz")). + +This illustrates how to use identifier +,(index :index *index1* "Foo" :note "How to use Foo") +,(index :index *index1* "Foo" :note "How not to use Foo") +,(index :index *index1* "Fooz") +...] diff --git a/skribe/doc/user/src/index3.skb b/skribe/doc/user/src/index3.skb new file mode 100644 index 0000000..3d76a90 --- /dev/null +++ b/skribe/doc/user/src/index3.skb @@ -0,0 +1 @@ +(the-index *index1*) diff --git a/skribe/doc/user/src/links1.skb b/skribe/doc/user/src/links1.skb new file mode 100644 index 0000000..e0ce61c --- /dev/null +++ b/skribe/doc/user/src/links1.skb @@ -0,0 +1,23 @@ +[This hyperlink points to the ,(ref :figure "The great Penguin" :text "figure") +of the chapter ,(ref :chapter "Standard Markups") (or also, the +,(ref :ident "Standard Markups" :text "chapter") about markups). +In the second example of reference, no ,(code ":text") option is specified: +,(ref :figure "The great Penguin"). One may use the ,(param ":ident") +field when specified such as: ,(ref :ident "fig1") or ,(ref :figure "fig1"). + +,(linebreak) +That other one points to a well known +,(ref :url "http://slashdot.org/" :text "url"). The same without +,(code ":text"): ,(ref :url "http://slashdot.org/"). + +,(linebreak) +With more complex tricks that are explained in Section +,(ref :section "Resolve"), it is also possible use, for the text of the +reference, a container number such as chapter: +,(resolve (lambda (n e env) + (let ((s (find1-down (lambda (x) + (and (is-markup? x 'chapter) + (string=? (markup-option x :title) + "Standard Markups"))) + (ast-document n)))) + (ref :handle (handle s) :text (markup-option s :number))))).] diff --git a/skribe/doc/user/src/links2.skb b/skribe/doc/user/src/links2.skb new file mode 100644 index 0000000..7cdee07 --- /dev/null +++ b/skribe/doc/user/src/links2.skb @@ -0,0 +1,4 @@ +[It is possible to send a mail by +,(mailto "foo@nowhere.com" :text "clicking") that link. That same +reference without ,(code ":text") options: ,(mailto "foo@nowhere.com"). +] diff --git a/skribe/doc/user/src/prgm1.skb b/skribe/doc/user/src/prgm1.skb new file mode 100644 index 0000000..dcdeb88 --- /dev/null +++ b/skribe/doc/user/src/prgm1.skb @@ -0,0 +1,15 @@ +(frame :width 100. + (prog :line 10 :mark "##" [ +SKRIBE=skribe + +all: demo.html demo.man ##main-goal + +demo.html: demo.skb + $(SKRIBE) demo.skb -o demo.html + +demo.man: demo.skb + $(SKRIBE) demo.skb -o demo.man +])) + +(p [The main goal is specified line ,(ref :line "main-goal").]) + diff --git a/skribe/doc/user/src/prgm2.skb b/skribe/doc/user/src/prgm2.skb new file mode 100644 index 0000000..5b5644b --- /dev/null +++ b/skribe/doc/user/src/prgm2.skb @@ -0,0 +1,18 @@ +(frame :width 100. + (prog (source :language bigloo :file "prgm.skb" :definition 'fib))) + +(p [The Fibonacci function is defined line ,(ref :line "fib").]) + +;!start +(frame :width 100. + (prog :line 11 :mark #f + (source :language skribe :file "prgm.skb" :start 11 :stop 24))) +;!stop + +(p [Here is the source of the frame above:]) + +(frame :width 100. + (prog :line 30 :mark #f + (source :language skribe :file "src/prgm2.skb" + :start ";!start" + :stop ";!stop"))) diff --git a/skribe/doc/user/src/prgm3.skb b/skribe/doc/user/src/prgm3.skb new file mode 100644 index 0000000..51cb564 --- /dev/null +++ b/skribe/doc/user/src/prgm3.skb @@ -0,0 +1,55 @@ +(define (makefile-fontifier string) + (with-input-from-string string + (lambda () + (read/rp (regular-grammar () + ((: #\# (+ all)) + ;; makefile comment + (let ((cmt (the-string))) + (cons (it cmt) (ignore)))) + ((bol (: (+ (out " \t\n:")) #\:)) + ;; target + (let ((prompt (the-string))) + (cons (bold prompt) (ignore)))) + ((bol (: (+ alpha) #\=)) + ;; variable definitions + (let* ((len (- (the-length) 1)) + (var (the-substring 0 len))) + (cons (list (color :fg "#bb0000" (bold var)) "=") + (ignore)))) + ((+ (out " \t\n:=$")) + ;; plain strings + (let ((str (the-string))) + (cons str (ignore)))) + ((: #\$ #\( (+ (out " )\n")) #\)) + ;; variable references + (let ((str (the-string)) + (var (the-substring 2 (- (the-length) 1)))) + (cons (underline str) (ignore)))) + ((+ (in " \t\n:")) + ;; separators + (let ((nl (the-string))) + (cons nl (ignore)))) + (else + ;; default + (let ((c (the-failure))) + (if (eof-object? c) + '() + (skribe-error 'makefile "Unexpected char" c))))) + (current-input-port))))) + +(define makefile + (language :name "Makefile" + :fontifier makefile-fontifier)) + +(frame :width 100. + (prog (source :language makefile [ +SKRIBE=skribe + +all: demo.html demo.man + +demo.html: demo.skb + $(SKRIBE) demo.skb -o demo.html + +demo.man: demo.skb + $(SKRIBE) demo.skb -o demo.man +]))) diff --git a/skribe/doc/user/src/slides.skb b/skribe/doc/user/src/slides.skb new file mode 100644 index 0000000..ac584d1 --- /dev/null +++ b/skribe/doc/user/src/slides.skb @@ -0,0 +1,27 @@ +(skribe-load "slide.skr" :advi #t) + +(document :title (color :fg "red" (sf (font :size +2. "Skribe Slides"))) + :author (author :name (it "Manuel Serrano") + :affiliation [Inria Sophia Antipolis] + :address (ref :url "http://www.inria.fr/mimosa/Manuel.Serrano")) + + (if (engine-format? "html") + (slide :title "Table of contents" :number #f :toc #f + (toc :chapter #f :section #f :subsection #f :subsubsection #f + :slide #t))) + + (slide :title "X11 client" :toc #t :vspace 0.3 + + (itemize + (item "xlock") + (item "xeyes") + (item "xterm"))) + + (slide :title "Xclock" :toc #t :vspace 0.3 + + (center (sf (underline "The Unix xclock client"))) + (slide-vspace 0.3) + + (slide-pause) + (slide-embed :command "xlock" + :alt (frame "Can't run embedded application")))) diff --git a/skribe/doc/user/src/start1.skb b/skribe/doc/user/src/start1.skb new file mode 100644 index 0000000..4e37dda --- /dev/null +++ b/skribe/doc/user/src/start1.skb @@ -0,0 +1,2 @@ +(document :title [Hello World!] [ +This is a very simple text.]) diff --git a/skribe/doc/user/src/start2.skb b/skribe/doc/user/src/start2.skb new file mode 100644 index 0000000..9fcfdbf --- /dev/null +++ b/skribe/doc/user/src/start2.skb @@ -0,0 +1,2 @@ +(document :title [Hello World!] [ +This is a ,(bold [very]) ,(it [simple]) ,(color :fg [red] [text]).]) diff --git a/skribe/doc/user/src/start3.skb b/skribe/doc/user/src/start3.skb new file mode 100644 index 0000000..0705966 --- /dev/null +++ b/skribe/doc/user/src/start3.skb @@ -0,0 +1,10 @@ +(document :title [Hello World!] + +(section :title [A first Section] [ + This is a ,(bold [very]) ,(it [simple]) ,(color :fg [red] [text]).]) + +(section :title [A second Section] [ + That section contains an ,(bold itemize) construction: + ,(itemize (item [first item]) + (item [second item]) + (item [third item]))])) diff --git a/skribe/doc/user/src/start4.skb b/skribe/doc/user/src/start4.skb new file mode 100644 index 0000000..3311925 --- /dev/null +++ b/skribe/doc/user/src/start4.skb @@ -0,0 +1,13 @@ +(document :title [Various links] [ + +(section :title "A Section" [ +The first link points to an external web page. Here we point to a +,(ref :url [http://slashdot.org/] [Slashdot]) +web page. The second one points to the second +,(ref :section [A second Section] [Section]) +of that document.]) + +(section :title [A second Section] [ +The last links points to the first +,(ref :scribe [user.scr] :figure [A simple web page] [Figure]) +of the Scribe User Manual.])]) diff --git a/skribe/doc/user/src/start5.skb b/skribe/doc/user/src/start5.skb new file mode 100644 index 0000000..9e6b877 --- /dev/null +++ b/skribe/doc/user/src/start5.skb @@ -0,0 +1,9 @@ +(resolve (lambda (n e env) + (let* ((current-chapter (ast-chapter n)) + (body (markup-body current-chapter)) + (sects (filter (lambda (x) (is-markup? x 'section)) + body))) + (itemize + (map (lambda (x) + (item (it (markup-option x :title)))) + sects)))))
\ No newline at end of file diff --git a/skribe/doc/user/start.skb b/skribe/doc/user/start.skb new file mode 100644 index 0000000..f3c1e28 --- /dev/null +++ b/skribe/doc/user/start.skb @@ -0,0 +1,197 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/start.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Mon Sep 1 11:22:25 2003 */ +;* Last change : Sun Feb 29 16:14:21 2004 (eg) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Getting started with Skribe */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Getting started */ +;*---------------------------------------------------------------------*/ +(chapter :title "Getting Started" + +(p [ +In this chapter, the syntax of a Skribe text is presented ,(emph "informally"). +In particular, the Skribe syntax is compared to the HTML syntax. Then, +it is presented how one can use Skribe to make dynamic text +(i.e texts which are generated by the system rather than entered-in by hand. +Finally, It is also +presented how Skribe source files can be processed.]) + +;*--- Hello world -----------------------------------------------------*/ +(section :title "Hello World!" [ +In this section we show how to produce very simple electronic documents +with Skribe. Suppose that we want to produce the following Web document: + +,(disp [,(font :size 2. (bold "Hello World!")) +,(linebreak 2) +This is a very simple text.]) + +The HTML source file for such a page should look like: + +,(prgm :language xml [ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> +<TITLE>Hello world Example</TITLE> +</HEAD> +<BODY> +<H1>Hello World!</H1> + +This is a very simple text. +</BODY> +</HTML>]) + +In Skribe, the very same document must be written: + +,(prgm :language skribe :file "src/start1.skb")]) + +;*--- Adding colors and fonts -----------------------------------------*/ +(section :title "Adding colors and fonts" [ +Let us suppose that we want now to colorize and change the face of some +words such as: + +,(disp [,(font :size 2. (bold "Hello World!")) +,(linebreak 2) +This is a ,(bold "very") ,(it "simple") ,(color :fg "red" "text").]) + +The HTML source file for such a document should look like: + +,(prgm :language xml [ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> +<TITLE>Hello world Example</TITLE> +</HEAD> +<BODY> +<H1>Hello World!</H1> + +This is a <B>very</B> <I>simple</I> <FONT color="red">text</FONT>. +</BODY> +</HTML>]) + +In Skribe, the very same document must be written: + +,(prgm :language skribe (source :file "src/start2.skb")) + +As one may notice the Skribe version is much more compact than the HTML one.]) + +;*--- Structured documents --------------------------------------------*/ +(section :title "Structured documents" [ +,(p [For large documents there is an obvious need of structure. Skribe +documents may contain ,(bold "chapters"), ,(bold "sections"), +,(bold "subsections"), ,(bold "itemize"), ... For instance, if we want to +extend our previous example to:]) + +,(disp :verb #t [,(bold (font :size 2. "Hello World!")) + +,(font :size 1. (bold "1. A first Section")) +This is a ,(bold "very") ,(it "simple") ,(color :fg "red" "text"). + +,(font :size 1. (bold "2. A second Section")) +That contains an ,(bold "itemize") construction: + . first item + . second item + . third item]) + +The Skribe source for that text is: + +,(prgm :language skribe (source :file "src/start3.skb"))]) + +;*--- Hyperlinks ------------------------------------------------------*/ +(section :title "Hyperlinks" [ +A Skribe document may contain links to chapters, to sections, to other +Skribe documents or Web pages. The following Skribe source +code illustrates these various kinds of links: + +,(prgm :language skribe (source :file "src/start4.skb"))]) + +;*--- Dynamic documents -----------------------------------------------*/ +(section :title "Dynamic documents" [ +Since Skribe is a programming language, rather than just a markup language, +it is easy to use it to generate some parts of a document. This section +presents here the kind of documents that can be created with Skribe. + +,(subsection :title "Simple computations" [ +In this section we present how to introduce a simple computation into a +document. For instance, the following sentence +,(disp [ +Document creation date: ,(date)]) +is generated with the following piece of code + +,(prgm :language skribe [ +\[Document creation date: \,(date)\] +]) + +Here, we use the Skribe function ,(code "date") to compute the date to +be inserted in the document. In general, any valid Scheme expression +is authorized inside a ,(code ",(...)") construct.,(footnote +[Skribe can be built either with Bigloo or STklos Scheme systems. The Scheme +expressions which are valid inside a ,(code ",(...)") depends of the Scheme system +used at Skribe construction.]). +Another example of +such a computation is given below. +,(prgm :language skribe [ +\[The value of \,(symbol "pi") is \,(* 4 (atan 1))\] +]) +When evaluated, this form produces the following output: +,(disp [ +The value of ,(symbol "pi") is ,(* 4 (atan 1)).]) +]) + +,(subsection :title "Text generation" [ When building a document, one +often need to generate some repetitive text. Skribe programming skills +can be used to ease the construction of such documents as illustrated below. +,(disp +(itemize + (map (lambda (x) (item [The square of ,(bold x) is ,(bold (* x x))])) + '(1 2 3 4 5 6 7 8 9)))) +This text has been generated with the following piece of code +,(prgm :language skribe [ +(itemize + (map (lambda (x) (item \[The square of \,(bold x) is \,(bold (* x x))\])) + '(1 2 3 4 5 6 7 8 9))) +])]) + +,(subsection :title "Introspection" [ +In Skribe, a document is represented by a tree which is available to +the user. So, it is easy to perform introspective tasks on the current +document. For instance the following code displays as an +enumeration the sections titles of the current chapter: + +,(prgm :language skribe :file "src/start5.skb") + +Without entering too much into the details here, the resolve function +is called at the end of the document processing. This function +searches the node representing the chapter to which belongs the +current node and from it finds all its sections. The titles +of these sections are put in italics in an itemize. + +,(p [The execution of this code yield the following text]) + +,(disp (include "src/start5.skb"))]) +]) + + +;*--- Compiling skribe documents --------------------------------------*/ +(section :title "Compiling Skribe documents" [ + +There are several ways to render a Skribe document. It can be statically +compiled by the ,(tt "skribe") compiler to various formats such as HTML, +LaTeX, man and so on. It can be compiled on-demand by the ,(tt "mod_skribe") +,(ref :url "http://www.apache.org/" :text "Apache") Skribe module. In this +section we only present static compilation. + +,(p [Let us suppose a Skribe text located in a file ,(tt "file.skb"). +In order to compile to various formats one must type in:]) + +,(disp :verb #t [ +$ skribe file.skb -o file.html ,(char 35) ,(it "This produces an HTML file.") +$ skribe file.skb -o file.tex ,(char 35) ,(it "This produces a TeX file.") +$ skribe file.skb -o file.man ,(char 35) ,(it "This produces a man page.") +$ skribe file.skb -o file.info ,(char 35) ,(it "This produces an info page.") +$ skribe file.skb -o file.mgp ,(char 35) ,(it "This produces a MagicPoint document")])])) diff --git a/skribe/doc/user/syntax.skb b/skribe/doc/user/syntax.skb new file mode 100644 index 0000000..de60bd9 --- /dev/null +++ b/skribe/doc/user/syntax.skb @@ -0,0 +1,105 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/syntax.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 11:55:24 2001 */ +;* Last change : Sun Feb 29 16:14:53 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The syntax of Skribe */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The Skribe syntax */ +;*---------------------------------------------------------------------*/ +(chapter :title "Syntax & Values" [ +A Skribe document is composed of Skribe expressions. A Skribe expression +can be: + +,(itemize (item [An atomic expression, such as a string of characters, a number.]) + (item [A list.]) + (item [A text.])) + +Here are several examples of correct Skribe expressions: + +,(center (frame :margin 5 :border 0 :width *prgm-width* + (color :margin 5 :bg *disp-color* :width 100. +(itemize (item [,(color :fg "#009900" (tt "\"foo\"")), a string of characters composed of the +characters `,(color :fg "#009900" "f")', `,(color :fg "#009900" "o")' +and `,(color :fg "#009900" "o")'.]) + (item [,(color :fg "#009900" (tt "123") " " (tt "3.14")), two numbers.]) + (item [,(color :fg "#009900" (tt "#t") " " (tt "#f")), the ,(emph "true") and ,(emph "false") +Skribe value.]) + (item [,(color :fg "#009900" (tt "(bold \"foo bar\")")), a list.]) + (item [,(color :fg "#009900" (tt (char 91)"A text sample"(char 93))), a simple text containing +three words and no escape sequence.]) + (item [,(color :fg "#009900" (tt (char 91)"Another text sample (that is still) simple"(char 93))), +another simple text.]) + (item [,(color :fg "#009900" (tt (char 91)"Another ,(bold \"text\") sample"(char 93))), +a more complex text that contains two words (,(color :fg "#009900" (tt "Another")) and ,(color :fg "#009900" (tt "sample"))) +and an expression ,(color :fg "#009900" (tt "(bold \"text\")")). The escape sequence is introduced +with the `,(color :fg "#009900" (tt ",("))' characters.]))))) + +,(p [ +Expressions are evaluated, thus ,(color :fg "#009900" (tt "(bold \"foo\")")) +has the effect of typesetting the word ,(color :fg "#009900" (tt "foo")) in +bold face to produce ,(color :fg "#009999" (bold "foo")). Escape sequences +enable evaluation of expressions inside the text. Thus the text +,(color :fg "#009900" (tt (char 91)"Another ,(bold \"text\") sample"(char 93))) +produces `,(color :fg "#009999" (tt [Another ,(bold "text") sample]))'. +On the other hand +,(color :fg "#009900" (tt (char 91)"Another (bold \"text\") sample"(char 93))) +produces +`,(color :fg "#009999" (tt [Another (bold "text") sample]))' because it does not contain +the escape sequence `,(color :fg "#009900" (char #\,)(char #\())'.]) +] + +;*---------------------------------------------------------------------*/ +;* Formal syntax */ +;*---------------------------------------------------------------------*/ +(section :title "Skribe syntax" + +(disp :verb #t :bg *prgm-skribe-color* [ +<expr> --> <atom> + | <text> + | <list> +<list> --> (<expr>+) +<text> --> ,(bold (color :fg "red" (char 91))),(it "any sequence but `,(' or a `,")<list>,(it "'"),(bold (color :fg "red" (char 93))) +<atom> --> <boolean> + | <integer> + | <float> + | <string> + | <color> +<integer> --> ,(tt (char 91))0-9,(tt (char 93))+ +<float> --> ,(tt (char 91))0-9,(tt (char 93))+.,(tt (char 91))0-9,(tt (char 93))* + | ,(tt (char 91))0-9,(tt (char 93))*.,(tt (char 91))0-9,(tt (char 93))+ +<string> --> ,(tt #\")...,(tt #\") +<color> --> <string> + | ,(tt #\")#,(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt #\")])) + +;*---------------------------------------------------------------------*/ +;* Values */ +;*---------------------------------------------------------------------*/ +(section :title "Values" :file #f :toc #t + +;*--- width -----------------------------------------------------------*/ +(subsection :title "Width" (p [ +,(mark "width") +A Skribe ,(emph "width") refers to the horizontal size a construction +occupies on an output document. There are three different ways for +specifying a width:]) + +(description (item :key "An absolute pixel size" + [This is represented by an ,(emph "exact") integer value + (such as ,(code "350")).]) + (item :key "A relative size" + [This is represented by an ,(emph "inexact") integer value + (such as ,(code "50.0")) which ranges in the interval + ,(char 91)-100.0 .. 100.0,(char 93)]) + (item :key "An engine dependent representation" + [This is represented by a string that is directly emitted + in the output document (such as HTML column ,(code "\"0*\"") + specification). Note that this way of specifying width + is strictly unportable.]))))) + + diff --git a/skribe/doc/user/table.skb b/skribe/doc/user/table.skb new file mode 100644 index 0000000..c726d44 --- /dev/null +++ b/skribe/doc/user/table.skb @@ -0,0 +1,81 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/table.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Sep 5 13:45:18 2003 */ +;* Last change : Wed Oct 27 12:09:01 2004 (eg) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe tables */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Table ... */ +;*---------------------------------------------------------------------*/ +(section :title "Table" :file #t + + (p [Tables are defined by the means of the ,(code "table") function.]) + + (doc-markup 'table + `((:border [The table border thickness.]) + (:width ,[The ,(ref :mark "width") of the table.]) + (:frame ,[Which parts of frame to render. Must be one of + ,(code "none"), ,(code "above"), ,(code "below"), + ,(code "hsides"), ,(code "vsides"), ,(code "lhs"), + ,(code "rhs"), ,(code "box"), ,(code "border").]) + (:rules ,[Rulings between rows and cols, Must be one of + ,(code [none]), ,(code "rows"), ,(code "cols"), ,(code "header"), + ,(code "all").]) + (:cellstyle ,[The style of cells border. Must be either + ,(code "collapse"), ,(code "separate"), or a length representing + the horizontal and vertical space separating the cells.]) + (:cellpadding [A number of pixels around each cell.]) + (:cellspacing [An optional number of pixels used to separate each + cell of the table. A negative uses the target default.]) + (#!rest row... [The rows of the table. Each row must be + constructed by the ,(ref :mark "tr" :text (code "tr")) function.]))) + + (p [,(bold (emph (color :fg "red" "Note:"))) Tables rendering may be only +partially supported by graphical agents. For instance, the ,(code "cellstyle") +attribute is only supported by HTML engines supporting +,(ref :url "http://www.w3.org/TR/REC-CSS2/" :text "CSS2").]) + + +;*--- table rows ------------------------------------------------------*/ +(subsection :title "Table row" + +(p [Table rows are defined by the ,(code "tr") function.]) + +(doc-markup 'tr + '((:bg [The background color of the row.]) + (#!rest cell... [The row cells.])))) + +;*--- Table cell ------------------------------------------------------*/ +(subsection :title "Table cell" + +(p [Two functions define table cells: ,(code "th") for header cells and +,(code "td") for plain cells.]) + +(doc-markup 'th + '((:bg [The background color of the cell.]) + (:width ,[The ,(ref :mark "width") of the table.]) + (:align [The horizontal alignment of the table cell + (,(tt "left"), ,(tt "right"), or ,(tt "center"). Some + engines, such as the HTML engine, also supports a + character for the alignment.)]) + (:valign [The vertical alignment of the cell. The value can + be ,(code "top"), ,(code "center"), ,(code "bottom").]) + (:colspan [The number of columns that the cell expands to.]) + (#!rest node [The value of the cell.])) + :writer-id 'tc + :ignore-args '(m) + :others '(td))) + +;*--- Example ---------------------------------------------------------*/ +(subsection :title "Example" + +(example-produce + (example :legend "A table" (prgm :file "src/api17.skb")) + (disp (include "src/api17.skb"))))) + +;; @indent: (put 'doc-markup 'skribe-indent 'skribe-indent-function)@* diff --git a/skribe/doc/user/toc.skb b/skribe/doc/user/toc.skb new file mode 100644 index 0000000..aa6c0dc --- /dev/null +++ b/skribe/doc/user/toc.skb @@ -0,0 +1,37 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/toc.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 13:01:03 2003 */ +;* Last change : Fri Sep 12 15:31:14 2003 (serrano) */ +;* Copyright : 2003 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Table of contents */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Sectioning */ +;*---------------------------------------------------------------------*/ +(section :title "Table of contents" :file #t + +(p [The production of table of contains.]) + +(doc-markup 'toc + '((:chapter [A boolean. The value ,(code "#t") forces the + inclusion of chapters in the table of contents.]) + (:section [A boolean controlling sections.]) + (:subsection [A boolean controlling subsections.]) + (#!rest handle [An optional handle pointing to the node from + which the table of contents if computed.])) + :see-also '(document chapter section resolve handle)) + +(example-produce + (example :legend "The toc markup" (prgm :file "src/api6.skb")) + (disp (include "src/api6.skb"))) + +(p [The second example only displays the table of contents of the current +chapter.]) + +(example-produce + (example :legend "A restricted table of contents" (prgm :file "src/api7.skb")) + (disp (include "src/api7.skb")))) diff --git a/skribe/doc/user/user.skb b/skribe/doc/user/user.skb new file mode 100644 index 0000000..07a6e03 --- /dev/null +++ b/skribe/doc/user/user.skb @@ -0,0 +1,163 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/user.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Nov 28 10:37:39 2001 */ +;* Last change : Thu Feb 26 21:02:00 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The Skribe user manual */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* The Skribe documentation style */ +;*---------------------------------------------------------------------*/ +(skribe-load "web-book.skr") +(skribe-load "skr/env.skr") +(skribe-load "skr/manual.skr") +(skribe-load "skr/api.skr") + +;*---------------------------------------------------------------------*/ +;* HTML custom */ +;*---------------------------------------------------------------------*/ +;; since we load slides (for documenting it), we have to use a +;; correct title width +(let ((he (find-engine 'html))) + (engine-custom-set! he 'body-width 100.)) + +;*---------------------------------------------------------------------*/ +;* The various indexes */ +;*---------------------------------------------------------------------*/ +(define *markup-index* (make-index "markup")) +(define *custom-index* (make-index "custom")) +(define *function-index* (make-index "function")) +(define *package-index* (make-index "package")) + +;*---------------------------------------------------------------------*/ +;* The document */ +;*---------------------------------------------------------------------*/ +(document :title "Skribe User Manual" + :env '((example-counter 0) (example-env ())) + :author (list (author :name "Erick Gallesio" + :affiliation "Université de Nice - Sophia Antipolis" + :address '("930 route des Colles, BP 145" + "F-06903 Sophia Antipolis, Cedex" + "France") + :email (mailto "eg@essi.fr")) + (author :name "Manuel Serrano" + :affiliation "Inria Sophia-Antipolis" + :address `("2004 route des Lucioles - BP 93" + "F-06902 Sophia Antipolis, Cedex" + "France") + :url (ref :url *serrano-url*) + :email (mailto *serrano-mail*))) + + (linebreak 1) + (center (frame (bold (font :size 1. [ +This is the documentation for Skribe version +,(color :fg "red" (skribe-release)).])))) + (linebreak 1) + +;;; Introduction +(section :title "Introduction" :number #f :toc #f [ +Skribe is a programming language designed for implementing electronic +documents. It is mainly designed for the writing of technical documents +such as the documentation of computer programs. With Skribe these +documents can be rendered using various tools and technologies. For +instance, a Skribe document can be ,(emph "compiled") to an HTML file +that suits Web browser, it can be compiled to a TeX file in order to +produce a high-quality printed document, and so on.] + + (subsection :title "Who may use Skribe?" :number #f [ +Everyone needing to design web pages, info documents, man pages or +Postscript files can use Skribe. In particular, there is ,(bold "no need") +for programming skills in order to use Skribe. Skribe can be used as +any text description languages such as TeX, LaTeX or HTML.]) + + (subsection :title "Why using Skribe?" :number #f [ +There are three main reasons for using Skribe:] + + (itemize + (item [ +It is easier to type in Skribe texts than other text description formats. +The need for ,(emph "meta keyword"), that is, words used to describe +the structure of the text and not the text itself, is very limited.]) + (item [ +Skribe is highly skilled for computing texts. It is very common that +one needs to automatically produce parts of the text. This can +be very simple such as, for instance, the need to include inside a text, +the date of the last update or the number of the last revision. +Sometimes it may be more complex. For instance, one may be willing to +embed inside a text the result of a complex arithmetic computation. Or +even, you may want to include some statistics about that +text, such as, the number of words, paragraphs, sections, and so on. +Skribe makes these sort of text manipulation easy whereas other +systems rely on the use of text preprocessors.]) + (item [ +The same source file can be compiled to various output formats such +as HTML, Info pages, man pages, Postscript, etc.])))) + +;;; toc +(if (engine-format? "latex") + (toc :chapter #t :section #t :subsection #t)) + +;;; Getting started +(include "start.skb") + +;;; Syntax +(include "syntax.skb") + +;;; Skribe Markup Library +(include "markup.skb") + +;;; Hyperlinks and references +(include "links.skb") + +;;; Indexes +(include "index.skb") + +;;; Bibliography +(include "bib.skb") + +;;; Computer programs +(include "prgm.skb") + +;;; Standard Library +(include "lib.skb") + +;;; Engines +(include "engine.skb") + +;;; Emacs +(include "emacs.skb") + +;;; Skribe +(include "skribec.skb") + +;;; Slides +(include "slide.skb") + +;;; Packages +(include "package.skb") + +;;; skribe-config +(include "skribe-config.skb") + +;;; List of examples +(include "examples.skb") + +;;; table of contents +(if (not (engine-format? "latex")) + (begin + (chapter :title "Table of contents" + (toc :chapter #t :section #t :subsection #t)) + (section :title "Index" :number #f + (mark "global index") + (the-index :column (if (engine-format? "latex") 2 3) + *markup-index* *custom-index* *function-index* *package-index* + (default-index)))) + (chapter :title "Index" + (mark "global index") + (the-index :column (if (engine-format? "latex") 2 3) + *markup-index* *custom-index* *function-index* *package-index* + (default-index))))) diff --git a/skribe/doc/user/xmle.skb b/skribe/doc/user/xmle.skb new file mode 100644 index 0000000..4a1ee78 --- /dev/null +++ b/skribe/doc/user/xmle.skb @@ -0,0 +1,25 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/xmle.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Wed Sep 3 11:20:49 2003 */ +;* Last change : Tue Apr 6 06:27:51 2004 (serrano) */ +;* Copyright : 2003-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* The documentation of the XML engine */ +;*=====================================================================*/ +;; @indent: (put 'doc-engine 'skribe-indent 'skribe-indent-function)@ + +;*---------------------------------------------------------------------*/ +;* Document */ +;*---------------------------------------------------------------------*/ +(section :title "Xml engine" :file #t + (mark "xml-engine") + (index "Xml" :note "Engine") + (p [The Xml engine...]) + + (subsection :title "The Xml customization" + + (doc-engine 'xml + `() + :source "skr/xml.skr"))) |
