Skribilo is a free document production tool that takes a structured document representation as its input and renders that document in a variety of output formats: HTML and Info for on-line browsing, and Lout and LaTeX for high-quality hard copies.
The input document can use Skribilo's markup language to provide information about the document's structure, which is similar to HTML or LaTeX and does not require expertise. Alternatively, it can use a simpler, “ markup-less” format that borrows from Emacs' outline mode and from other conventions used in emails, Usenet and text.
Last but not least, Skribilo can be thought of as a complete document programming framework for the Scheme programming language that may be used to automate a variety of document generation tasks. Technically, the Skribilo language/API is an embedded domain-specific language (EDSL), implemented via so-called “deep embedding”. Skribilo uses GNU Guile 3.0 or 2.x as the underlying Scheme implementation.
Releases are available from the download area.
Skribilo is distributed under the terms of the GNU General Public Licence, version 3 or later. To use Skribilo, you need the following pieces of software:
The user manual is available in the following formats:
Here is a live example: the source code of this web page, colored using Skribilo's computer program coloring features.
1: ;;; 2: ;;; Skribilo's Wonderful Website. 3: ;;; 4: 5: (use-modules (skribilo ast) 6: (skribilo engine) 7: (skribilo source lisp) 8: (skribilo package html-navtabs)) 9: 10: (define (html-tabs n e) 11: ;; Create one "navigation tab" for each chapter. 12: (let ((doc (ast-document n))) 13: (map handle 14: (container-search-down (lambda (n) 15: (is-markup? n 'chapter)) 16: doc)))) 17: 18: 19: (let ((html (find-engine 'html))) 20: (if (engine? html) 21: (begin 22: ;; Customizing the HTML output... 23: (engine-custom-set! html 'css "static/main.css") 24: (engine-custom-set! html 'html-navtabs-produce-css? #f) 25: (engine-custom-set! html 'html-navtabs html-tabs) 26: (engine-custom-set! html 'charset "UTF-8")))) 27: 28: 29: 30: ;;; 31: ;;; List of useful URLs. 32: ;;; 33: 34: (define (wikipedia/markup . body) 35: (ref :url "http://en.wikipedia.org/wiki/Markup_language" 36: :text body)) 37: 38: (define (wikipedia/markup-less . body) 39: (ref :url "http://en.wikipedia.org/wiki/Lightweight_markup_language" 40: :text body)) 41: 42: (define (wikipedia/esperanto . body) 43: (ref :url "http://en.wikipedia.org/wiki/Esperanto" 44: :text body)) 45: 46: (define (scheme . body) 47: (ref :url "http://schemers.org/" :text body)) 48: 49: (define (guile . body) 50: (ref :url "http://www.gnu.org/software/guile/guile.html" :text body)) 51: 52: (define (r6rs . body) 53: (ref :url "http://r6rs.org/" :text body)) 54: 55: (define (latex . body) 56: (ref :url "http://www.latex-project.org/" :text body)) 57: 58: (define (context . body) 59: (ref :url "http://www.pragma-ade.nl/" :text body)) 60: 61: (define (lout . body) 62: (ref :url "http://savannah.nongnu.org/projects/lout/" :text body)) 63: 64: (define (info . body) 65: (ref :url "http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Files.html" 66: :text body)) 67: 68: (define (ploticus . body) 69: (ref :url "http://ploticus.sf.net/" :text body)) 70: 71: (define (guile-lib . body) 72: (ref :url "http://www.nongnu.org/guile-lib/" :text body)) 73: 74: (define (freedom . body) 75: (ref :url "http://www.gnu.org/philosophy/free-sw.html" :text body)) 76: 77: (define (gpl . body) 78: (ref :url "http://www.gnu.org/licenses/gpl.html" :text body)) 79: 80: (define (emacs/outline . body) 81: (ref :url "http://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html" 82: :text body)) 83: 84: (define (skribilo-ml . body) 85: (ref :url "http://lists.nongnu.org/mailman/listinfo/skribilo-users" 86: :text body)) 87: 88: (define (git . body) 89: (ref :url "http://git.or.cz/" :text body)) 90: 91: (define (skribe* . body) 92: (ref :url "http://www-sop.inria.fr/mimosa/fp/Skribe/" :text body)) 93: 94: (define (scribe . body) 95: (ref :url "http://www-sop.inria.fr/members/Manuel.Serrano/scribe/" :text body)) 96: 97: (define (bigloo . body) 98: (ref :url "http://www-sop.inria.fr/mimosa/fp/Bigloo/" :text body)) 99: 100: (define (stklos . body) 101: (ref :url "http://stklos.net/" :text body)) 102: 103: (define %user-sui 104: ;; Location of the User Manual's SUI file. 105: "doc/user.sui") 106: 107: 108: ;;; 109: ;;; The website. 110: ;;; 111: 112: (document :title [Skribilo: The Ultimate Document Programming Framework] 113: :author #f 114: :keywords '("Skribilo" "document programming" 115: "document formatting" "authoring" 116: "Scheme" "Guile" 117: "Skribe" "Lout" "LaTeX" "HTML") 118: 119: (mark "intro") 120: 121: (p [Skribilo is a ,(freedom [free]) document production tool that 122: takes a structured document representation as its input and renders that 123: document in a variety of output formats: HTML and ,(info [Info]) for 124: on-line browsing, and ,(lout [Lout]) and ,(latex [LaTeX]) for 125: high-quality hard copies.]) 126: 127: (p [The input document can use Skribilo's ,(wikipedia/markup [markup 128: language]) to provide information about the document's structure, which 129: is similar to HTML or ,(latex [LaTeX]) and does not require expertise. 130: Alternatively, it can use a simpler, “,(wikipedia/markup-less 131: [markup-less])” format that borrows from ,(emacs/outline [Emacs' 132: outline mode]) and from other conventions used in emails, Usenet and 133: text.]) 134: 135: (p [Last but not least, Skribilo can be thought of as a complete 136: ,(emph [document programming framework]) for the ,(scheme [Scheme 137: programming language]) that may be used to automate a variety of 138: document generation tasks. Technically, the Skribilo language/API is an 139: embedded domain-specific language (EDSL), implemented ,(it [via]) 140: so-called ,(ref :url 141: "http://www.haskell.org/haskellwiki/Embedded_domain_specific_language#Degree_of_embedding" 142: :text [“deep embedding”]). Skribilo uses ,(guile [GNU Guile]) 3.0 or 2.x 143: as the underlying Scheme implementation.]) 144: 145: 146: (chapter :title [Features] :number #f :file #f 147: :ident "features" 148: 149: (itemize 150: (item [Output in a ,(ref :skribe %user-sui :ident "engines" 151: :text [variety of formats]): HTML, XML, ,(lout [Lout]), ,(latex 152: [LaTeX]), ,(context [ConTeXt]), and ,(info [Info]).]) 153: (item [Input using ,(skribe* [Skribe])'s ,(ref :skribe 154: %user-sui :ident "skribe-syntax" :text [markup]) (see ,(ref :mark "self" 155: :text [this example])), using ,(ref :skribe %user-sui :ident 156: "commonmark-syntax" :text [CommonMark]), using 157: conventions similar to those used in ,(ref :skribe %user-sui :ident 158: "outline-syntax" :text [Emacs' outline mode]), or from an ,(ref :skribe 159: %user-sui :ident "rss2-syntax" :text [RSS,(~)2 feed]).]) 160: (item [Packages are available to produce: ,(ref :skribe 161: %user-sui :ident "slides" :text [slides]) (overhead transparencies), 162: ,(ref :skribe %user-sui :ident "pie-charts" :text [pie charts]), ,(ref 163: :skribe %user-sui :ident "equations" :text [equation formatting]), ,(ref 164: :skribe %user-sui :ident "programs" :text [syntax highlighting of 165: computer programs]), and others.]) 166: (item [,(ref :skribe %user-sui :chapter "Bibliographies" :text 167: [Bibliography management])—i.e., BibTeX on steroids thanks to the 168: programmability brought by ,(scheme [Scheme]).]) 169: (item [Unicode support.]) 170: (item [Use of a proper module system (that of ,(guile 171: [Guile])) rather than ,(tt [load])-style interactions.]) 172: (item [And much more! :-)]))) 173: 174: (chapter :title [Availability] :number #f :file #f 175: :ident "download" 176: 177: (p [Releases are available from the ,(ref :text [download area] 178: :url "http://dl.sv.nongnu.org/releases/skribilo/").]) 179: 180: (p [Skribilo is distributed under the terms of the ,(gpl [GNU 181: General Public Licence]), version 3 or later. To use Skribilo, 182: you need the following pieces of software: 183: 184: ,(itemize 185: (item [,(guile [GNU Guile]) 3.0, 2.2.*, or 2.0.*;]) 186: (item [,(ref :url "http://www.nongnu.org/guile-reader/" 187: :text [Guile-Reader]) 0.6 or later;]) 188: (item [either ,(lout [Lout]) (3.31 or later), ,(latex [LaTeX]), or 189: ,(context [ConTeXt]) to produce hard copies (PostScript/PDF);]) 190: (item [optionally, ,(ploticus [Ploticus]) to produce pie charts 191: (alternatively, ,(lout [Lout]) can be used for that purpose);]) 192: (item [optionally, ,(guile-lib [Guile-Lib]) to be able to use the 193: ,(ref :skribe %user-sui :ident "rss2-syntax" :text [RSS-2 reader]).]))])) 194: 195: (chapter :title [Documentation] :number #f :file #f ;; FIXME: Do it! 196: :ident "documentation" 197: 198: (p [The user manual is available in the following formats: 199: 200: ,(itemize 201: (item (ref :text [HTML] :url "doc/user.html")) 202: (item (ref :text [PDF] :url "doc/user.pdf")))])) 203: 204: (chapter :title [Example] :number #f :file #f 205: :ident "example" 206: 207: (p [Here is a live example: the source code of this web page, 208: colored using Skribilo's computer program coloring features.]) 209: 210: (mark "self") 211: (tt (prog 212: (source :language skribe 213: :file "index.skb")))) 214: 215: (chapter :title [Mailing List] :number #f :file #f 216: :ident "mailing-list" 217: 218: (p [If you want to complain or tell how bright and shining your 219: life has become since you discovered Skribilo, then go ahead and 220: subscribe to the ,(skribilo-ml [,(tt [skribilo-users]) mailing list])! 221: If you want to suggest improvements, that's also where they should go!])) 222: 223: (chapter :title [Development] :number #f :file #f 224: :ident "development" 225: 226: (p [Development is done using the ,(git [Git]) distributed 227: revision control system. You can fetch a copy of the source code 228: repository using the following incantation: 229: 230: ,(frame :class "code-excerpt" :border #f :margin #f 231: (code [git clone git://git.sv.gnu.org/skribilo.git])) 232: 233: You can then happily hack on your side and eventually promote your 234: changes ,(ref :ident "mailing-list" :text [on the mailing-list]).]) 235: 236: (p [The repository can also be ,(ref :url 237: "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=summary" :text 238: [browsed on-line]).]) 239: 240: (p [A tentative list of milestones and to-do items is in the ,(ref 241: :url "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=blob;f=TODO" :text 242: [,(tt [TODO]) file]).])) 243: 244: (chapter :title [History] :number #f :file #f 245: :ident "history" 246: 247: (p [Skribilo is a direct descendant of ,(skribe* [Skribe]), a 248: document production tool written by Manuel Serrano for ,(bigloo 249: [Bigloo]) and ported to ,(stklos [STkLos]) by Érick Gallesio. 250: Development of ,(skribe* [Skribe]) started around 2003 as a successor of 251: Manuel's previous documentation system named ,(scribe [Scribe]).]) 252: 253: (p [Skribilo derives from Skribe 1.2d but it differs in a number 254: of ways: 255: 256: ,(itemize 257: (item [It contains new packages (pie charts, equation formatting) 258: and a new engine (the ,(lout [Lout]) engine).]) 259: (item [Symmetrically to the notion of engine (rendering back-ends), 260: Skribilo has the concept of ,(emph [readers]). A reader is the part 261: that reads an input document in a specific syntax and returns an 262: abstract syntax tree understandable by the core mechanisms. Skribilo 263: currently comes with two readers: one that implements the standard 264: Skribe syntax, and one that reads free form text with annotations 265: similar to those found in ,(emacs/outline [Emacs' outline mode]).]) 266: (item [It's been reworked to be used as a framework or library, 267: rather than as a stand-alone program. As a result, the logical 268: separation of modules has been improved, the globally shared state has 269: been significantly reduced, and ,(ref :url 270: "http://srfi.schemers.org/srfi-35/srfi-35.html" :text [SRFI-35 271: exceptions]) are used rather than plain ,(tt [error]) or ,(tt [exit]) 272: calls. The idea is to expose ,(emph [all the core mechanisms]) of 273: Skribilo to the user, thereby blurring the border between the user 274: program or document and the core of the system.]) 275: (item [Although Skribilo only runs on ,(guile [GNU Guile]), care was 276: taken to use mostly portable APIs (,(ref :url "http://srfi.schemers.org/" 277: :text [SRFIs])) so that the code is intelligible to most Scheme 278: programmers.]))])) 279: 280: (chapter :title [Related Links] :number #f :file #f 281: :ident "related" 282: 283: (itemize 284: (item [,(skribe* [Skribe]), the father of Skribilo. Its 285: predecessor is ,(scribe [Scribe]) and their goals were expressed in 286: ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Scribe/doc/scribe.html" 287: :text (it [the Scribe white paper])) by Manuel Serrano and Érick 288: Gallesio. Their 2005 Journal of Functional Programming (JFP) article 289: entitled ,(ref :url 290: "http://www-sop.inria.fr/mimosa/Manuel.Serrano/publi/jfp05/article.html" 291: :text (it [Skribe: A Functional Authoring Language])) provides further 292: insight.]) 293: (item [,(ref :url 294: "http://docs.racket-lang.org/scribble/index.html" :text [Scribble]), the 295: documentation system of Racket, is similar in spirit to Skribilo/Skribe. 296: It has ,(ref :url 297: "http://docs.racket-lang.org/scribble/getting-started.html" :text 298: [different syntax]) and ,(ref :url 299: "http://docs.racket-lang.org/scribble/base.html" :text [markup]). ,(ref 300: :skribe %user-sui :ident "engines" :text [Like Skribilo]), it supports 301: several ,(ref :url "http://docs.racket-lang.org/scribble/renderer.html" 302: :text "renderers"). It does not seem to provide an API to work with the 303: AST, and things like ,(ref :url 304: "http://git.savannah.gnu.org/cgit/skribilo.git/tree/src/guile/skribilo/resolve.scm" 305: :text (tt [resolve])).]) 306: (item [Andy Wingo's ,(ref :url 307: "http://www.gnu.org/software/guile/manual/html_node/texinfo.html" :text [STexi]) (,(ref 308: :text [Texinfo] :url "http://www.gnu.org/software/texinfo/") as 309: S-expressions), available in ,(guile [Guile 2.x]). The 310: ,(ref :text (tt [fold-layout]) :url 311: "http://www.gnu.org/software/guile/manual/html_node/sxml-fold.html") 312: operator provides an interesting, purely functional approach to 313: documentation transformation (not unlike XSLT, but with a real 314: programming language).]) 315: (item [The ,(ref :url "http://www.jstatsoft.org/v46/i03/paper" 316: :text [Org-Mode paper about reproducible research]) introduces ideas 317: that can be usefully implemented in Skribilo: a Skribilo document can 318: embed executable code, and run it to include its results at compilation 319: time.]) 320: (item [,(ref :url "http://okmij.org/ftp/Scheme/SXML.html" 321: :text [SXML]), XML as S-expressions. Oleg Kiselyov's discussion of 322: ,(ref :text [implementation strategies for a purely functional SXML 323: tree] :url "http://okmij.org/ftp/Scheme/parent-pointers.txt") is a good 324: source of inspiration.]) 325: (item [,(ref :url 326: "http://www.ccs.neu.edu/home/dorai/mistie/mistie.html" :text 327: [Mistie]), a “programmable filter” in Scheme (for MzScheme) that 328: allows the definition of filters from one markup language to another 329: one.]) 330: (item [,(ref :url "http://www.it.usyd.edu.au/~jeff/nonpareil/" 331: :text [Nonpareil]), Jeff Kingston's much anticipated successor to ,(lout 332: [Lout]), both being purely functional document formatting 333: systems/languages. Although Nonpareil is more ambitious than Skribilo, 334: the document entitled ,(it [Nonpareil Document Formatting]) shows 335: interesting similarities between both systems: separation of document 336: syntax and programming syntax (“readers” and Scheme in Skribilo), 337: representation of document structure separated from the representation 338: of a laid out document (Nonpareil's ,(it [doc]) objects resemble 339: Skribilo's ,(tt [<ast>]) objects; its ,(it [scene]) objects have no 340: equivalent in Skribilo since Skribilo doesn't address text layout by 341: itself). It also includes interesting discussions about text selection 342: and document traversal (Nonpareil's ,(it [doc]) objects have no parent 343: pointers, unlike Skribilo's ,(tt [<ast>])).]) 344: (item [Good ol' ,(ref :url 345: "http://www.gnu.org/software/texinfo/" :text [GNU Texinfo]) abstracts 346: the various kinds of back-ends very well (in particular its 347: cross-reference-related commands).]) 348: (item [,(ref :url 349: "http://www.coyotos.org/docs/osdoc/osdoc.html" :text [OSDoc]), a 350: derivative of ,(ref :url "http://docbook.org/" :text [Docbook]).]) 351: (item [Systems that produce documents in various formats from 352: (almost) markup-less input text: ,(ref :url "http://txt2tags.sf.net/" 353: :text [txt2tags]), ,(ref :url "http://www.maplefish.com/todd/aft.html" 354: :text [AFT]), ,(ref :url "http://os.inf.tu-dresden.de/~nf2/files/GOSH/" 355: :text [GOSH]), ,(ref :url "http://mercnet.pt/plaindoc/pd.html" :text 356: [PlainDoc]), ,(ref :url "http://www.methods.co.nz/asciidoc/" :text 357: [AsciiDoc]), ,(ref :url "http://docutils.sourceforge.net/rst.html" :text 358: [reStructured Text (RST)]), ,(ref :url 359: "http://www.t3x.org/attic/index.html#sd" :text [SD]), ,(ref :url 360: "http://triptico.com/software/grutatxt.html" :text [Grutatxt]), and many 361: others.]))) 362: 363: (chapter :title [The Name] :number #f :file #f 364: :ident "name" 365: 366: (p [Skribilo is an ,(wikipedia/esperanto [Esperanto]) noun, which 367: literally means ,(ref :url 368: "http://www.reta-vortaro.de/revo/art/skrib.html#skrib.0ilo" :text [“a 369: tool to write”]) (prefix “,(ref :url 370: "http://www.reta-vortaro.de/revo/art/skrib.html" :text [skrib])” 371: relates to writing, while suffix “,(ref :text [-ilo] :url 372: "http://www.reta-vortaro.de/revo/art/il.html")” designates a tool). 373: Interestingly, “,(skribe* [skribe])”, which is the name of the tool 374: Skribilo is based on, is an adverb meaning “writing” in 375: ,(wikipedia/esperanto [Esperanto]).]))) 376: 377: 378: ;;; Local Variables: 379: ;;; coding: utf-8 380: ;;; ispell-local-dictionary: "american" 381: ;;; indent-tabs-mode: nil 382: ;;; End:
If you want to complain or tell how bright and shining your life has become since you discovered Skribilo, then go ahead and subscribe to the skribilo-users mailing list! If you want to suggest improvements, that's also where they should go!
Development is done using the Git distributed revision control system. You can fetch a copy of the source code repository using the following incantation:
git clone git://git.sv.gnu.org/skribilo.gitThe repository can also be browsed on-line.
A tentative list of milestones and to-do items is in the TODO file.
Skribilo is a direct descendant of Skribe, a document production tool written by Manuel Serrano for Bigloo and ported to STkLos by Érick Gallesio. Development of Skribe started around 2003 as a successor of Manuel's previous documentation system named Scribe.
Skribilo derives from Skribe 1.2d but it differs in a number of ways:
Skribilo is an Esperanto noun, which literally means “a tool to write” (prefix “ skrib” relates to writing, while suffix “ -ilo” designates a tool). Interestingly, “ skribe”, which is the name of the tool Skribilo is based on, is an adverb meaning “writing” in Esperanto.