diff options
| -rw-r--r-- | doc/user/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/user/compiler.skb | 4 | ||||
| -rw-r--r-- | doc/user/src/outline.txt | 59 | ||||
| -rw-r--r-- | doc/user/syntax.skb | 112 | ||||
| -rw-r--r-- | doc/user/user.skb | 6 |
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)) ;*---------------------------------------------------------------------*/ |