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