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

Mailing List

If you want to complain or tell how bright and shinning 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)