13.3 Skribilo User Manual — Lout Engine
Contents↑ Engines

The Lout engine produces documents for the Lout typesetting system, 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.

Skribilo's Lout engine provides lots of customization opportunities (currently more than the 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.

13.3.1 Lout Customization

customdefaultdescription
document-typedocA symbol denoting the underlying Lout document type, i.e., one of doc (the default), report, book or slides. Note that these document types are not interchangeable: slides should be used only when using the slides package; report and book do not permit text in the body of a document outside chapters. Also, these document types provide different layout features, book being the ``richest'' one; in addition, some of the customs below do not apply to all these document types.
document-includeautoDocument style file include line (a string such as @Include { my-doc-style.lout }) or the symbol auto in which case the include file is deduced from document-type.
includes"@SysInclude { tbl } "A string containing @Include directives.
inline-definitions-proc(unquote lout-definitions)A procedure that is passed the engine and returns Lout definitions to be included at the beginning of the document as a string.
encoding"ISO-8859-1"The encoding of the output document1. As of Lout 3.39, only "ISO-8859-1" and "ISO-8859-2" are supported.
initial-font"Palatino Base 10p"Lout specification of the document font.
initial-break(unquote (string-append "unbreakablefirst " "unbreakablelast " "hyphen adjust 1.2fx"))Lout specification of the default paragraph breaking style.
initial-language"English"Lout specification of the document's language. This is used to select hyphenation rules, among other things.
column-number1Number of columns.
first-page-number1Number of the first page.
page-orientationportraitA symbol denoting the page orientation, one of portrait, landscape, reverse-portrait or reverse-landscape.
cover-sheet?#tFor report, this boolean determines whether a cover sheet should be produced. The doc-cover-sheet-proc custom may also honor this custom for doc documents.
date-line#tFor report and 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#fFor report, this can be an arbitrary Skribe expression for use as an abstract.
abstract-title#tFor report, the title/name of the abstract. If #f then no abstract title is produced. If #t, then a default abstract title is chosen according to initial-language.
publisher#fFor book, the publisher.
edition#fFor book, the edition.
before-title-page#fFor book, an expression that will appear before the title page.
on-title-page#fFor book, the expression used as the title page.
after-title-page#fFor book, an expression that will appear right after the title page.
at-end#fFor book, an expression that will appear at the end of the book, on a page of its own.
optimize-pages?#fA boolean indicating whether to optimize pages. Refer to Lout's User's Guide for caveat.
doc-cover-sheet-proc(unquote lout-make-doc-cover-sheet)For doc, a procedure that produces the title or cover sheet. When invoked, the procedure is passed the document node and the engine.
bib-refs-sort-proc#fKept for backward compability, do not use.
paragraph-gap" //1.0vx @ParaIndent @Wide &{0i} "Lout code for paragraph gaps. Note that the default value is not @PP as one would expect but is instead similar to @PP with @ParaGap equal to 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" @LP "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?#fA 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-lines2Number of lines over which dropped capitals span. Only 2 and 3 are currently supported.
use-header-rows?#fFor multi-page tables, setting this to #t allows header rows to be repeated on each new page. However, it appears to be buggy at the moment.
use-lout-footnote-numbers?#fTells 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(unquote lout-split-external-link)A procedure that takes a URL ref markup and returns a list containing (maybe) one such 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 @ExternalLink symbols to work around the fact that @ExternalLink objects are unbreakable. In order to completely disable use of @ExternalLink, just set it to markup-body.
toc-leader"."A string, which is the leader used in table-of-content entries.
toc-leader-space"2.5s"Inter-leader space in table-of-contents entries.
toc-entry-proc(unquote lout-make-toc-entry)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"lout"The lout program path, only useful when producing lout-illustration on other engines.
lout-program-arguments()List of additional arguments that should be passed to lout, e.g., ("-I foo" "-I bar").
make-pdf-docinfo?#tTells whether to produce PDF "docinfo", i.e., meta-information with title, author, etc.
pdf-title#tTitle for use as the PDF document meta-information. If #t, the document's :title is used.
pdf-author#tAuthor for use as the PDF document meta-information. If #t, the document's :author is used.
pdf-keywords#fKeywords (a list of string) in the PDF document information. This custom is deprecated, use the :keywords option of document instead.
pdf-extra-info(("SkribiloVersion" (unquote (skribilo-version))))A list of key-value pairs (strings) to appear in the PDF meta-information.
make-pdf-outline?#tTells whether to produce a PDF outline (aka. "bookmarks").
pdf-bookmark-title-proc(unquote lout-pdf-bookmark-title)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(unquote lout-pdf-bookmark-node?)Predicate that takes a node and an engine and returns true if that node should have a PDF outline entry.
pdf-bookmark-closed-pred(unquote (lambda (n e) (not (and (markup? n) (memq (markup-markup n) (quote (chapter slide slide-topic)))))))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?#tIndicate whether to use colors or not.
source-color#tA boolean enabling/disabling color of source code (see source markup).
source-comment-color"#ffa600"The source comment color.
source-define-color"#6959cf"The source define color.
source-module-color"#1919af"The source module color.
source-markup-color"#1919af"The source markup color.
source-thread-color"#ad4386"The source thread color.
source-string-color"red"The source string color.
source-bracket-color"red"The source bracket color.
source-type-color"#00cf00"The source type color.

13.3.2 Additional Markup

The (skribilo engine lout) module also exports a new markup called lout-illustration, which provides an engine-independent way to include illustrations written in Lout, such as @Diag pictures. When an engine other than Lout is used, lout-illustration are first automatically translated to EPS (using Lout's @Illustration) and then to whatever image format is supported by the engine (see Section Images).

prototype
(lout-illustration :alt :ident [:file] illustration...)
optionenginesdescription
:identhtml lout latex context info xml An identifier. This identifier is also used as the basis of the EPS file name with non-Lout engines.
:fileIf different from #f, this specifies a file where the Lout illustration is stored.
:altA string displayed on display devices not capable of displaying images, as for image.
argumentdescription
illustration...The illustration itself if :file is #f.

The following example shows a simple diagram. When using the lout engine, the diagram is integrated in-line in the document. When using other engines, it is integrated using image.

(use-modules (skribilo engine lout))

(lout-illustration :ident "document-toolchain"
                   :alt "a document toolchain" "

# This is Lout code to produce a diagram.
@Diag
  aoutline { circle }
  afont { Courier Base 1f }
  boutline { circle }
  bfont { Palatino Slope 2f }
  bpaint { black }
  bformat { white @Color @Body }
  coutline { curvebox }
  coutlinestyle { dotted }
  doutline { curvebox }
{
  @Tbl
    strut { yes }
    indent { ctr }
    aformat { @Cell A | @Cell marginhorizontal { 2.0fe } B |
              @Cell C | @Cell D }
    amargin { 1.0fe }
  {
    @Rowa D { W:: @DNode HTML }
    @Rowa A { A:: @ANode txt } C { P:: @CNode Lout }
          D { X:: @DNode PostScript }
    @Rowa A { B:: @ANode skr } B { S:: @BNode Skribilo }
          C { Q:: @CNode @LaTeX }
    @Rowa A { C:: @ANode rss } C { R:: @CNode ConTeXt }
          D { Y:: @DNode PDF }
    @Rowa D { Z:: @DNode Info }
  }

  //

  # input arrows
  @Arrow from { A } to { S }
  @Arrow from { B } to { S }
  @Arrow from { C } to { S }

  # arrows to intermediate files
  @Arrow from { S } to { P }
  @Arrow from { S } to { Q }
  @Arrow from { S } to { R }

  # PS/PDF incoming arrows
  @Arrow from { P } to { X }
  @Arrow from { P } to { Y }
  @Arrow from { Q } to { X }
  @Arrow from { Q } to { Y }
  @Arrow from { R } to { X }
  @Arrow from { R } to { Y }

  # HTML and Info
  @Link from { S } to { W } arrow { yes } path { vhcurve }
  @Link from { S } to { Z } arrow { yes } path { vhcurve }

}
")
Ex. 42: A Lout illustration

... produces:

a document toolchain



1 This option is supported when Guile 2.0+ is being used.
(made with skribilo)