summaryrefslogtreecommitdiff
path: root/doc/user/compiler.skb
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/compiler.skb')
-rw-r--r--doc/user/compiler.skb141
1 files changed, 141 insertions, 0 deletions
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: