summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès2008-01-29 17:52:44 +0100
committerLudovic Courtès2008-01-29 17:52:44 +0100
commitbda408c218cad42b482981213de79e3382df87b6 (patch)
tree8c1b09217724d4edb19a3e1369355f9c73e980eb
parent54936ba52223f0e1e92c8e7aa393be904299e28a (diff)
downloadskribilo-bda408c218cad42b482981213de79e3382df87b6.tar.gz
skribilo-bda408c218cad42b482981213de79e3382df87b6.tar.lz
skribilo-bda408c218cad42b482981213de79e3382df87b6.zip
doc: Document the `outline' reader.
* doc/user/Makefile.am (EXTRA_DIST): Add `src/outline.txt' and `loute.skb'. * doc/user/compiler.skb: Add ref to `outline-syntax'. * doc/user/syntax.skb: Re-structure, add `outline-syntax' section. * doc/user/user.skb: Use `(skribilo reader)' and `(ice-9 pretty-print)'.
-rw-r--r--doc/user/Makefile.am5
-rw-r--r--doc/user/compiler.skb4
-rw-r--r--doc/user/src/outline.txt59
-rw-r--r--doc/user/syntax.skb112
-rw-r--r--doc/user/user.skb6
5 files changed, 172 insertions, 14 deletions
diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
index 385f641..c89c95f 100644
--- a/doc/user/Makefile.am
+++ b/doc/user/Makefile.am
@@ -2,7 +2,7 @@
EXTRA_DIST = bib.skb char.skb colframe.skb document.skb emacs.skb \
engine.skb enumeration.skb eq.skb examples.skb figure.skb \
font.skb footnote.skb htmle.skb image.skb index.skb \
- justify.skb latexe.skb lib.skb line.skb links.skb \
+ justify.skb latexe.skb loute.skb lib.skb line.skb links.skb \
markup.skb ornament.skb package.skb pie.skb prgm.skb sectioning.skb \
skribilo-config.skb compiler.skb skribeinfo.skb slide.skb spacing.skb \
start.skb syntax.skb table.skb toc.skb user.skb xmle.skb \
@@ -20,7 +20,8 @@ EXTRA_DIST += src/api1.skb \
src/index1.skb src/index2.skb src/index3.skb src/links1.skb \
src/links2.skb src/pie1.skb src/pie2.skb src/prgm1.skb src/prgm2.skb \
src/prgm3.skb src/slides.skb src/start1.skb src/start2.skb \
- src/start3.skb src/start4.skb src/start5.skb
+ src/start3.skb src/start4.skb src/start5.skb \
+ src/outline.txt
html_DATA = user.html
diff --git a/doc/user/compiler.skb b/doc/user/compiler.skb
index cde4146..cde7331 100644
--- a/doc/user/compiler.skb
+++ b/doc/user/compiler.skb
@@ -75,8 +75,8 @@ i.e., as the format of the input file. Currently, two formats are
supported: ,(tt [skribe]), which corresponds to the Skribe syntax (see
,(numref :text [Chapter] :ident "syntax")), or ,(tt [outline]), which
corresponds to plain text (markup-less) following the structuring
-conventions of ,(ref :text [Emacs' Outline mode] :url
-"http://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html").])
+conventions of Emacs' Outline mode (see ,(numref :text [Section] :ident
+"outline-syntax")).])
`(#\t "engine" ,[Use ,(tt "engine") as the engine, i.e., as
the output format. For details on engines and for a list of supported
engines, see ,(numref :text [Chapter] :ident "engines").])
diff --git a/doc/user/src/outline.txt b/doc/user/src/outline.txt
new file mode 100644
index 0000000..a89a2d0
--- /dev/null
+++ b/doc/user/src/outline.txt
@@ -0,0 +1,59 @@
+-*- mode: outline; coding: latin-1; -*-
+
+Title: Demonstrating Skribilo's Outline Syntax
+Author: Ludovic Courtès
+Keywords: Skribilo outline Emacs
+
+This document aims to *demonstrate*
+[[http://skribilo.nongnu.org/][Skribilo]]'s outline syntax.
+
+
+* The First Chapter
+
+The first chapter contains a couple of sections.
+They look as though they had been introduced with
+the `section' markup of the Skribe syntax.
+
+** The First Section
+
+This section is pretty much empty.
+
+** The Second Section
+
+This section introduces lists.
+
+*** Bullet Lists
+
+This section contains a wonderful `itemize'-style bullet list:
+
+ - the first item;
+
+ - the second item;
+
+ - the last one, which spans
+ two lines of text.
+
+
+And that's it. Note that list items had to be
+separated by empty lines.
+
+*** Enumerations
+
+This section shows an `enumerate'-style list:
+
+ 1. The first item;
+
+ 2. The second one;
+
+ 3. The last one.
+
+
+Note that list items are numbered this time.
+
+
+* The Second Chapter
+
+The second chapter does _not_ add anything useful.
+
+Text like this that starts after an empty line is
+put into a new paragraph.
diff --git a/doc/user/syntax.skb b/doc/user/syntax.skb
index 7a47273..5ade31a 100644
--- a/doc/user/syntax.skb
+++ b/doc/user/syntax.skb
@@ -1,4 +1,4 @@
-;;; syntax.skb -- The Skribe syntax.
+;;; syntax.skb -- The Skribilo syntaxes.
;;;
;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org>
;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano
@@ -20,13 +20,30 @@
;;; USA.
;*---------------------------------------------------------------------*/
-;* The Skribe syntax */
+;* The Skribilo syntaxes */
;*---------------------------------------------------------------------*/
-(chapter :title "Syntax & Values"
+(chapter :title "Syntax"
:ident "syntax"
- (p [A Skribilo document is composed of Skribe expressions. A Skribe
-expression can be:
+ (p [This chapter describes the syntax or Skribilo documents---or
+rather, the available syntaxes Skribilo documents can use. Skribilo
+actually supports several input syntaxes, each of which is implemented
+by a ,(emph [reader]). The input syntax (and reader) can be selected at
+document compilation time using the ,(tt [--reader]) option of the
+compiler (see ,(numref :text [Chapter] :ident "compiler")).
+Nevertheless, it has a ``preferred'' syntax (the default syntax), which
+is that of the ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Skribe/"
+:text [Skribe document preparation system]). Thus, the Skribe syntax is
+first described, and then alternate syntaxes are presented.])
+
+
+ (section :title [The Skribe Syntax]
+
+ (p [By default or when the ,(tt [--reader=skribe]) option is
+passed to the compiler, a Skribilo document is composed of ,(emph
+[Skribe expressions]), which resemble expressions in the Scheme
+programming language, with a few extensions to make them more convenient
+to use within documents. A Skribe expression can be:
,(itemize (item [An atomic expression, such as a string of characters, a number.])
(item [A list.])
@@ -69,7 +86,7 @@ the escape sequence `,(color :fg "#009900" (char #\,)(char #\())'.])
;*---------------------------------------------------------------------*/
;* Formal syntax */
;*---------------------------------------------------------------------*/
-(section :title "Skribe Syntax"
+(subsection :title "Skribe Syntax"
(disp :verb #t :bg *prgm-skribe-color* [
<expr> --> <atom>
@@ -92,10 +109,10 @@ the escape sequence `,(color :fg "#009900" (char #\,)(char #\())'.])
;*---------------------------------------------------------------------*/
;* Values */
;*---------------------------------------------------------------------*/
-(section :title "Values" :file #f :toc #t
+(subsection :title "Values" :file #f :toc #t
;*--- width -----------------------------------------------------------*/
-(subsection :title "Width" (p [
+(subsubsection :title "Width" (p [
,(mark "width")
A Skribe ,(emph "width") refers to the horizontal size a construction
occupies on an output document. There are three different ways for
@@ -113,6 +130,85 @@ specifying a width:])
in the output document (such as HTML column ,(code "\"0*\"")
specification). Note that this way of specifying width
is strictly unportable.])))))
+
+
+ (section :title [The Outline Syntax]
+ :ident "outline-syntax"
+
+ (p [Alternatively, Skribilo allows documents to be written in a
+plain text format, with almost no markup. Instead, conventions borrowed
+from ,(ref :text [Emacs' Outline Mode] :url
+"http://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html")
+to denote the text structure as well as other common conventions are
+used to express various formatting ideas. This syntax is implemented by
+the ,(tt [outline]) reader; thus, it is made available by passing the
+,(tt [--reader=outline]) option to the ,(ref :ident "compiler" :text
+[compiler]). The major elements of this syntax are the following:])
+
+ (description
+ (item :key [Document title and author]
+ [The document title is introduced by adding a line starting
+with ,(code [Title:]) at the beginning of the text file, and followed by
+the title. Likewise, the author can be specified with a line starting
+with ,(code [Author:]).])
+ (item :key [Sectioning]
+ [Chapters are introduced using a heading preceding by a
+single ,(tt [*]) (star) character. For instance, ,(tt [* The First
+Part]) on a line on its own, followed by an empty line, introduces a new
+chapter entitled ``The First Part''. Likewise, two stars introduce a
+section, three stars introduce a subsection, etc.])
+ (item :key [Emphasis, italics, bold]
+ [Words or phrases surrounded by the ,(tt [_]) (underscore)
+character are emphasized; those surrounded by ,(tt [/]) (slash)
+characters are italicized; finally, those surrounded by ,(tt [*]) (star)
+characters are typeset in boldface (see Section ,(ref :section
+"Ornaments")).])
+ (item :key [Quotes]
+ [Words enclosed in double quotes (i.e., two back-quote
+characters, then two single-quote characters) are interpreted as quoted
+text, as per ,(tt "q").])
+ (item :key [Code]
+ [Words enclosed in single quotes (i.e., one back-quote
+character, then one single-quote) are interpreted as code and are
+typeset using a fixed-width font, as per ,(markup-ref "tt").])
+ (item :key [Hyperlinks]
+ [URLs are automatically recognized and converted into a
+,(code [(ref :url ...)]) form (see ,(markup-ref "ref")). In addition,
+,(tt [outline]) has limited support for Org-Mode-style hyperlinks; for
+instance, ,(code "[[http://gnu.org/][The GNU Project]]") yields ,(ref
+:url "http://gnu.org/" :text [The GNU Project]).]))
+
+ (p [Here is an example showing how the ,(tt [outline]) syntax maps
+to the native ,(tt [skribe]) syntax:])
+
+ (let ((src (string-append %top-srcdir "/doc/user/src/outline.txt")))
+ (example-produce
+ (example :legend [The ,(tt [outline]) syntax]
+ (tt
+ (flush :side 'left
+ (pre (with-input-from-file src
+ (lambda ()
+ (let loop ((line (read-line))
+ (result '()))
+ (if (eof-object? line)
+ (string-join (reverse result)
+ (string #\newline))
+ (loop (read-line)
+ (cons line result))))))))))
+ (disp
+ (prgm
+ (with-output-to-string
+ (lambda ()
+ (let* ((read (make-reader 'outline))
+ (input (open-input-file src))
+ (sexp (read input)))
+ (pretty-print sexp :width 65))))))))
+
+ (p [The ,(tt [outline]) mode makes it possible to quickly create
+documents that can be output in variety of formats (see ,(numref :text
+[Chapter] :ident "engines")). The downside is that, being a markup-less
+document format, there are many things cannot be done using it, most
+notably tables, bibliographies, and cross-references.])))
;;; Local Variables:
;;; coding: latin-1
diff --git a/doc/user/user.skb b/doc/user/user.skb
index 4147292..3844df8 100644
--- a/doc/user/user.skb
+++ b/doc/user/user.skb
@@ -33,13 +33,15 @@
(use-modules (skribilo package eq)
(skribilo package pie)
(skribilo package slide)
- (skribilo package web-book2))
+ (skribilo package web-book2)
+ (skribilo reader))
(if %have-ploticus? (set! %ploticus-program %ploticus-path))
;; Modules needed, e.g., to get the output of "skribilo-config --help".
(use-modules (ice-9 popen)
- (ice-9 rdelim))
+ (ice-9 rdelim)
+ (ice-9 pretty-print))
;*---------------------------------------------------------------------*/