Skribilo: The Ultimate Document Programming Framework

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 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. Skribilo uses GNU Guile 1.8 as the underlying Scheme implementation.

Features

  • Output in a variety of formats: HTML, XML, Lout, LaTeX, ConTeXt.
  • Input using Skribe's markup (see this example) or using free form, markup-less text and conventions similar to those used in Emacs' outline mode.
  • Packages are available to produce: slides (overhead transparencies), pie charts, equation formatting, syntax highlighting of computer programs, and others.
  • Bibliography management, i.e., BibTeX on steroids thanks to the programmability brought by Scheme.
  • Use of a proper module system (currently that of Guile, eventually that of R6RS) rather than load-style interactions.
  • And much more! :-)

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: (define (html-left-margin n e)
  6:   ;; Create the left margin of the HTML page being output.  N is the
  7:   ;; node being output (e.g., a chapter) and E is an engine.
  8:   (let* ((doc (ast-document n))
  9:          (chapters (search-down (lambda (n)
 10:                                   (is-markup? n 'chapter))
 11:                                 doc)))
 12:     (table :class "left-margin-menu" :frame 'none
 13:        (cons (tr (td (ref :mark "intro" :text "Introduction")))
 14:              (map (lambda (chapter)
 15:                     (tr (td (ref :handle (handle chapter)
 16:                                :text (markup-option chapter :title)))))
 17:                   chapters)))))
 18: 
 19: 
 20: (let ((html (find-engine 'html)))
 21:   ;; Customizing the HTML output...
 22:   (if (engine? html)
 23:       (begin
 24:         (engine-custom-set! html 'left-margin html-left-margin)
 25:         (engine-custom-set! html 'css "skribilo.css"))))
 26: 
 27: 
 28: 
 29: ;;;
 30: ;;; List of useful URLs.
 31: ;;;
 32: 
 33: (define (wikipedia/markup . body)
 34:   (ref :url "http://en.wikipedia.org/wiki/Markup_language"
 35:      :text body))
 36: 
 37: (define (wikipedia/markup-less . body)
 38:   (ref :url "http://en.wikipedia.org/wiki/Lightweight_markup_language"
 39:      :text body))
 40: 
 41: (define (scheme . body)
 42:   (ref :url "http://schemers.org/" :text body))
 43: 
 44: (define (guile . body)
 45:   (ref :url "http://www.gnu.org/software/guile/guile.html" :text body))
 46: 
 47: (define (r6rs . body)
 48:   (ref :url "http://r6rs.org/" :text body))
 49: 
 50: (define (latex . body)
 51:   (ref :url "http://www.latex-project.org/" :text body))
 52: 
 53: (define (lout . body)
 54:   (ref :url "http://lout.sf.net/" :text body))
 55: 
 56: (define (ploticus . body)
 57:   (ref :url "http://ploticus.sf.net/" :text body))
 58: 
 59: (define (guile-lib . body)
 60:   (ref :url "http://home.gna.org/guile-lib/" :text body))
 61: 
 62: (define (freedom . body)
 63:   (ref :url "http://www.gnu.org/philosophy/free-sw.html" :text body))
 64: 
 65: (define (gpl . body)
 66:   (ref :url "http://www.gnu.org/licenses/gpl.html" :text body))
 67: 
 68: (define (emacs/outline . body)
 69:   (ref :url "http://www.gnu.org/software/emacs/manual/html_node/Outline-Format.html"
 70:      :text body))
 71: 
 72: (define (skribilo-ml . body)
 73:   (ref :url "http://lists.nongnu.org/mailman/listinfo/skribilo-users"
 74:      :text body))
 75: 
 76: (define (arch . body)
 77:   (ref :url "http://www.gnu.org/software/gnu-arch/" :text body))
 78: 
 79: (define (skribe* . body)
 80:   (ref :url "http://www-sop.inria.fr/mimosa/fp/Skribe/" :text body))
 81: 
 82: (define (scribe . body)
 83:   (ref :url "http://www-sop.inria.fr/mimosa/fp/Scribe/" :text body))
 84: 
 85: (define (bigloo . body)
 86:   (ref :url "http://www-sop.inria.fr/mimosa/fp/Bigloo/" :text body))
 87: 
 88: (define (stklos . body)
 89:   (ref :url "http://www.stklos.org/" :text body))
 90: 
 91: 
 92: ;;;
 93: ;;; The website.
 94: ;;;
 95: 
 96: (document :title [Skribilo: The Ultimate Document Programming Framework]
 97:    :author #f
 98:    :keywords '("Skribilo" "document programming"
 99:                "document formatting" "authoring"
100:                "Scheme" "Guile"
101:                "Skribe" "Lout" "LaTeX" "HTML")
102: 
103:    (mark "intro")
104: 
105:    (p [Skribilo is a ,(freedom [free]) document production tool that
106: takes a structured document representation as its input and renders that
107: document in a variety of output formats: HTML for on-line browsing, and
108: ,(lout [Lout]) and ,(latex [LaTeX]) for high-quality hard copies.])
109: 
110:    (p [The input document can use Skribilo's ,(wikipedia/markup [markup
111: language]) to provide information about the document's structure, which
112: is similar to HTML or ,(latex [LaTeX]) and does not require expertise.
113: Alternatively, it can use a simpler, ``,(wikipedia/markup-less
114: [markup-less])'' format that borrows from ,(emacs/outline [Emacs'
115: outline mode]) and from other conventions used in emails, Usenet and
116: text.])
117: 
118:    (p [Last but not least, Skribilo can be thought of as a complete
119: ,(emph [document programming framework]) for the ,(scheme [Scheme
120: programming language]) that may be used to automate a variety of
121: document generation tasks.  Skribilo uses ,(guile [GNU Guile]) 1.8 as
122: the underlying Scheme implementation.])
123: 
124: 
125:    (chapter :title [Features] :number #f :file #f
126: 
127:       (itemize
128:          (item [Output in a variety of formats: HTML, XML, ,(lout
129: [Lout]), ,(latex [LaTeX]), ConTeXt.])
130:          (item [Input using ,(skribe* [Skribe])'s markup (see
131: ,(ref :mark "self" :text [this example])) or using free form,
132: markup-less text and conventions similar to those used in
133: ,(emacs/outline [Emacs' outline mode]).])
134:          (item [Packages are available to produce: slides (overhead
135: transparencies), pie charts, equation formatting, syntax highlighting of
136: computer programs, and others.])
137:          (item [Bibliography management, i.e., BibTeX on steroids thanks
138: to the programmability brought by ,(scheme [Scheme]).])
139:          (item [Use of a proper module system (currently that of ,(guile
140: [Guile]), eventually that of ,(r6rs [R6RS])) rather than ,(tt
141: [load])-style interactions.])
142:          (item [And much more!  :-)])))
143: 
144:    (chapter :title [Example] :number #f :file #f
145: 
146:       (p [Here is a live example: the source code of this web page,
147: colored using Skribilo's computer program coloring features.])
148: 
149:       (mark "self")
150:       (tt (prog
151:               (source :language skribe
152:                  :file "index.skb"))))
153: 
154:    (chapter :title [Documentation] :number #f :file #f ;; FIXME: Do it!
155: 
156:       (p [Coming real soon...]))
157: 
158:    (chapter :title [Availability] :number #f :file #f
159: 
160:       (p [Skribilo is available under the ,(gpl [GNU General Public
161: Licence]), version 2 or later.  In order to use Skribilo, you need the
162: following pieces of software:
163: 
164: ,(itemize
165:     (item [,(guile [GNU Guile]) 1.8.0 or later;])
166:     (item [,(ref :url "http://savannah.gnu.org/projects/guile-reader/"
167:                :text [Guile-reader]) 0.3 or later;])
168:     (item [a recent version of ,(guile-lib [Guile-lib]);])
169:     (item [either ,(lout [Lout]) 3.31 or ,(latex [LaTeX]) to produce
170: hard copies (PostScript/PDF);])
171:     (item [optionally, ,(ploticus [Ploticus]) to produce pie charts
172: (alternatively, ,(lout [Lout]) can be used for that purpose.]))])
173: 
174:       (p [There has been no public release yet.]))
175: 
176:    (chapter :title [Mailing List] :number #f :file #f
177:       :ident "mailing-list"
178: 
179:       (p [If you want to complain or tell how bright and shinning your
180: life has become since you discovered Skribilo, then go ahead and
181: subscribe to the ,(skribilo-ml [,(tt [skribilo-users]) mailing list])!
182: If you want to suggest improvements, that's also where they should go!]))
183: 
184:    (chapter :title [Development] :number #f :file #f
185: 
186:       (p [Development is done using the good ol' ,(arch [GNU Arch])
187: distributed revision control system.  You can fetch the latest version
188: of the main branch using the following incantations:
189: 
190: ,(frame :class "code-excerpt" :border #f :margin #f
191:     (code [
192: $ tla register-archive http://arch.sv.gnu.org/archives/skribilo/2006/
193: ,(linebreak)
194: $ tla get skribilo--devo--1.2  my-skribilo-directory
195: ]))
196: 
197: You can then happily hack on your side and eventually promote your
198: changes ,(ref :ident "mailing-list" :text [on the mailing-list]).]))
199: 
200:    (chapter :title [History] :number #f :file #f
201: 
202:       (p [Skribilo is a direct descendant of ,(skribe* [Skribe]), a
203: document production tool written by Manuel Serrano for ,(bigloo
204: [Bigloo]) and ported to ,(stklos [STkLos]) by Erick Gallesio.
205: Development of ,(skribe* [Skribe]) started around 2003 as a successor of
206: Manuel's previous documentation system named ,(scribe [Scribe]).])
207: 
208:       (p [Skribilo derives from Skribe 1.2d but it differs in a number
209: of ways:
210: 
211: ,(itemize
212:     (item [It contains new packages (pie charts, equation formatting)
213: and a new engine (the ,(lout [Lout]) engine).])
214:     (item [Symmetrically to the notion of engine (rendering back-ends),
215: Skribilo has the concept of ,(emph [readers]).  A reader is the part
216: that reads an input document in a specific syntax and returns an
217: abstract syntax tree understandable by the core mechanisms.  Skribilo
218: currently comes with two readers: one that implements the standard
219: Skribe syntax, and one that reads free form text with annotations
220: similar to those found in ,(emacs/outline [Emacs' outline mode]).])
221:     (item [It's been reworked to be used as a framework or library,
222: rather than as a stand-alone program.  As a result, the logical
223: separation of modules has been improved, the globally shared state has
224: been significantly reduced, and ,(ref :url
225: "http://srfi.schemers.org/srfi-35/srfi-35.html" :text [SRFI-35
226: exceptions]) are used rather than plain ,(tt [error]) or ,(tt [exit])
227: calls.  The idea is to expose ,(emph [all the core mechanisms]) of
228: Skribilo to the user, thereby blurring the border between the user
229: program or document and the core of the system.])
230:     (item [Although Skribilo only runs on ,(guile [GNU Guile]), care was
231: taken to use mostly portable APIs (,(ref :url "http://srfi.schemers.org/"
232: :text [SRFIs])) so that the code is intelligible to most Scheme
233: programmers.  Following ,(r6rs [R6RS]) is also an objective for the near
234: future.]))]))
235: 
236:     (chapter :title [Related Links] :number #f :file #f
237: 
238:        (itemize
239:           (item [,(skribe* [Skribe]), the father of Skribilo.  Its
240: predecessor is ,(scribe [Scribe]) and their goals were expressed in
241: ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Scribe/doc/scribe.html"
242: :text [the Scribe white paper]) by Manuel Serrano and Erick Gallesio.])
243:           (item [Andy Wingo's ,(ref :url
244: "http://wingolog.org/software/guile-lib/texinfo/" :text [STexi]) (,(ref
245: :text [Texinfo] :url "http://www.gnu.org/software/texinfo/") as
246: S-expressions), available in ,(guile-lib [Guile-lib]).])
247:           (item [,(ref :url "http://okmij.org/ftp/Scheme/SXML.html"
248: :text [SXML]), XML as S-expressions.])
249:            (item [,(ref :url "http://www.it.usyd.edu.au/~jeff/nonpareil/"
250: :text [Nonpareil]), Jeff Kingston's much anticipated successor to ,(lout
251: [Lout]).  Although Nonpareil is more ambitious than Skribilo, the
252: document entitled ,(it [Nonpareil Document Formatting]) shows
253: interesting similarities between both systems: separation of document
254: syntax and programming syntax (``readers'' and Scheme in Skribilo),
255: representation of document structure separated from the representation
256: of a laid out document (Nonpareil's ,(it [doc]) objects resemble
257: Skribilo's ,(tt [<ast>]) objects; its ,(it [scene]) objects have no
258: equivalent in Skribilo since Skribilo doesn't address text layout by
259: itself).  It also includes interesting discussions about text selection
260: and document traversal (Nonpareil's ,(it [doc]) objects have no parent
261: pointers, unlike Skribilo's ,(tt [<ast>])).])
262:            (item [Good ol' ,(ref :url
263: "http://www.gnu.org/software/texinfo/" :text [GNU Texinfo]) abstracts
264: the various kinds of back-ends very well (in particular its
265: cross-reference-related commands).])
266:           (item [,(ref :url
267: "http://www.coyotos.org/docs/osdoc/osdoc.html" :text [OSDoc]), a
268: derivative of ,(ref :url "http://docbook.org/" :text [Docbook]).])
269:           (item [Systems that produce documents in various formats from
270: (almost) markup-less input text: ,(ref :url "http://txt2tags.sf.net/"
271: :text [txt2tags]), ,(ref :url
272: "http://os.inf.tu-dresden.de/~nf2/files/GOSH/" :text [GOSH]), ,(ref :url
273: "http://mercnet.pt/plaindoc/pd.html" :text [PlainDoc]), and many
274: others.]))))
275: 
276: 
277: ;;; Local Variables:
278: ;;; coding: latin-1
279: ;;; ispell-local-dictionary: "american"
280: ;;; End:
281: 
282: ;;; arch-tag: fd51e0ce-d99f-4b70-8b92-9afbcfcf8855

Documentation

Coming real soon...


Availability

Skribilo is available under the GNU General Public Licence, version 2 or later. In order to use Skribilo, you need the following pieces of software:

There has been no public release yet.


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 good ol' GNU Arch distributed revision control system. You can fetch the latest version of the main branch using the following incantations:
$ tla register-archive http://arch.sv.gnu.org/archives/skribilo/2006/
$ tla get skribilo--devo--1.2 my-skribilo-directory
You can then happily hack on your side and eventually promote your changes on the mailing-list.


History

Skribilo is a direct descendant of Skribe, a document production tool written by Manuel Serrano for Bigloo and ported to STkLos by Erick 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:

  • It contains new packages (pie charts, equation formatting) and a new engine (the Lout engine).
  • Symmetrically to the notion of engine (rendering back-ends), Skribilo has the concept of readers. A reader is the part that reads an input document in a specific syntax and returns an abstract syntax tree understandable by the core mechanisms. Skribilo currently comes with two readers: one that implements the standard Skribe syntax, and one that reads free form text with annotations similar to those found in Emacs' outline mode.
  • It's been reworked to be used as a framework or library, rather than as a stand-alone program. As a result, the logical separation of modules has been improved, the globally shared state has been significantly reduced, and SRFI-35 exceptions are used rather than plain error or exit calls. The idea is to expose all the core mechanisms of Skribilo to the user, thereby blurring the border between the user program or document and the core of the system.
  • Although Skribilo only runs on GNU Guile, care was taken to use mostly portable APIs (SRFIs) so that the code is intelligible to most Scheme programmers. Following R6RS is also an objective for the near future.


Related Links

  • Skribe, the father of Skribilo. Its predecessor is Scribe and their goals were expressed in the Scribe white paper by Manuel Serrano and Erick Gallesio.
  • Andy Wingo's STexi (Texinfo as S-expressions), available in Guile-lib.
  • SXML, XML as S-expressions.
  • Nonpareil, Jeff Kingston's much anticipated successor to Lout. Although Nonpareil is more ambitious than Skribilo, the document entitled Nonpareil Document Formatting shows interesting similarities between both systems: separation of document syntax and programming syntax (``readers'' and Scheme in Skribilo), representation of document structure separated from the representation of a laid out document (Nonpareil's doc objects resemble Skribilo's <ast> objects; its scene objects have no equivalent in Skribilo since Skribilo doesn't address text layout by itself). It also includes interesting discussions about text selection and document traversal (Nonpareil's doc objects have no parent pointers, unlike Skribilo's <ast>).
  • Good ol' GNU Texinfo abstracts the various kinds of back-ends very well (in particular its cross-reference-related commands).
  • OSDoc, a derivative of Docbook.
  • Systems that produce documents in various formats from (almost) markup-less input text: txt2tags, GOSH, PlainDoc, and many others.


This HTML page was produced by Skribilo.
Last update: Sat Feb 24 15:31:43+0100 2007