path: root/doc/user/syntax.skb

;;; syntax.skb  --  The Skribilo syntaxes.
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008, 2009  Ludovic Court�s <ludo@gnu.org>
;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
;;;
;;;
;;; This file is part of Skribilo.
;;;
;;; Skribilo is free software: you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
;;; the Free Software Foundation, either version 3 of the License, or
;;; (at your option) any later version.
;;;
;;; Skribilo is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with Skribilo.  If not, see <http://www.gnu.org/licenses/>.

;*---------------------------------------------------------------------*/
;*    The Skribilo syntaxes                                            */
;*---------------------------------------------------------------------*/
(chapter :title "Syntax"
         :ident "syntax"
   
   (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 *skribe-url* :text [Skribe document
preparation system]).  Thus, the Skribe syntax is first described, and
then alternate syntaxes are presented.])


   (section :title [The Skribe Syntax]
            :ident "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.])
	  (item [A text.]))

Here are several examples of correct Skribe expressions:

,(center (frame :margin 5 :border 0 :width *prgm-width*
		(color :margin 5 :bg *disp-color* :width 100.
(itemize (item [,(color :fg "#009900" (tt "\"foo\"")), a string of characters composed of the
characters `,(color :fg "#009900" "f")', `,(color :fg "#009900" "o")'
and `,(color :fg "#009900" "o")'.])
	 (item [,(color :fg "#009900" (tt "123") " " (tt "3.14")), two numbers.])
	 (item [,(color :fg "#009900" (tt "#t") " " (tt "#f")), the ,(emph "true") and ,(emph "false")
Skribe value.])
	 (item [,(color :fg "#009900" (tt "(bold \"foo bar\")")), a list.])
	 (item [,(color :fg "#009900" (tt (char 91)"A text sample"(char 93))), a simple text containing
three words and no escape sequence.])
	 (item [,(color :fg "#009900" (tt (char 91)"Another text sample (that is still) simple"(char 93))),
another simple text.])
	 (item [,(color :fg "#009900" (tt (char 91)"Another ,(bold \"text\") sample"(char 93))),
a more complex text that contains two words (,(color :fg "#009900" (tt "Another")) and ,(color :fg "#009900" (tt "sample")))
and an expression ,(color :fg "#009900" (tt "(bold \"text\")")). The escape sequence is introduced
with the `,(color :fg "#009900" (tt ",("))' characters.])))))

,(p [
Expressions are evaluated, thus ,(color :fg "#009900" (tt "(bold \"foo\")"))
has the effect of typesetting the word ,(color :fg "#009900" (tt "foo")) in
bold face to produce ,(color :fg "#009999" (bold "foo")). Escape sequences
enable evaluation of expressions inside the text. Thus the text
,(color :fg "#009900" (tt (char 91)"Another ,(bold \"text\") sample"(char 93)))
produces `,(color :fg "#009999" (tt [Another ,(bold "text") sample]))'.
On the other hand
,(color :fg "#009900" (tt (char 91)"Another (bold \"text\") sample"(char 93)))
produces
`,(color :fg "#009999" (tt [Another (bold "text") sample]))' because it does not contain
the escape sequence `,(color :fg "#009900" (char #\,)(char #\())'.])
])

;*---------------------------------------------------------------------*/
;*    Formal syntax                                                    */
;*---------------------------------------------------------------------*/
(subsection :title [Formal Syntax]

(disp :verb #t :bg *prgm-skribe-color* [
<expr>    --> <atom>
            | <text>
            | <list>
<list>    --> (<expr>+)
<text>    --> ,(bold (color :fg "red" (char 91))),(it "any sequence but `,(' or a `,")<list>,(it "'"),(bold (color :fg "red" (char 93)))
<atom>    --> <boolean>
            | <integer>
            | <float>
            | <string>
            | <color>
<integer> --> ,(tt (char 91))0-9,(tt (char 93))+
<float>   --> ,(tt (char 91))0-9,(tt (char 93))+.,(tt (char 91))0-9,(tt (char 93))*
            | ,(tt (char 91))0-9,(tt (char 93))*.,(tt (char 91))0-9,(tt (char 93))+
<string>  --> ,(tt #\")...,(tt #\")
<color>   --> <string>
            | ,(tt #\")#,(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt (char 91))0-9a-f,(tt (char 93)),(tt #\")]))

;*---------------------------------------------------------------------*/
;*    Values                                                           */
;*---------------------------------------------------------------------*/
(subsection :title "Values" :file #f :toc #t

;*--- width -----------------------------------------------------------*/
(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
specifying a width:])

(description (item :key "An absolute pixel size" 
		  [This is represented by an ,(emph "exact") integer value
                  (such as ,(code "350")).])
	    (item :key "A relative size" 
		  [This is represented by an ,(emph "inexact") integer value
                  (such as ,(code "50.0")) which ranges in the interval 
                  ,(char 91)-100.0 .. 100.0,(char 93)])
	    (item :key "An engine dependent representation" 
		  [This is represented by a string that is directly emitted
                  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 ()
			  (set-correct-file-encoding!)
			  (let loop ((line   (read-line))
				     (result '()))
			    (if (eof-object? line)
				(string-join (reverse result)
					     (string #\newline))
				(loop (read-line)
				      (cons line result))))))))))
	 (prgm 
	   (with-output-to-string
	     (lambda ()
	       (let* ((read  (make-reader 'outline))
		      (input (open-input-file src)))
		 (set-correct-file-encoding! input)
		 (pretty-print (read input) :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 very simple
markup-less document format, there are many things that cannot be done
using it, most notably tables, bibliographies, and cross-references.]))

   (section :title [The Gemtext Syntax] :ident "gemtext-syntax"
     (p [,(ref
:url "https://gemini.circumlunar.space/docs/gemtext.gmi"
:text "Gemtext"), the lightweight markup language used by the ,(ref
:url "https://gemini.circumlunar.space" :text "Gemini protocol"), is
supported as an input syntax. To use it, just pass ,(tt
[--reader=gemtext]) to the compiler. When used programmatically, the
Gemtext reader can be customized using the following options.])

     (doc-markup 'make-gemtext-reader
                 '((:join-lines? [If ,(code "#t"), lines which are not
separated by a blank line are joined into a single paragraph. This is
a relaxation of the Gemtext standard, and is not done by default.])
                   (:section-numbers? [If ,(code "#t"), sections are
numbered. Else, they are not.]))
                 :common-args '()
                 :source "skribilo/reader/gemtext.scm"
	         :idx *function-index*))

   (section :title [The RSS 2.0 Syntax]
            :ident "rss2-syntax"
      
      (p [RSS 2.0 (aka. ,(ref :url "http://en.wikipedia.org/wiki/RSS" :text
(emph [Really Simple Syndication]))) is supported as an input syntax.
To use it, just pass ,(tt [--reader=rss-2]) to the compiler.  This
makes it possible to generate Skribilo documents from RSS 2.0 feeds,
which can be useful or at least funny.  Consider the following example:]

   (disp :verb #t [
$ wget http://planet.gnu.org/rss20.xml
$ skribilo -R rss-2 -t lout -c column-number=2 < rss20.xml \\
  | lout | ps2pdf - > gnu-planet.pdf
])

[It produces a two-column PDF file with the contents of the RSS feed of
GNU Planet, where each item of the feed is mapped to a Skribilo
``chapter''.]))
   
   (section :title [Documents in Scheme Programs]
            :ident "scheme-syntax"
      
      (p [It is also possible to create and output Skribilo documents
from a Guile Scheme program.  In that case, you get to use the Scheme
syntax, which is close to the ,(ref :ident "skribe-syntax" :text [Skribe
syntax]) described above, modulo the ,(code "[...]") constructs.  A
typical Scheme program that would produce and output a document, pretty
much like what the ,(ref :ident "compiler" :text [,(tt [skribilo])
compiler does]), would look like this:]
	 
	 (example :legend [Programming Skribilo documents in Scheme.]
	  (prgm :language scheme :file "src/scheme.scm"))
	 
        [This should give you an idea of the wonderful, life-changing
things that can be achieved with a bit of ,(emph [document
programming]).]))
   
   (section :title [Writing New Readers]
            :ident "custom-syntax"
      
      (p [Skribilo is extensible and makes it easy to add ,(emph [custom
readers]), allowing the use of virtually any input syntax.  A reader is
essentially a procedure like R5RS' ,(tt [read]), i.e., a one-argument
procedure that takes a port and returns an S-expression.  The returned
S-expression should be a valid ``document program'' as shown in ,(ref
:ident "scheme-syntax").])
      
      (p [The are a few additional details, though.  Implementations of
readers are required to use the ,(tt [(skribilo reader)]) modules and
the ,(tt [define-reader]) macro.  In addition, the reader must live in
its own module, under the ,(tt [(skribilo reader)]) module hierarchy, so
that the reader lookup mechanism (used by the ,(tt [--reader]) option of
the compiler) can find it.  This mechanism is the same as that used for
engines (see ,(numref :text [Section] :ident "custom-engine")).  A
skeleton for a reader would be like this:]
    
	(example :legend [Writing a new reader.]
	 (prgm :language scheme [
(define-module (skribilo reader my-reader)
  #:use-module (skribilo reader)
  #:export (reader-specification))

(define (make-my-reader)
  (lambda (port)
    ...))

(define-reader my-reader  ;; the reader name
  "0.1"                   ;; a version number
  make-my-reader)         ;; the procedure that returns
                          ;; a reader procedure
]))
	
      	[Users and encouraged to look at examples in the Skribilo
source for additional details.])))


;;; Local Variables:
;;; ispell-local-dictionary: "american"
;;; End: