8. Skribilo User Manual — Equation Formatting
Contents↑ Skribilo User Manual

Skribilo comes with an equation formatting package. This package may be loaded by adding the following form at the top of your document:

  1: (use-modules (skribilo package eq))
It allows the inclusion of (complex) equations in your documents, such as, for example, the following:
An illustration
This chapter will describe the syntactic facilities available to describe equations, as well as the rendering options.

8.1 Syntax

To start with, let's have a look at a concrete example.

;; The golden ratio, phi.
(eq (eq:= (symbol "phi")
           (eq:/ (eq:+ 1 (eq:sqrt 5))
                 2)))


Ex. 36: Example of a simple equation using the verbose syntax

... produces:

φ = (1 + sqrt(5)) / 2
In this example, the eq: sub-markups are used pretty much like any other kind of markup. However, the resulting syntax is very verbose and hard to read.

Fortunately, the eq package allows for the use of a much simpler syntax.

;; The golden ratio, phi.
(eq '(= phi (/ (+ 1 (sqrt 5)) 2)))

Ex. 37: Example of a simple equation

... produces:

φ = (1 + sqrt(5)) / 2
Readers familiar with the Lisp family of programming languages may have already recognized its prefix notation. Note that, unlike in the previous example, the equation itself if quoted, that is, preceded by the ' sign. Additionally, when referring to a symbol (such as the Greek letter φ), you no longer need to use the symbol markup (see Section 3.15.3).

It is possible to create equation display blocks, where several equations are displayed and aligned according to a particular operator.

(p [This paragraph contains this equation: ,(eq :inline? #t '(/ alpha
beta)).  This is actually an ,(emph [inline]) equation, meaning that it
occurs within a paragraph.  Typesetting has to be adjusted
accordingly.])

(eq-display
         
   (p [This is an equation display block, within which equations can be
aligned with one another.])

   (eq :ident "eq-limit-b-over-l"
       :renderer 'lout
       :align-with '=
       '(= (limit (/ lambda beta) 0
                   (apply IPL n k))

            ;; non-simplified
            (/ (expt (+ alpha beta) k)
               (* beta
                  (sum :from (= x 0)
                       :to   (- k 1)
                       (* (combinations k x)
                          (expt beta (- k 1 x))
                          (expt alpha x)))))))

   [This equation can be simplified as follows:]

   (eq :ident "eq-limit-b-over-l-simplified"
       :renderer 'lout
       :align-with '=
       '(= ;; simplified
            (/ (expt (+ alpha beta) k)
               (- (expt (+ alpha beta) k)
                  (expt alpha k)))
         
            (limit (/ lambda beta) 0
                   (apply IPL n k)))))

Ex. 38: Inlined, displayed, and aligned equations

... produces:

This paragraph contains this equation: α / β. This is actually an inline equation, meaning that it occurs within a paragraph. Typesetting has to be adjusted accordingly.

This is an equation display block, within which equations can be aligned with one another.


An illustration
This equation can be simplified as follows:
An illustration


8.2 Rendering


8.3 Summary

The options available for the top-level eq markup are summarized here:

prototype
(eq [:number #t] [:mul-style 'space] [:div-style 'over] [:renderer] [:align-with] [:inline? 'auto] [:class "eq"] [:ident])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:inline?lout If auto, Skribilo will automatically determine whether the equation is to be "in-line". Otherwise, it should be a boolean indicating whether the equation is to appear "in-line", i.e., within a paragraph. If the engine supports it, it may adjust various parameters such as in-equation spacing accordingly.
:numberlout If true, then a number is automatically assigned to the equation and displayed. If it is a string, then that string is used as the equation's number. If #f, then the equation is left unnumbered. Note that this option is only taken into account for displayed equations.
:rendererThe engine that should be used to render the equation. This allows, for instance, to use the Lout engine to render equations in HTML.
:mul-stylelout A symbol denoting the default style for multiplications. This should be one of space, cross, asterisk or dot.
:div-stylelout A symbol denoting the default style for divisions. This should be one of over, fraction, div and slash. Per-eq:/ :div-style options override this setting.
:align-withlout Within a eq-display block, this should be a symbol specifying according to which operator equations are to be aligned with one another.

Equation display blocks can be defined using eq-display. Display blocks define the scope of the alignment among equations as specified by the :align-with options of eq.

prototype
(eq-display [:class "eq-display"] [:ident])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.

(made with skribilo)