doc: Document the Lout engine.

* doc/modules/skribilo/documentation/env.scm (*api-engines*): Add
  `lout'.

* doc/user/engine.skb: Include `loute.skb'.

* doc/user/slide.skb (Slide Package): Add `:ident'.

3 files changed, 227 insertions, 0 deletions

diff --git a/doc/user/engine.skb b/doc/user/engine.skb
index b50c880..f80236e 100644
--- a/doc/user/engine.skb
+++ b/doc/user/engine.skb
@@ -185,6 +185,7 @@ This is all it takes to extend Skribilo's set of engines!])))
 
    ;; existing engines
    (include "htmle.skb")
+   (include "loute.skb")
    (include "latexe.skb")
    (include "xmle.skb"))
 
diff --git a/doc/user/loute.skb b/doc/user/loute.skb
new file mode 100644
index 0000000..5817177
--- /dev/null
+++ b/doc/user/loute.skb
@@ -0,0 +1,225 @@
+;;; loute.skb  --  Documentation of the Lout engine.
+;;;
+;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
+;;;
+;;;
+;;; 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.
+
+
+(section :title "Lout Engine" :file #t
+         
+   (mark "lout-engine")
+   (index "Lout" :note "Engine")
+
+   (p [The Lout engine produces documents for the ,(ref :text [Lout
+typesetting system] :url "http://www.cs.usyd.edu.au/~jeff/"), which is
+then suitable for the production of PostScript/PDF files for printing.
+Lout is a typesetting system comparable to TeX/LaTeX in functionality.
+However, it is based on a lazy, purely functional programming language
+and makes it easy to customize document layout; it is also lightweight
+compared to typical LaTeX installations, consuming less than 10,(~)MiB
+of disk space.])
+   
+   (p [Skribilo's Lout engine provides lots of customization
+opportunities (currently more than the ,(ref :mark "latex-engine" :text
+[LaTeX engine])), which are shown below.  It also enhances Lout by
+adding new features: PDF bookmarks, high-level interface to the use of
+dropped capitals, improved paragraph indentation, etc.])
+   
+   (subsection :title [Lout Customization]
+      
+      (doc-engine 'lout
+        `((document-type ,[A symbol denoting the underlying Lout
+document type, i.e., one of ,(tt [doc]) (the default), ,(tt [report]),
+,(tt [book]) or ,(tt [slides]).  Note that these document types are not
+interchangeable: ,(tt [slides]) should be used only when using the ,(ref
+:ident "slides" :text [,(tt [slides]) package]); ,(tt [report]) and ,(tt
+[book]) do not permit text in the body of a document outside chapters.
+Also, these document types provide different layout features, ,(tt
+[book]) being the ``richest'' one; in addition, some of the customs
+below do not apply to all these document types.])
+	  (document-include ,[Document style file include line (a string
+such as ,(code [@Include { my-doc-style.lout }])) or the symbol ,(tt
+[auto]) in which case the include file is deduced from ,(tt
+[document-type]).])
+	  (includes         ,[A string containing ,(code [@Include])
+directives.])
+	  (inline-definitions-proc ,[A procedure that is passed the
+engine and returns Lout definitions to be included at the beginning of
+the document as a string.])
+
+	  (initial-font     ,[Lout specification of the document font.])
+	  (initial-break    ,[Lout specification of the default
+paragraph breaking style.])
+	  (initial-language ,[Lout specification of the document's
+language.  This is used to select hyphenation rules, among other
+things.])
+
+	  (column-number    ,[Number of columns.])
+	  (first-page-number ,[Number of the first page.])
+	  (page-orientation ,[A symbol denoting the page orientation,
+one of ,(tt [portrait]), ,(tt [landscape]), ,(tt [reverse-portrait]) or
+,(tt [reverse-landscape]).])
+          (cover-sheet?     ,[For ,(tt [report]), this boolean determines
+whether a cover sheet should be produced.  The ,(tt
+[doc-cover-sheet-proc]) custom may also honor this custom for ,(tt
+[doc]) documents.])
+          (date-line        ,[For ,(tt [report]) and ,(tt [slide]),
+determines whether a date line will appear on the first page (if it's a
+boolean), or what date line will appear (if it's not a boolean).])
+	  (abstract         ,[For ,(tt [report]), this can be an
+arbitrary Skribe expression for use as an abstract.])
+	  (abstract-title   ,[For ,(tt [report]), the title/name of the
+abstract.  If ,(tt [#f]) then no abstract title is produced.  If ,(tt
+[#t]), then a default abstract title is chosen according to ,(tt
+[initial-language]).])
+
+	  (publisher        ,[For ,(tt [book]), the publisher.])
+	  (edition          ,[For ,(tt [book]), the edition.])
+	  (before-title-page ,[For ,(tt [book]), an expression that will
+appear before the title page.])
+          (on-title-page    ,[For ,(tt [book]), the expression used as
+the title page.])
+          (after-title-page ,[For ,(tt [book]), an expression that will
+appear right after the title page.])
+          (at-end           ,[For ,(tt [book]), an expression that will
+appear at the end of the book, on a page of its own.])
+       
+          (optimize-pages?  ,[A boolean indicating whether to optimize
+pages.  Refer to Lout's User's Guide for caveat.])
+	  (doc-cover-sheet-proc ,[For ,(tt [doc]), a procedure that
+produces the title or cover sheet.  When invoked, the procedure is
+passed the ,(markup-ref "document") node and the engine.])
+          (bib-refs-sort-proc ,[Kept for backward compability, do not
+use.])
+
+	  (paragraph-gap    ,[Lout code for paragraph gaps.  Note that the
+default value is not ,(code [@PP]) as one would expect but is instead
+similar to ,(code [@PP]) with ,(code [@ParaGap]) equal to ,(code
+[1.0vx]), which means that a regular inter-line space is used as
+inter-paragraph space.  This differs from Lout's default where the
+inter-paragraph space is larger than the inter-line space, but looks
+better, at least in the author's eyes.])
+	  (first-paragraph-gap ,[Gap for the first paragraph within a
+container (e.g., the first paragraph of a chapter).  This allows
+paragraphs to have a different indentation depending on whether they are
+the first paragraph of a section or not.  By default, the first
+paragraph is not indented and subsequent paragraph are indented.])
+
+	  (drop-capital?     ,[A boolean or predicate indicating whether
+drop capitals should be used at the beginning of paragraphs.  When
+invoked, the predicate is passed the node at hand and the engine.])
+	  (drop-capital-lines ,[Number of lines over which dropped
+capitals span.  Only 2 and 3 are currently supported.])
+	  
+	  (use-header-rows?  ,[For multi-page ,(markup-ref "table")s,
+setting this to ,(tt [#t]) allows header rows to be repeated on each new
+page.  However, it appears to be buggy at the moment.])
+          (use-lout-footnote-numbers? ,[Tells whether to use Lout's
+footnote numbering scheme or Skribilo's number.  Using Lout's numbering
+scheme may yield footnote numbers that are different from those obtained
+with other engines, which can be undesirable.])
+          (transform-url-ref-proc ,[A procedure that takes a URL
+,(markup-ref "ref") markup and returns a list containing (maybe) one
+such ,(markup-ref "ref") markup.  This custom can be used to modify the
+way URLs are rendered.  The default value is a procedure that limits the
+size of the text passed to Lout's ,(tt [@ExternalLink]) symbols to work
+around the fact that ,(tt [@ExternalLink]) objects are unbreakable.  In
+order to completely disable use of ,(tt [@ExternalLink]), just set it to
+,(tt [markup-body]).])
+          
+	  (toc-leader       ,[A string, which is the leader used in
+table-of-content entries.])
+          (toc-leader-space ,[Inter-leader space in table-of-contents
+entries.])
+	  (toc-entry-proc   ,[Procedure that takes a large-scale structure
+(chapter, section, etc.) and the engine and produces the number and
+possibly title of this structure for use in table-of-contents.])
+
+	  (lout-program-name ,[The ,(tt [lout]) program path, only
+useful when producing ,(markup-ref "lout-illustration") on other
+engines.])
+	  (lout-program-arguments ,[List of additional arguments that
+should be passed to ,(tt [lout]), e.g., ,(tt [("-I foo" "-I bar")]).])
+       
+          (make-pdf-docinfo? ,[Tells whether to produce PDF "docinfo",
+i.e., meta-information with title, author, etc.])
+          (pdf-title         ,[Title for use as the PDF document
+meta-information.  If ,(tt [#t]), the ,(markup-ref "document")'s ,(param
+:title) is used.])
+          (pdf-author        ,[Author for use as the PDF document
+meta-information.  If ,(tt [#t]), the ,(markup-ref "document")'s ,(param
+:author) is used.])
+	  (pdf-keywords      ,[Keywords (a list of string) in the PDF
+document information.  This custom is deprecated, use the ,(param
+:keywords) option of ,(markup-ref "document") instead.])
+	  (pdf-extra-info    ,[A list of key-value pairs (strings) to
+appear in the PDF meta-information.])
+
+          (make-pdf-outline? ,[Tells whether to produce a PDF outline
+(aka. "bookmarks").])
+          (pdf-bookmark-title-proc ,[Procedure that takes a node and an
+engine and return a string representing the title of that node's PDF
+bookmark.])
+	  (pdf-bookmark-node-pred ,[Predicate that takes a node and an
+engine and returns true if that node should have a PDF outline entry.])
+          (pdf-bookmark-closed-pred ,[Predicate that takes a node and
+an engine and returns true if the bookmark for that node should be
+closed ("folded") when the user opens the PDF document.])
+
+          (color?            ,[Indicate whether to use colors or not.])
+
+	  ;; 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."))
+	:source "skribilo/engine/lout.scm"))
+   
+   (subsection :title [Additional Markup]
+      
+      (p [The ,(tt [(skribilo engine lout)]) module also exports a new
+markup called ,(tt [lout-illustration]), which provides an
+engine-independent way to include illustrations written in Lout, such as
+,(tt [@Diag]) pictures.  When an engine other than Lout is used, ,(tt
+[lout-illustration]) are first automatically translated to EPS (using
+Lout's ,(tt [@Illustration])) and then to whatever image format is
+supported by the engine (see Section ,(ref :section "Images")).])
+      
+      (doc-markup 'lout-illustration
+                  `((:ident ,[An identifier.  This identifier is also
+used as the basis of the EPS file name with non-Lout engines.])
+                    (:file  ,[If different from ,(tt [#f]), this
+specifies a file where the Lout illustration is stored.])
+	            (:alt   ,[A string displayed on display devices not
+capable of displaying images, as for ,(markup-ref "image").])
+	            (#!rest illustration... ,[The illustration itself if ,(param :file)
+is ,(tt [#f]).]))
+                  :common-args '()
+		  :source #f
+                  :def '(define-markup (lout-illustration :rest
+		  illustration :key (file #f) ident alt) ...))))
+
+;;; Local Variables:
+;;; coding: latin-1
+;;; ispell-local-dictionary: "american"
+;;; End:
diff --git a/doc/user/slide.skb b/doc/user/slide.skb
index b6ccd6b..cb411ab 100644
--- a/doc/user/slide.skb
+++ b/doc/user/slide.skb
@@ -59,6 +59,7 @@
 ;*    Computer programs                                                */
 ;*---------------------------------------------------------------------*/
 (chapter :title "Slide Package"
+         :ident "slides"
 
    (p [This chapter describes the facilities Skribilo offers authoring
 slides.  As usual, in order to access the functionalities described in