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 1.8 or 2.0 as the underlying Scheme implementation.

Features


Availability

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:


Documentation

The user manual is available in the following formats:


Example

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 "skribilo.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]) 1.8 or
143: 2.0 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 (when using Guile 2.0).])
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]) 2.0.*, or 1.8.3 or later;])
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.0]).  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:

Mailing List

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

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
You can then happily hack on your side and eventually promote your changes on the mailing-list.

The repository can also be browsed on-line.

A tentative list of milestones and to-do items is in the TODO file.


History

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:


Related Links


The Name

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.


(made with skribilo)