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'.

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")