summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès2008-01-24 16:02:43 +0100
committerLudovic Courtès2008-01-24 16:02:43 +0100
commit87819ed728dc9cbb2cccbf236a665709ef663abf (patch)
tree1dc6713bc640423ae52f50bdbb1da0ed08812900
parentbf65015355fc0afe9bde6edc85118818de27bedc (diff)
downloadskribilo-87819ed728dc9cbb2cccbf236a665709ef663abf.tar.gz
skribilo-87819ed728dc9cbb2cccbf236a665709ef663abf.tar.lz
skribilo-87819ed728dc9cbb2cccbf236a665709ef663abf.zip
doc: Document the "compiler".
* doc/modules/skribilo/documentation/manual.scm (compiler-options): Rewritten to suit our needs. * doc/user/Makefile.am (EXTRA_DIST): `skribec.skb' renamed to `compiler.skb'. * doc/user/bib.skb: Fix xref. * doc/user/lib.skb: Likewise. * doc/user/links.skb: Likewise. * doc/user/syntax.skb: Add `:ident'.
-rw-r--r--doc/modules/skribilo/documentation/manual.scm61
-rw-r--r--doc/user/Makefile.am4
-rw-r--r--doc/user/bib.skb2
-rw-r--r--doc/user/compiler.skb141
-rw-r--r--doc/user/engine.skb1
-rw-r--r--doc/user/lib.skb2
-rw-r--r--doc/user/links.skb40
-rw-r--r--doc/user/skribec.skb68
-rw-r--r--doc/user/syntax.skb20
-rw-r--r--doc/user/user.skb4
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")