;;; ;;; Skribilo's Wonderful Website. ;;; (use-modules (skribilo ast) (skribilo engine) (skribilo source lisp) (skribilo package html-navtabs)) (define (html-tabs n e) ;; Create one "navigation tab" for each chapter. (let ((doc (ast-document n))) (map handle (container-search-down (lambda (n) (is-markup? n 'chapter)) doc)))) (let ((html (find-engine 'html))) (if (engine? html) (begin ;; Customizing the HTML output... (engine-custom-set! html 'css "static/main.css") (engine-custom-set! html 'html-navtabs-produce-css? #f) (engine-custom-set! html 'html-navtabs html-tabs) (engine-custom-set! html 'charset "UTF-8")))) ;;; ;;; List of useful URLs. ;;; (define (wikipedia/markup . body) (ref :url "http://en.wikipedia.org/wiki/Markup_language" :text body)) (define (wikipedia/markup-less . body) (ref :url "http://en.wikipedia.org/wiki/Lightweight_markup_language" :text body)) (define (wikipedia/esperanto . body) (ref :url "http://en.wikipedia.org/wiki/Esperanto" :text body)) (define (scheme . body) (ref :url "http://schemers.org/" :text body)) (define (guile . body) (ref :url "http://www.gnu.org/software/guile/guile.html" :text body)) (define (r6rs . body) (ref :url "http://r6rs.org/" :text body)) (define (latex . body) (ref :url "http://www.latex-project.org/" :text body)) (define (context . body) (ref :url "http://www.pragma-ade.nl/" :text body)) (define (lout . body) (ref :url "http://savannah.nongnu.org/projects/lout/" :text body)) (define (info . body) (ref :url "http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Files.html" :text body)) (define (ploticus . body) (ref :url "http://ploticus.sf.net/" :text body)) (define (guile-lib . body) (ref :url "http://www.nongnu.org/guile-lib/" :text body)) (define (freedom . body) (ref :url "http://www.gnu.org/philosophy/free-sw.html" :text body)) (define (gpl . body) (ref :url "http://www.gnu.org/licenses/gpl.html" :text body)) (define (emacs/outline . body) (ref :url "http://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html" :text body)) (define (skribilo-ml . body) (ref :url "http://lists.nongnu.org/mailman/listinfo/skribilo-users" :text body)) (define (git . body) (ref :url "http://git.or.cz/" :text body)) (define (skribe* . body) (ref :url "http://www-sop.inria.fr/mimosa/fp/Skribe/" :text body)) (define (scribe . body) (ref :url "http://www-sop.inria.fr/members/Manuel.Serrano/scribe/" :text body)) (define (bigloo . body) (ref :url "http://www-sop.inria.fr/mimosa/fp/Bigloo/" :text body)) (define (stklos . body) (ref :url "http://stklos.net/" :text body)) (define %user-sui ;; Location of the User Manual's SUI file. "doc/user.sui") ;;; ;;; The website. ;;; (document :title [Skribilo: The Ultimate Document Programming Framework] :author #f :keywords '("Skribilo" "document programming" "document formatting" "authoring" "Scheme" "Guile" "Skribe" "Lout" "LaTeX" "HTML") (mark "intro") (p [Skribilo is a ,(freedom [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 [Info]) for on-line browsing, and ,(lout [Lout]) and ,(latex [LaTeX]) for high-quality hard copies.]) (p [The input document can use Skribilo's ,(wikipedia/markup [markup language]) to provide information about the document's structure, which is similar to HTML or ,(latex [LaTeX]) and does not require expertise. Alternatively, it can use a simpler, “,(wikipedia/markup-less [markup-less])” format that borrows from ,(emacs/outline [Emacs' outline mode]) and from other conventions used in emails, Usenet and text.]) (p [Last but not least, Skribilo can be thought of as a complete ,(emph [document programming framework]) for the ,(scheme [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 ,(it [via]) so-called ,(ref :url "http://www.haskell.org/haskellwiki/Embedded_domain_specific_language#Degree_of_embedding" :text [“deep embedding”]). Skribilo uses ,(guile [GNU Guile]) 3.0 or 2.x as the underlying Scheme implementation.]) (chapter :title [Features] :number #f :file #f :ident "features" (itemize (item [Output in a ,(ref :skribe %user-sui :ident "engines" :text [variety of formats]): HTML, XML, ,(lout [Lout]), ,(latex [LaTeX]), ,(context [ConTeXt]), and ,(info [Info]).]) (item [Input using ,(skribe* [Skribe])'s ,(ref :skribe %user-sui :ident "skribe-syntax" :text [markup]) (see ,(ref :mark "self" :text [this example])), or using free form, markup-less text and conventions similar to those used in ,(ref :skribe %user-sui :ident "outline-syntax" :text [Emacs' outline mode]), or from an ,(ref :skribe %user-sui :ident "rss2-syntax" :text [RSS,(~)2 feed]).]) (item [Packages are available to produce: ,(ref :skribe %user-sui :ident "slides" :text [slides]) (overhead transparencies), ,(ref :skribe %user-sui :ident "pie-charts" :text [pie charts]), ,(ref :skribe %user-sui :ident "equations" :text [equation formatting]), ,(ref :skribe %user-sui :ident "programs" :text [syntax highlighting of computer programs]), and others.]) (item [,(ref :skribe %user-sui :chapter "Bibliographies" :text [Bibliography management])—i.e., BibTeX on steroids thanks to the programmability brought by ,(scheme [Scheme]).]) (item [Unicode support.]) (item [Use of a proper module system (that of ,(guile [Guile])) rather than ,(tt [load])-style interactions.]) (item [And much more! :-)]))) (chapter :title [Availability] :number #f :file #f :ident "download" (p [Releases are available from the ,(ref :text [download area] :url "http://dl.sv.nongnu.org/releases/skribilo/").]) (p [Skribilo is distributed under the terms of the ,(gpl [GNU General Public Licence]), version 3 or later. To use Skribilo, you need the following pieces of software: ,(itemize (item [,(guile [GNU Guile]) 3.0, 2.2.*, or 2.0.*;]) (item [,(ref :url "http://www.nongnu.org/guile-reader/" :text [Guile-Reader]) 0.6 or later;]) (item [either ,(lout [Lout]) (3.31 or later), ,(latex [LaTeX]), or ,(context [ConTeXt]) to produce hard copies (PostScript/PDF);]) (item [optionally, ,(ploticus [Ploticus]) to produce pie charts (alternatively, ,(lout [Lout]) can be used for that purpose);]) (item [optionally, ,(guile-lib [Guile-Lib]) to be able to use the ,(ref :skribe %user-sui :ident "rss2-syntax" :text [RSS-2 reader]).]))])) (chapter :title [Documentation] :number #f :file #f ;; FIXME: Do it! :ident "documentation" (p [The user manual is available in the following formats: ,(itemize (item (ref :text [HTML] :url "doc/user.html")) (item (ref :text [PDF] :url "doc/user.pdf")))])) (chapter :title [Example] :number #f :file #f :ident "example" (p [Here is a live example: the source code of this web page, colored using Skribilo's computer program coloring features.]) (mark "self") (tt (prog (source :language skribe :file "index.skb")))) (chapter :title [Mailing List] :number #f :file #f :ident "mailing-list" (p [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-ml [,(tt [skribilo-users]) mailing list])! If you want to suggest improvements, that's also where they should go!])) (chapter :title [Development] :number #f :file #f :ident "development" (p [Development is done using the ,(git [Git]) distributed revision control system. You can fetch a copy of the source code repository using the following incantation: ,(frame :class "code-excerpt" :border #f :margin #f (code [git clone git://git.sv.gnu.org/skribilo.git])) You can then happily hack on your side and eventually promote your changes ,(ref :ident "mailing-list" :text [on the mailing-list]).]) (p [The repository can also be ,(ref :url "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=summary" :text [browsed on-line]).]) (p [A tentative list of milestones and to-do items is in the ,(ref :url "http://git.sv.gnu.org/gitweb/?p=skribilo.git;a=blob;f=TODO" :text [,(tt [TODO]) file]).])) (chapter :title [History] :number #f :file #f :ident "history" (p [Skribilo is a direct descendant of ,(skribe* [Skribe]), a document production tool written by Manuel Serrano for ,(bigloo [Bigloo]) and ported to ,(stklos [STkLos]) by Érick Gallesio. Development of ,(skribe* [Skribe]) started around 2003 as a successor of Manuel's previous documentation system named ,(scribe [Scribe]).]) (p [Skribilo derives from Skribe 1.2d but it differs in a number of ways: ,(itemize (item [It contains new packages (pie charts, equation formatting) and a new engine (the ,(lout [Lout]) engine).]) (item [Symmetrically to the notion of engine (rendering back-ends), Skribilo has the concept of ,(emph [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 [Emacs' outline mode]).]) (item [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 ,(ref :url "http://srfi.schemers.org/srfi-35/srfi-35.html" :text [SRFI-35 exceptions]) are used rather than plain ,(tt [error]) or ,(tt [exit]) calls. The idea is to expose ,(emph [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.]) (item [Although Skribilo only runs on ,(guile [GNU Guile]), care was taken to use mostly portable APIs (,(ref :url "http://srfi.schemers.org/" :text [SRFIs])) so that the code is intelligible to most Scheme programmers.]))])) (chapter :title [Related Links] :number #f :file #f :ident "related" (itemize (item [,(skribe* [Skribe]), the father of Skribilo. Its predecessor is ,(scribe [Scribe]) and their goals were expressed in ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Scribe/doc/scribe.html" :text (it [the Scribe white paper])) by Manuel Serrano and Érick Gallesio. Their 2005 Journal of Functional Programming (JFP) article entitled ,(ref :url "http://www-sop.inria.fr/mimosa/Manuel.Serrano/publi/jfp05/article.html" :text (it [Skribe: A Functional Authoring Language])) provides further insight.]) (item [,(ref :url "http://docs.racket-lang.org/scribble/index.html" :text [Scribble]), the documentation system of Racket, is similar in spirit to Skribilo/Skribe. It has ,(ref :url "http://docs.racket-lang.org/scribble/getting-started.html" :text [different syntax]) and ,(ref :url "http://docs.racket-lang.org/scribble/base.html" :text [markup]). ,(ref :skribe %user-sui :ident "engines" :text [Like Skribilo]), it supports several ,(ref :url "http://docs.racket-lang.org/scribble/renderer.html" :text "renderers"). It does not seem to provide an API to work with the AST, and things like ,(ref :url "http://git.savannah.gnu.org/cgit/skribilo.git/tree/src/guile/skribilo/resolve.scm" :text (tt [resolve])).]) (item [Andy Wingo's ,(ref :url "http://www.gnu.org/software/guile/manual/html_node/texinfo.html" :text [STexi]) (,(ref :text [Texinfo] :url "http://www.gnu.org/software/texinfo/") as S-expressions), available in ,(guile [Guile 2.x]). The ,(ref :text (tt [fold-layout]) :url "http://www.gnu.org/software/guile/manual/html_node/sxml-fold.html") operator provides an interesting, purely functional approach to documentation transformation (not unlike XSLT, but with a real programming language).]) (item [The ,(ref :url "http://www.jstatsoft.org/v46/i03/paper" :text [Org-Mode paper about reproducible research]) introduces ideas that can be usefully implemented in Skribilo: a Skribilo document can embed executable code, and run it to include its results at compilation time.]) (item [,(ref :url "http://okmij.org/ftp/Scheme/SXML.html" :text [SXML]), XML as S-expressions. Oleg Kiselyov's discussion of ,(ref :text [implementation strategies for a purely functional SXML tree] :url "http://okmij.org/ftp/Scheme/parent-pointers.txt") is a good source of inspiration.]) (item [,(ref :url "http://www.ccs.neu.edu/home/dorai/mistie/mistie.html" :text [Mistie]), a “programmable filter” in Scheme (for MzScheme) that allows the definition of filters from one markup language to another one.]) (item [,(ref :url "http://www.it.usyd.edu.au/~jeff/nonpareil/" :text [Nonpareil]), Jeff Kingston's much anticipated successor to ,(lout [Lout]), both being purely functional document formatting systems/languages. Although Nonpareil is more ambitious than Skribilo, the document entitled ,(it [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 ,(it [doc]) objects resemble Skribilo's ,(tt []) objects; its ,(it [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 ,(it [doc]) objects have no parent pointers, unlike Skribilo's ,(tt [])).]) (item [Good ol' ,(ref :url "http://www.gnu.org/software/texinfo/" :text [GNU Texinfo]) abstracts the various kinds of back-ends very well (in particular its cross-reference-related commands).]) (item [,(ref :url "http://www.coyotos.org/docs/osdoc/osdoc.html" :text [OSDoc]), a derivative of ,(ref :url "http://docbook.org/" :text [Docbook]).]) (item [Systems that produce documents in various formats from (almost) markup-less input text: ,(ref :url "http://txt2tags.sf.net/" :text [txt2tags]), ,(ref :url "http://www.maplefish.com/todd/aft.html" :text [AFT]), ,(ref :url "http://os.inf.tu-dresden.de/~nf2/files/GOSH/" :text [GOSH]), ,(ref :url "http://mercnet.pt/plaindoc/pd.html" :text [PlainDoc]), ,(ref :url "http://www.methods.co.nz/asciidoc/" :text [AsciiDoc]), ,(ref :url "http://docutils.sourceforge.net/rst.html" :text [reStructured Text (RST)]), ,(ref :url "http://www.t3x.org/attic/index.html#sd" :text [SD]), ,(ref :url "http://triptico.com/software/grutatxt.html" :text [Grutatxt]), and many others.]))) (chapter :title [The Name] :number #f :file #f :ident "name" (p [Skribilo is an ,(wikipedia/esperanto [Esperanto]) noun, which literally means ,(ref :url "http://www.reta-vortaro.de/revo/art/skrib.html#skrib.0ilo" :text [“a tool to write”]) (prefix “,(ref :url "http://www.reta-vortaro.de/revo/art/skrib.html" :text [skrib])” relates to writing, while suffix “,(ref :text [-ilo] :url "http://www.reta-vortaro.de/revo/art/il.html")” designates a tool). Interestingly, “,(skribe* [skribe])”, which is the name of the tool Skribilo is based on, is an adverb meaning “writing” in ,(wikipedia/esperanto [Esperanto]).]))) ;;; Local Variables: ;;; coding: utf-8 ;;; ispell-local-dictionary: "american" ;;; indent-tabs-mode: nil ;;; End: