Guile Present version 0.3.0, updated 21 September 2014 Andy Wingo (wingo@pobox.com)
This manual is for Guile Present (version 0.3.0, updated 21 September 2014) Copyright 2014 Andy Wingo Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License or (at your option) any later version. You should have received a copy of the GNU Lesser General Public License along with this manual; if not, see http://www.gnu.org/licenses/.
i Short Contents 1 (present)............................................ 1 2 (present org-mode).................................... 3 3 (present texinfo)...................................... 4 4 (present cairo)........................................ 5 5 (present svg)......................................... 6 6 (present fold)........................................ 7 7 (present util)......................................... 9 8 org-to-pdf-presentation................................ 10 9 texi-to-pdf-presentation............................... 11 Concept Index.......................................... 12 Function Index.......................................... 13
Chapter 1: (present) 1 1 (present) 1.1 Overview Guile-Present is a library to create presentations in Guile Scheme. It has three parts: A specification of the declarative presentation language; A set of parsers to transform other formats to the presentation language; and A rendering library to render a presentation onto some kind of graphics device. For examples of a parser, see Chapter 2 [(present org-mode)], page 3. Renderers are built on a pure-functional layout algorithm (see Chapter 6 [(present fold)], page 7). One renderer (see [presentation->svg], page 6) produces a single layered SVG. Guile-Present also includes a command line tool (see Chapter 8 [org-to-pdf-presentation], page 10) to render an Org Mode file directly into a PDF suitable for presenting with a PDF viewer. See Section Summary in Org Mode Manual, for more information on Org Mode. 1.2 Presentation language The presentation language defined in Guile-Present is a dialect of SXML. See http://ssax. sourceforge.net/ for more information on SXML. The elements defined in the presentation language are as follows: presentation The top-level node. No attributes defined; may contain slide elements. slide title header Defines a slide. May contain attributes title and level, where level is an integer indicating the level of subsectioning. A title, as might appear on a title slide. May contain text elements, which will normally be rendered on a separate lines. A header line. May contain text elements, which will normally be rendered on a separate lines. image An image. May not contain subelements. Will open an image named the current value of the image-filename parameter, at the size image-width and image-height. p ul li A set of text lines. No attributes defined. Each child text element will normally be rendered on a separate line. An unordered list. May only contain li elements. No attributes defined. A list element. May contain p or ul elements. No attributes defined. For example, the following example shows a presentation with one title slide and one body slide:
Chapter 1: (present) 2 (presentation (slide (@ (title "title-slide") (level 0)) (title "Presentation language")) (slide (@ (title "Summary") (level 1)) (header "Summary") (p "The presentation language" "is not particularly expressive.") (ul (li (p "Few elements defined") (ul (li (p "This will change with time")))) (li "Unclear specification")) (p "However, it is what we have."))) 1.3 Usage
Chapter 2: (present org-mode) 3 2 (present org-mode) 2.1 Overview Routines to read files written in Emacs org-mode, parsing them into the presentation SXML language. 2.2 Usage org->presentation port Parse a file written in Emacs org-mode into the presentation SXML format. Note that only a limited subset of org-mode s syntax is understood. Specifically, inline text formatters (e.g. _emphasized_ ) are not parsed, although it would be nice to do so in the future. Here is an example of a document that this code understands: # -*- mode: org; fill-column: 34 -*- #+TITLE: Presentation title * Outline First we talk about this Then we talk about that * This ** This: foo Whereas * Foo is an elegant solution to problems in the bar domain * Still, baz * Zag * Metasyntactic Foo!
Chapter 3: (present texinfo) 4 3 (present texinfo) 3.1 Overview Transform parsed texinfo into the presentation SXML language. See Guile-Lib s (texinfo) for more information. 3.2 Usage stexi->presentation stexi Transform stexi into the presentation SXML format. Note that only a limited subset of texinfo is understood.
Chapter 4: (present cairo) 5 4 (present cairo) 4.1 Overview Routines to render SXML documents from the presentation vocabulary using the Cairo graphics library. 4.2 Usage presentation-render-cairo presentation cr Convert an SXML document in the presentation vocabulary to a multi-layered SVG. The result will still be a document in SXML format, so if you want to write it to disk, use sxml->xml. See Section (sxml simple) in Guile Library, for more information. The resulting SVG will be written with annotations readable by Inkscape, a vector graphics editor, which help to make the SVG easily editable. If your toolchain does not understand namespaces, you might want to filter out elements that start with sodipodi:, xmlns:, and inkscape:.
Chapter 5: (present svg) 6 5 (present svg) 5.1 Overview Routines to transform SXML documents from the presentation vocabulary into SVG. The code in this file was originally presented in Andy Wingo s 2007 paper, Applications of fold to XML transformation. 5.2 Usage presentation->svg presentation Convert an SXML document in the presentation vocabulary to a multi-layered SVG. The result will still be a document in SXML format, so if you want to write it to disk, use sxml->xml. See Section (sxml simple) in Guile Library, for more information. The resulting SVG will be written with annotations readable by Inkscape, a vector graphics editor, which help to make the SVG easily editable. If your toolchain does not understand namespaces, you might want to filter out elements that start with sodipodi:, xmlns:, and inkscape:.
Chapter 6: (present fold) 7 6 (present fold) 6.1 Overview (present fold) defines a number of variants of the fold algorithm for use in transforming presentations. Additionally it defines the layout operator, fold-layout, which might be described as a context-passing variant of SSAX s pre-post-order. 6.2 Usage foldt fup fhere tree The standard multithreaded tree fold. fup is of type [a] -> a. fhere is of type object -> a. fold proc seed list The standard list fold. proc is of type a -> b -> b. seed is of type b. list is of type [a]. foldts fdown fup fhere seed tree The single-threaded tree fold originally defined in SSAX. See Section (sxml ssax) in Guile Library, for more information. foldts* fdown fup fhere seed tree A variant of [foldts], page 7 that allows pre-order tree rewrites. Originally defined in Andy Wingo s 2007 paper, Applications of fold to XML transformation. fold-values proc list. seeds A variant of [fold], page 7 that allows multi-valued seeds. Note that the order of the arguments differs from that of fold. foldts*-values fdown fup fhere tree. seeds A variant of [foldts*], page 7 that allows multi-valued seeds. Originally defined in Andy Wingo s 2007 paper, Applications of fold to XML transformation. fold-layout tree bindings params layout stylesheet A traversal combinator in the spirit of SSAX s Section pre-post-order in Guile Library. fold-layout was originally presented in Andy Wingo s 2007 paper, Applications of fold to XML transformation. bindings := (<binding>...) binding := (<tag> <handler-pair>...) (*default* <handler-pair>...) (*text*. <text-handler>) tag := <symbol> handler-pair := (pre-layout. <pre-layout-handler>) (post. <post-handler>) (bindings. <bindings>) (pre. <pre-handler>) (macro. <macro-handler>)
Chapter 6: (present fold) 8 pre-layout-handler A function of three arguments: kids params layout the kids of the current node, before traversal the params of the current node the layout coming into this node pre-layout-handler is expected to use this information to return a layout to pass to the kids. The default implementation returns the layout given in the arguments. post-handler A function of five arguments: tag params layout klayout kids the current tag being processed the params of the current node the layout coming into the current node, before any kids were processed the layout after processing all of the children the already-processed child nodes post-handler should return two values, the layout to pass to the next node and the final tree. text-handler text-handler is a function of three arguments: text params layout the string the current params the current layout text-handler should return two values, the layout to pass to the next node and the value to which the string should transform.
Chapter 7: (present util) 9 7 (present util) 7.1 Overview Utility procedures and macros. 7.2 Usage match-bind [Special Form] Match a string against a regular expression, binding lexical variables to the various parts of the match. vars is a list of names to which to bind the parts of the match. The first variable of the list will be bound to the entire match, so the number of variables needed will be equal to the number of open parentheses ( ( ) in the pattern, plus one for the whole match. consequent is executed if the given expression str matches regex. If the string does not match, alternate will be executed if present. If alternate is not present, the result of match-bind is unspecified. Here is a short example: (define (star-indent line) "Returns the number of spaces until the first star ( * ) in the input, or #f if the first non-space character is not a star." (match-bind "^( *)\*.*$" line (_ spaces) (string-length spaces) #f)) match-bind compiles the regular expression regex at macro expansion time. For this reason, regex must be a string literal, not an arbitrary expression.
Chapter 8: org-to-pdf-presentation 10 8 org-to-pdf-presentation 8.1 Overview org-to-pdf-presentation is a command-line script offered by Guile-Lib that can transform a file written in Emacs Org Mode and directly produce a PDF file, suitable for presenting with a PDF viewer. org-to-pdf-presentation works by rendering each slide as an SVG, then using librsvg to convert the SVGs to one PDF of many pages. You will need the tool, rsvg-convert, provided under Debian as librsvg2-bin. 8.2 Usage org-to-pdf-presentation in-org-file out-pdf-file [Command] Convert the Org Mode file in-org-file into a PDF suitable for presentations. This command is subject to the limitations of org->presentation. Namely, only a subset of all Org Mode constructs are supported. See [org->presentation], page 3, for more information.
Chapter 9: texi-to-pdf-presentation 11 9 texi-to-pdf-presentation 9.1 Overview texi-to-pdf-presentation is a command-line script offered by Guile-Present that can transform a file written in a subset of Texinfo into a presentation as a PDF file, suitable for presenting with a PDF viewer. texi-to-pdf-presentation works by rendering each slide using Guile-Cairo. You will need Guile-Cairo, and optionally guile-rsvg if you include SVG images. 9.2 Usage texi-to-pdf-presentation in-texi-file out-pdf-file [Command] Convert the Texinfo file in-texi-file into a PDF suitable for presentations. This command is subject to the limitations of stexi->presentation. Namely, only a subset of all Texinfo constructs are supported. See [stexi->presentation], page 4, for more information.
Concept Index 12 Concept Index (Index is nonexistent)
Function Index 13 Function Index F fold............................................ 7 fold-layout.................................... 7 fold-values.................................... 7 foldt.......................................... 7 foldts......................................... 7 foldts*........................................ 7 foldts*-values................................ 7 M match-bind..................................... 9 O org->presentation............................. 3 org-to-pdf-presentation..................... 10 P presentation->svg............................. 6 presentation-render-cairo................... 5 S stexi->presentation.......................... 4 T texi-to-pdf-presentation................... 11