diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/modules/skribilo/documentation/manual.scm | 61 | ||||
| -rw-r--r-- | doc/user/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/user/bib.skb | 2 | ||||
| -rw-r--r-- | doc/user/compiler.skb | 141 | ||||
| -rw-r--r-- | doc/user/engine.skb | 1 | ||||
| -rw-r--r-- | doc/user/lib.skb | 2 | ||||
| -rw-r--r-- | doc/user/links.skb | 40 | ||||
| -rw-r--r-- | doc/user/skribec.skb | 68 | ||||
| -rw-r--r-- | doc/user/syntax.skb | 20 | ||||
| -rw-r--r-- | doc/user/user.skb | 4 |
10 files changed, 239 insertions, 104 deletions
diff --git a/doc/modules/skribilo/documentation/manual.scm b/doc/modules/skribilo/documentation/manual.scm index 4010982..9fddcaf 100644 --- a/doc/modules/skribilo/documentation/manual.scm +++ b/doc/modules/skribilo/documentation/manual.scm @@ -36,7 +36,10 @@ :use-module (skribilo source xml) :use-module (oop goops) - :use-module (ice-9 optargs)) + :use-module (ice-9 optargs) + :use-module (srfi srfi-1) + :use-module (srfi srfi-13) + :use-module (srfi srfi-37)) (fluid-set! current-reader %skribilo-module-reader) @@ -401,11 +404,51 @@ ;*---------------------------------------------------------------------*/ ;* compiler-options ... */ ;*---------------------------------------------------------------------*/ -(define-markup (compiler-options bin) - (skribe-message " [executing: ~a --options]\n" bin) - (let ((port (open-input-file (format #f "| ~a --options" bin)))) - (let ((opts (read port))) - (close-input-port port) - (apply description (map (lambda (opt) (item :key (bold (car opt)) - (cadr opt) ".")) - opts))))) +(define-markup (compiler-options module . descriptions) + ;; Fetch an SRFI-37 option list from MODULE (a module name) and use option + ;; descriptions from DESCRIPTIONS. + + ;; XXX: We don't have something as smart as what Skribe had that would + ;; allow automatic extract of option documentation. OTOH, descriptions in + ;; the manual can be verbose and can include hyperlinks, which differs from + ;; descriptions in `--help' output, so it makes sense to have some + ;; duplication here. + (let ((options (module-ref (resolve-module module) '%options))) + (description + (map (lambda (option) + (let* ((names (option-names option)) + (short-name (find char? names)) + (long-names (filter string? names)) + (doc (assoc-ref descriptions + (or short-name (car long-names))))) + (define (make-option-list) + (let ((long (map (lambda (long) + (string-append "--" long)) + long-names))) + (string-join (if short-name + (cons (string-append "-" + (string short-name)) + long) + long) + ", "))) + + (define (make-key) + (string-append + (make-option-list) + (let ((arg-name (if doc (car doc) "ARG"))) + (cond ((option-required-arg? option) + (string-append (if (null? long-names) " " "=") + arg-name)) + ((option-optional-arg? option) + (string-append (if (null? long-names) " [" "[=") + arg-name "]")) + (else ""))))) + + (item :key (tt (make-key)) + (if doc + (if (or (option-optional-arg? option) + (option-required-arg? option)) + (cadr doc) + (car doc)) + "")))) + options)))) diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am index 014e315..385f641 100644 --- a/doc/user/Makefile.am +++ b/doc/user/Makefile.am @@ -4,7 +4,7 @@ EXTRA_DIST = bib.skb char.skb colframe.skb document.skb emacs.skb \ font.skb footnote.skb htmle.skb image.skb index.skb \ justify.skb latexe.skb lib.skb line.skb links.skb \ markup.skb ornament.skb package.skb pie.skb prgm.skb sectioning.skb \ - skribilo-config.skb skribec.skb skribeinfo.skb slide.skb spacing.skb \ + skribilo-config.skb compiler.skb skribeinfo.skb slide.skb spacing.skb \ start.skb syntax.skb table.skb toc.skb user.skb xmle.skb \ lout/book-style.lout @@ -33,6 +33,8 @@ skrflags = -I $(srcdir) -P $(top_srcdir)/doc/img \ -B $(srcdir) \ -e '(define %top-srcdir "$(top_srcdir)")' \ -e '(define %top-builddir "$(top_builddir)")' + +# FIXME: Eventually, we should use the native API. skrflags += --compat=skribe if HAVE_PLOTICUS diff --git a/doc/user/bib.skb b/doc/user/bib.skb index f5dde61..afd9760 100644 --- a/doc/user/bib.skb +++ b/doc/user/bib.skb @@ -317,7 +317,7 @@ bibliography entries.]) ;; Suffixes (subsection :title "SUFFIXES" :number #f [ -The ,(ref :chapter "Skribe compiler" :text "skribe") compiler uses file +The ,(ref :chapter "Skribilo Compiler" :text "skribilo") compiler uses file suffixes in order to select amongst its possible targets which to choose. These suffixes are: diff --git a/doc/user/compiler.skb b/doc/user/compiler.skb new file mode 100644 index 0000000..cde4146 --- /dev/null +++ b/doc/user/compiler.skb @@ -0,0 +1,141 @@ +;;; compiler.skb -- The Skribilo compiler. +;;; +;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> +;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano +;;; +;;; +;;; This program is free software; you can redistribute it and/or modify +;;; it under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 2 of the License, or +;;; (at your option) any later version. +;;; +;;; This program is distributed in the hope that it will be useful, +;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with this program; if not, write to the Free Software +;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +;;; USA. + +;*---------------------------------------------------------------------*/ +;* The compiler */ +;*---------------------------------------------------------------------*/ +(chapter :title "Skribilo Compiler" + :ident "compiler" + +(index "skribilo" :note "compiler") +(p [This chapter introduces the Skribilo compiler, i.e., the tool that +turns input documents into various output formats.]) + +;; Synopsis +(section :title "Synopsis" :number #f + + (p (compiler-command "skribilo" "options" "input"))) + +;; Description +(section :title "Description" :number #f + + (p [The ,(tt [skribilo]) compiler turns Skribilo input documents into +one of a variety of output formats, including HTML, LaTeX and Lout. The +input format is specified using the ,(tt [--reader]) command-line +option, while the output format is specified using the ,(tt [--target]) +option. These options and others are described below.])) + +;; Suffixes +(section :title "Suffixes" :number #f + + (p [A number of file name extensions are used by convention: + +,(description + (item :key (tt ".skb") [a Skribilo or Skribe source file.]) + (item :key (tt ".html") [an HTML target file.]) + (item :key (tt ".lout") [a Lout target file.]) + (item :key (tt ".tex") [a TeX, LaTeX or ConTeXt target file.]) + (item :key (tt ".sui") [a Skribe URL index file.]))])) + + +;; Options +(section :title "Options" :number #f + + (mark "skribilo compiler options") + (p [The options supported by the ,(tt [skribilo]) compiler are listed +below. They follow the usual GNU convention, i.e., each option can have +both a short name (a hyphen followed by a single character) and a long +name (two hyphens followed by a name).]) + + (index "compatibility" :note "Skribe compatibility mode") + + (p (compiler-options '(skribilo) + `(#\h ,[Produce a help message.]) + `(#\V ,[Show program version.]) + `(#\R "reader" ,[Use ,(tt "reader") to read the input file, +i.e., as the format of the input file. Currently, two formats are +supported: ,(tt [skribe]), which corresponds to the Skribe syntax (see +,(numref :text [Chapter] :ident "syntax")), or ,(tt [outline]), which +corresponds to plain text (markup-less) following the structuring +conventions of ,(ref :text [Emacs' Outline mode] :url +"http://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html").]) + `(#\t "engine" ,[Use ,(tt "engine") as the engine, i.e., as +the output format. For details on engines and for a list of supported +engines, see ,(numref :text [Chapter] :ident "engines").]) + `("compat" "compat" ,[Use ,(tt "compat") as the compatibility +mode. This defaults to ,(tt [skribilo]). Specifying ,(tt [skribe]) +enables the ,(ref :text [Skribe] :url +"http://www-sop.inria.fr/mimosa/fp/Skribe/") compatibility mode, making +it possible to compile most Skribe documents. Technically, the ,(tt +[skribe]) compatibility mode populates the name space of Skribilo +documents with bindings available to Skribe documents and that are not +available by default to Skribilo documents,(footnote [Skribe uses a +single name space for all the code of packages, documents, in addition +to bindings provided by the underlying Scheme implementation.]) (e.g., +,(srfi-ref 1) functions, Bigloo's hash table API, etc.); for Skribe +functions not available in Skribilo, such as ,(tt [skribe-load]), a +compatible implementation is provided.]) + `(#\o "file" ,[Write output to ,(tt [file]).]) + + `(#\I "dir" ,[Prepend ,(tt [dir]) to the document include path.]) + `(#\B "dir" ,[Prepend ,(tt [dir]) to the bibliography include path.]) + `(#\S "dir" ,[Prepend ,(tt [dir]) to the source include path.]) + `(#\P "dir" ,[Prepend ,(tt [dir]) to the image include path.]) + + `(#\b "base" ,[Strip ,(tt [base]) (an arbitrary string, +typically an URL) from all hyperlinks when producing ,(ref :mark +"html-engine" :text [HTML files]).]) + `(#\e "expr" ,[Prepend ,(tt [expr]) to the list of expressions +to be evaluated before the input document is processed. ,(tt [expr]) is +evaluated in the document's environment/module; thus, this option can be +used to pass parameters to the document, e.g., with ,(tt [-e '(define +chbouib-enabled? "yes")']).]) + `(#\p "file" ,[Pre-load ,(tt [file]) before processing the input +document. ,(tt [file]) is evaluated in the document's name space and +should be a regular Scheme file, i.e., it cannot use the ,(ref :text +[Skribe syntax] :ident "syntax").]) + + `(#\v "level" ,[Be verbose, unless ,(tt [level]) is ,(tt [0]).]) + `(#\w "level" ,[Issue warnings, unless ,(tt [level]) is ,(tt [0]).]) + `(#\g "arg" ,[Issue debugging output, unless ,(tt [arg]) is ,(tt +[0]). If ,(tt [arg]) is not a number, it is interpreted as a symbol to +be watched.]) + `("no-color" ,[By default, debugging output is colored on +capable terminals such as ,(tt [xterm]) or the Linux console (check your +,(tt [TERM]) environment variable). This option turns coloring off.])))) + + +;; Environment variables +(section :title "Environment Variables" :number #f + + (p [The ,(tt [skribilo]) command does not pay attention to any +specific environment variable. In particular, it does not honor the +,(tt [SKRIBEPATH]) variable that is recognized by Skribe. Instead, you +should use the ,(tt [-I]) command-line option to specify the load path +of ,(emph [documents]) (see ,(markup-ref "include")), or, alternatively, +change the value of the ,(tt [GUILE_LOAD_PATH]) variable, which affects +Guile's own module load path.]))) + + +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/engine.skb b/doc/user/engine.skb index 9fdf500..b50c880 100644 --- a/doc/user/engine.skb +++ b/doc/user/engine.skb @@ -26,6 +26,7 @@ ;* Engine */ ;*---------------------------------------------------------------------*/ (chapter :title "Engines" + :ident "engines" (p [Skribilo documents can be rendered, or output, in a variety of different formats. When using the compiler, which format is used is diff --git a/doc/user/lib.skb b/doc/user/lib.skb index dcf8d6e..4c558db 100644 --- a/doc/user/lib.skb +++ b/doc/user/lib.skb @@ -44,7 +44,7 @@ call.])) (p [Skribilo provides functions to deal with paths. These functions are related to the path that can be specified on the command line, when the Skribilo compiler is invoked (see Chapter -,(ref :chapter "Skribe compiler").)]) +,(ref :ident "compiler").)]) (doc-markup '*document-path* '() diff --git a/doc/user/links.skb b/doc/user/links.skb index 0bc19f7..812bd32 100644 --- a/doc/user/links.skb +++ b/doc/user/links.skb @@ -1,5 +1,6 @@ -;;; links.skb -- Skribe links +;;; links.skb -- Links and cross-references. ;;; +;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2003, 2004 Manuel Serrano ;;; ;;; @@ -21,10 +22,12 @@ ;*---------------------------------------------------------------------*/ ;* 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 +(chapter :title "References and Hyperlinks" + + (p [Skribilo supports traditional ,(emph [cross-references]) (that +is, references to some part of documents) and ,(emph [hyperlinks]) (that +is, visual marks enriching texts that enable interactive +browsing). Hyperlinks and references may point to: ,(itemize (item [Inner parts of a document, such as a section or a figure.]) (item [Other documents, such as Web documents.]) @@ -32,7 +35,7 @@ texts that enable interactive browsing). Hyperlinks may point to (item [Specific part of other Skribe documents, such as a chapter of another Skribe document.])) -,(paragraph [In order to use hyperlinks, Skribe documents must:]) +In order to use hyperlinks, Skribilo documents must: ,(itemize (item [,(emph "Refer to") marks. This is the role of the ,(tt "ref") Skribe function.]) @@ -42,7 +45,7 @@ texts that enable interactive browsing). Hyperlinks may point to 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.]))] + with an hyperlink.]))]) ;*---------------------------------------------------------------------*/ ;* mark ... @label mark@ */ @@ -140,7 +143,7 @@ printed documents, as produced by the Lout and LaTeX engines. The ;*---------------------------------------------------------------------*/ ;* mailto ... @label mailto@ */ ;*---------------------------------------------------------------------*/ -(section :title "Electronic mails" +(section :title "Electronic Mail" (p [The ,(code "mailto") function is mainly useful for electronic output formats that are able to run a mailing agent. The function ,(tt "mailto") @@ -157,13 +160,15 @@ introduces mail annotation in a Skribe document.]) ;*---------------------------------------------------------------------*/ ;* Skribe Url Index ... */ ;*---------------------------------------------------------------------*/ -(section :title "Skribe Url Index" [ -,(p [A ,(emph "Skribe Url Index") (henceforth ,(sc "Sui")) describes the +(section :title "Skribe URL Index" + :ident "sui" + +(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* [ +(disp :verb #t :bg *prgm-skribe-color* [ <sui> --> (skribe-url-index <title> :file <file-name> (marks <sui-ref>*) @@ -173,11 +178,16 @@ of a ,(sc "Sui") file is:]) (subsubsection <sui-ref>*)) <sui-ref> --> (<string> :file <file-name> :mark <string>)]) -,(p [,(sc "Sui") files can be automatically produced by the Skribe compiler. +(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])])) +(disp :verb #t [ +$ skribilo user.skb -o user.sui]))) -;; LocalWords: Hyperlinks HTML URL url +;;; LocalWords: Hyperlinks HTML URL url + +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/skribec.skb b/doc/user/skribec.skb deleted file mode 100644 index ec83d3d..0000000 --- a/doc/user/skribec.skb +++ /dev/null @@ -1,68 +0,0 @@ -;;; skribec.skb -- The Skribe compiler -;;; -;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> -;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano -;;; -;;; -;;; This program is free software; you can redistribute it and/or modify -;;; it under the terms of the GNU General Public License as published by -;;; the Free Software Foundation; either version 2 of the License, or -;;; (at your option) any later version. -;;; -;;; This program is distributed in the hope that it will be useful, -;;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;;; GNU General Public License for more details. -;;; -;;; You should have received a copy of the GNU General Public License -;;; along with this program; if not, write to the Free Software -;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, -;;; USA. - -;*---------------------------------------------------------------------*/ -;* The Skribe compiler */ -;*---------------------------------------------------------------------*/ -(chapter :title "Skribe compiler" - :ident "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 (FIXME) -;;(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/doc/user/syntax.skb b/doc/user/syntax.skb index 4b18d33..7a47273 100644 --- a/doc/user/syntax.skb +++ b/doc/user/syntax.skb @@ -1,5 +1,6 @@ -;;; syntax.skb -- The syntax of Skribe +;;; syntax.skb -- The Skribe syntax. ;;; +;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano ;;; ;;; @@ -21,9 +22,11 @@ ;*---------------------------------------------------------------------*/ ;* The Skribe syntax */ ;*---------------------------------------------------------------------*/ -(chapter :title "Syntax & Values" [ -A Skribe document is composed of Skribe expressions. A Skribe expression -can be: +(chapter :title "Syntax & Values" + :ident "syntax" + + (p [A Skribilo 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.]) @@ -61,12 +64,12 @@ On the other hand 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" +(section :title "Skribe Syntax" (disp :verb #t :bg *prgm-skribe-color* [ <expr> --> <atom> @@ -111,4 +114,7 @@ specifying a width:]) specification). Note that this way of specifying width is strictly unportable.]))))) - +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/user.skb b/doc/user/user.skb index b1469d9..4147292 100644 --- a/doc/user/user.skb +++ b/doc/user/user.skb @@ -170,8 +170,8 @@ as HTML, PostScript, Info pages, etc.]))))) ;;; Emacs (include "emacs.skb") -;;; Skribilo -(include "skribec.skb") +;;; Compiler +(include "compiler.skb") ;;; Slides (include "slide.skb") |