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])), or using free form, markup-less text and 156: conventions similar to those used in ,(ref :skribe %user-sui :ident 157: "outline-syntax" :text [Emacs' outline mode]), or from an ,(ref :skribe 158: %user-sui :ident "rss2-syntax" :text [RSS,(~)2 feed]).]) 159: (item [Packages are available to produce: ,(ref :skribe 160: %user-sui :ident "slides" :text [slides]) (overhead transparencies), 161: ,(ref :skribe %user-sui :ident "pie-charts" :text [pie charts]), ,(ref 162: :skribe %user-sui :ident "equations" :text [equation formatting]), ,(ref 163: :skribe %user-sui :ident "programs" :text [syntax highlighting of 164: computer programs]), and others.]) 165: (item [,(ref :skribe %user-sui :chapter "Bibliographies" :text 166: [Bibliography management])—i.e., BibTeX on steroids thanks to the 167: programmability brought by ,(scheme [Scheme]).]) 168: (item [Unicode support.]) 169: (item [Use of a proper module system (that of ,(guile 170: [Guile])) rather than ,(tt [load])-style interactions.]) 171: (item [And much more! :-)]))) 172: 173: (chapter :title [Availability] :number #f :file #f 174: :ident "download" 175: 176: (p [Releases are available from the ,(ref :text [download area] 177: :url "http://dl.sv.nongnu.org/releases/skribilo/").]) 178: 179: (p [Skribilo is distributed under the terms of the ,(gpl [GNU 180: General Public Licence]), version 3 or later. To use Skribilo, 181: you need the following pieces of software: 182: 183: ,(itemize 184: (item [,(guile [GNU Guile]) 3.0, 2.2.*, or 2.0.*;]) 185: (item [,(ref :url "http://www.nongnu.org/guile-reader/" 186: :text [Guile-Reader]) 0.6 or later;]) 187: (item [either ,(lout [Lout]) (3.31 or later), ,(latex [LaTeX]), or 188: ,(context [ConTeXt]) to produce hard copies (PostScript/PDF);]) 189: (item [optionally, ,(ploticus [Ploticus]) to produce pie charts 190: (alternatively, ,(lout [Lout]) can be used for that purpose);]) 191: (item [optionally, ,(guile-lib [Guile-Lib]) to be able to use the 192: ,(ref :skribe %user-sui :ident "rss2-syntax" :text [RSS-2 reader]).]))])) 193: 194: (chapter :title [Documentation] :number #f :file #f ;; FIXME: Do it! 195: :ident "documentation" 196: 197: (p [The user manual is available in the following formats: 198: 199: ,(itemize 200: (item (ref :text [HTML] :url "doc/user.html")) 201: (item (ref :text [PDF] :url "doc/user.pdf")))])) 202: 203: (chapter :title [Example] :number #f :file #f 204: :ident "example" 205: 206: (p [Here is a live example: the source code of this web page, 207: colored using Skribilo's computer program coloring features.]) 208: 209: (mark "self") 210: (tt (prog 211: (source :language skribe 212: :file "index.skb")))) 213: 214: (chapter :title [Mailing List] :number #f :file #f 215: :ident "mailing-list" 216: 217: (p [If you want to complain or tell how bright and shining your 218: life has become since you discovered Skribilo, then go ahead and 219: subscribe to the ,(skribilo-ml [,(tt [skribilo-users]) mailing list])! 220: If you want to suggest improvements, that's also where they should go!])) 221: 222: (chapter :title [Development] :number #f :file #f 223: :ident "development" 224: 225: (p [Development is done using the ,(git [Git]) distributed 226: revision control system. You can fetch a copy of the source code 227: repository using the following incantation: 228: 229: ,(frame :class "code-excerpt" :border #f :margin #f 230: (code [git clone git://git.sv.gnu.org/skribilo.git])) 231: 232: You can then happily hack on your side and eventually promote your 233: changes ,(ref :ident "mailing-list" :text [on the mailing-list]).]) 234: 235: (p [The repository can also be ,(ref :url 236: "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=summary" :text 237: [browsed on-line]).]) 238: 239: (p [A tentative list of milestones and to-do items is in the ,(ref 240: :url "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=blob;f=TODO" :text 241: [,(tt [TODO]) file]).])) 242: 243: (chapter :title [History] :number #f :file #f 244: :ident "history" 245: 246: (p [Skribilo is a direct descendant of ,(skribe* [Skribe]), a 247: document production tool written by Manuel Serrano for ,(bigloo 248: [Bigloo]) and ported to ,(stklos [STkLos]) by Érick Gallesio. 249: Development of ,(skribe* [Skribe]) started around 2003 as a successor of 250: Manuel's previous documentation system named ,(scribe [Scribe]).]) 251: 252: (p [Skribilo derives from Skribe 1.2d but it differs in a number 253: of ways: 254: 255: ,(itemize 256: (item [It contains new packages (pie charts, equation formatting) 257: and a new engine (the ,(lout [Lout]) engine).]) 258: (item [Symmetrically to the notion of engine (rendering back-ends), 259: Skribilo has the concept of ,(emph [readers]). A reader is the part 260: that reads an input document in a specific syntax and returns an 261: abstract syntax tree understandable by the core mechanisms. Skribilo 262: currently comes with two readers: one that implements the standard 263: Skribe syntax, and one that reads free form text with annotations 264: similar to those found in ,(emacs/outline [Emacs' outline mode]).]) 265: (item [It's been reworked to be used as a framework or library, 266: rather than as a stand-alone program. As a result, the logical 267: separation of modules has been improved, the globally shared state has 268: been significantly reduced, and ,(ref :url 269: "http://srfi.schemers.org/srfi-35/srfi-35.html" :text [SRFI-35 270: exceptions]) are used rather than plain ,(tt [error]) or ,(tt [exit]) 271: calls. The idea is to expose ,(emph [all the core mechanisms]) of 272: Skribilo to the user, thereby blurring the border between the user 273: program or document and the core of the system.]) 274: (item [Although Skribilo only runs on ,(guile [GNU Guile]), care was 275: taken to use mostly portable APIs (,(ref :url "http://srfi.schemers.org/" 276: :text [SRFIs])) so that the code is intelligible to most Scheme 277: programmers.]))])) 278: 279: (chapter :title [Related Links] :number #f :file #f 280: :ident "related" 281: 282: (itemize 283: (item [,(skribe* [Skribe]), the father of Skribilo. Its 284: predecessor is ,(scribe [Scribe]) and their goals were expressed in 285: ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Scribe/doc/scribe.html" 286: :text (it [the Scribe white paper])) by Manuel Serrano and Érick 287: Gallesio. Their 2005 Journal of Functional Programming (JFP) article 288: entitled ,(ref :url 289: "http://www-sop.inria.fr/mimosa/Manuel.Serrano/publi/jfp05/article.html" 290: :text (it [Skribe: A Functional Authoring Language])) provides further 291: insight.]) 292: (item [,(ref :url 293: "http://docs.racket-lang.org/scribble/index.html" :text [Scribble]), the 294: documentation system of Racket, is similar in spirit to Skribilo/Skribe. 295: It has ,(ref :url 296: "http://docs.racket-lang.org/scribble/getting-started.html" :text 297: [different syntax]) and ,(ref :url 298: "http://docs.racket-lang.org/scribble/base.html" :text [markup]). ,(ref 299: :skribe %user-sui :ident "engines" :text [Like Skribilo]), it supports 300: several ,(ref :url "http://docs.racket-lang.org/scribble/renderer.html" 301: :text "renderers"). It does not seem to provide an API to work with the 302: AST, and things like ,(ref :url 303: "http://git.savannah.gnu.org/cgit/skribilo.git/tree/src/guile/skribilo/resolve.scm" 304: :text (tt [resolve])).]) 305: (item [Andy Wingo's ,(ref :url 306: "http://www.gnu.org/software/guile/manual/html_node/texinfo.html" :text [STexi]) (,(ref 307: :text [Texinfo] :url "http://www.gnu.org/software/texinfo/") as 308: S-expressions), available in ,(guile [Guile 2.x]). The 309: ,(ref :text (tt [fold-layout]) :url 310: "http://www.gnu.org/software/guile/manual/html_node/sxml-fold.html") 311: operator provides an interesting, purely functional approach to 312: documentation transformation (not unlike XSLT, but with a real 313: programming language).]) 314: (item [The ,(ref :url "http://www.jstatsoft.org/v46/i03/paper" 315: :text [Org-Mode paper about reproducible research]) introduces ideas 316: that can be usefully implemented in Skribilo: a Skribilo document can 317: embed executable code, and run it to include its results at compilation 318: time.]) 319: (item [,(ref :url "http://okmij.org/ftp/Scheme/SXML.html" 320: :text [SXML]), XML as S-expressions. Oleg Kiselyov's discussion of 321: ,(ref :text [implementation strategies for a purely functional SXML 322: tree] :url "http://okmij.org/ftp/Scheme/parent-pointers.txt") is a good 323: source of inspiration.]) 324: (item [,(ref :url 325: "http://www.ccs.neu.edu/home/dorai/mistie/mistie.html" :text 326: [Mistie]), a “programmable filter” in Scheme (for MzScheme) that 327: allows the definition of filters from one markup language to another 328: one.]) 329: (item [,(ref :url "http://www.it.usyd.edu.au/~jeff/nonpareil/" 330: :text [Nonpareil]), Jeff Kingston's much anticipated successor to ,(lout 331: [Lout]), both being purely functional document formatting 332: systems/languages. Although Nonpareil is more ambitious than Skribilo, 333: the document entitled ,(it [Nonpareil Document Formatting]) shows 334: interesting similarities between both systems: separation of document 335: syntax and programming syntax (“readers” and Scheme in Skribilo), 336: representation of document structure separated from the representation 337: of a laid out document (Nonpareil's ,(it [doc]) objects resemble 338: Skribilo's ,(tt [<ast>]) objects; its ,(it [scene]) objects have no 339: equivalent in Skribilo since Skribilo doesn't address text layout by 340: itself). It also includes interesting discussions about text selection 341: and document traversal (Nonpareil's ,(it [doc]) objects have no parent 342: pointers, unlike Skribilo's ,(tt [<ast>])).]) 343: (item [Good ol' ,(ref :url 344: "http://www.gnu.org/software/texinfo/" :text [GNU Texinfo]) abstracts 345: the various kinds of back-ends very well (in particular its 346: cross-reference-related commands).]) 347: (item [,(ref :url 348: "http://www.coyotos.org/docs/osdoc/osdoc.html" :text [OSDoc]), a 349: derivative of ,(ref :url "http://docbook.org/" :text [Docbook]).]) 350: (item [Systems that produce documents in various formats from 351: (almost) markup-less input text: ,(ref :url "http://txt2tags.sf.net/" 352: :text [txt2tags]), ,(ref :url "http://www.maplefish.com/todd/aft.html" 353: :text [AFT]), ,(ref :url "http://os.inf.tu-dresden.de/~nf2/files/GOSH/" 354: :text [GOSH]), ,(ref :url "http://mercnet.pt/plaindoc/pd.html" :text 355: [PlainDoc]), ,(ref :url "http://www.methods.co.nz/asciidoc/" :text 356: [AsciiDoc]), ,(ref :url "http://docutils.sourceforge.net/rst.html" :text 357: [reStructured Text (RST)]), ,(ref :url 358: "http://www.t3x.org/attic/index.html#sd" :text [SD]), ,(ref :url 359: "http://triptico.com/software/grutatxt.html" :text [Grutatxt]), and many 360: others.]))) 361: 362: (chapter :title [The Name] :number #f :file #f 363: :ident "name" 364: 365: (p [Skribilo is an ,(wikipedia/esperanto [Esperanto]) noun, which 366: literally means ,(ref :url 367: "http://www.reta-vortaro.de/revo/art/skrib.html#skrib.0ilo" :text [“a 368: tool to write”]) (prefix “,(ref :url 369: "http://www.reta-vortaro.de/revo/art/skrib.html" :text [skrib])” 370: relates to writing, while suffix “,(ref :text [-ilo] :url 371: "http://www.reta-vortaro.de/revo/art/il.html")” designates a tool). 372: Interestingly, “,(skribe* [skribe])”, which is the name of the tool 373: Skribilo is based on, is an adverb meaning “writing” in 374: ,(wikipedia/esperanto [Esperanto]).]))) 375: 376: 377: ;;; Local Variables: 378: ;;; coding: utf-8 379: ;;; ispell-local-dictionary: "american" 380: ;;; indent-tabs-mode: nil 381: ;;; 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.git |
The 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.