Features

document programming framework

  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: