diff options
Diffstat (limited to 'doc/user/loute.skb')
| -rw-r--r-- | doc/user/loute.skb | 225 |
1 files changed, 225 insertions, 0 deletions
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: |