|
|
This chapter describes the forms composing Scribe texts. In XML/HTML
these forms are called markups. In LaTeX they are called
macros. In Scribe these forms are called functions. In this manual we will say that we call a
function when a function is used in a form. The values used in a
function call are named the actual parameters of the
function or parameters in short. When calling a function
with parameters we say that we are passing arguments to the
function.
In this documentation function names are typesetted in bold face. We
call a keyword argument, an argument whose identifier starts
with the : character. Arguments whose identifier does not start
with this character are called plain arguments or
arguments in short. An optional argument is
represented by a list, starting with the character "[" and
ending with the character "]", whose first element is a keyword
argument and the second element is the default value used if the optional
argument value is not provided on a function call. Arguments that are not
optional are said mandatory. If a plain argument is preceeded with
a . character, this argument may be used to accumulate several
values. There are two ways to pass actual arguments
to a function.
- for keyword arguments: the value of the parameter
must be preceeded by the name of the argument.
- for plain arguments: a value is provided.
Example: Let us consider the function section defined as follows:
(section :title [:number #t] [:toc #t] . body) |
The argument :title is a mandatory keyword argument.
The keyword arguments :number and :toc are
optional. The plain argument body is preceeded with a
. character so it may receive several values. All the following
calls are legal section calls:
(section :title "A title" "This is the body of the section")
(section :title "A title" "This" " is" " the body of the section")
(section :title "A title" :number 3 "This" " is" " the body of the section")
(section :title "A title" :toc #f :number 3 "This" " is" " the body of the section")
(section :title "A title" :number 3 :toc #f "This" " is" " the body of the section") |
| (document :title [:author list] . body) | Scribe function |
The document function defines a Scribe document. The mandatory
argument :title is a Scribe expression that contains the
title of the document. The argument :author is a list of
authors. Each element of this list can be any Scribe expression. In
particular, the element of the :author list can be value
built by the function author.
Example:
(document :title "This is a Scribe document"
:author '("Foo" "Bar" (author :name "Gee" :email "gee@nowhere.org"))
"A body...") |
| (author :name [:title #f] [:affiliation #f] [:email #f] [:url #f] [:address #f] [:phone #f] [:photo #f]) | Scribe function |
The author function is used to specify the author of a Scribe
document. The arguments are:
| argument | description |
|---|
| :name | The name of the author. |
| :title | His title, such as Dr., Pr., team manager. |
| :affiliation | His affiliation, such as a university or a company. |
| :email | His email. |
| :url | His web page URL. |
| :phone | His phone and fax numbers. |
| :address | His address. |
| :photo | A picture (see image to create images.) |
The example:
(author :name "Manuel Serrano"
:affiliation "Inria Sophia-Antipolis"
:url "http://kaolin.unice.fr/~serrano"
:email "Manuel.Serrano@inria.fr"
:address `("2004 route des Lucioles - BP 93"
"F-06902 Sophia Antipolis, Cedex"
"France")
:phone "phone: (+33) 4 92 38 76 41") |
produces:
Manuel Serrano
Inria Sophia-Antipolis
2004 route des Lucioles - BP 93
F-06902 Sophia Antipolis, Cedex
France
Manuel.Serrano@inria.fr
http://kaolin.unice.fr/~serrano
phone: (+33) 4 92 38 76 41 |
| (chapter [:title #f] [:subtitle #f] [:number #t] [:toc #t] [:file #t] [:split #f] . body) | Scribe function |
This function creates a new chapter of a Scribe document. Its arguments
are:
| argument | description |
|---|
| :title | The title of the chapter. |
| :subtitle | If the chapter has no title, it must have a subtitle. When
a subtitle is preferred to a title, when rendering the chapter, the
Scribe compiler will prefix the title of the current document to the
chapter subtitle. |
| :number | This argument controls the chapter number.
A value of #t means that the Scribe compiler computes the chapter
number. A value of #f means that the chapter has no number. |
| :toc | This argument controls if the chapter must
be referenced in the table of contents. |
| :file | The argument :file1 must be a boolean. A value of
#t tells the Scribe compiler to compile that chapter in a separate
file. A value of #f tells the Scribe compiler to embed the chapter
in the main target file. |
| :split | The argument :split must be a boolean. A value of
#t tells the Scribe compiler that each section contained in this
chapter must be emitted in a separate file. Otherwise, the sections are
emitted in the file containing the chapter. Obviously, this option applies
only to back-end supporting multi-file generation (such as the HTML backend). |
Example:
(chapter :title "A chapter" [A chapter body.])
(chapter :subtitle "A another chapter" [Another chapter.])
(chapter :title "A last chapter" :file #f :toc #f [A chapter in the main target file.]) |
| (section :title [:number #t] [:file #f] [:toc #t] . body) | Scribe function |
| (subsection :title [:number #t] [:toc #t] . body) | Scribe function |
| (subsubsection :title [:number #t] . body) | Scribe function |
| argument | description |
|---|
| :title | The mandatory :title is the name of the
block (e.g., the section, subsection or subsubsection) |
| :file | The argument :file is only applicable to
section. It has the same meaning as the :file argument
of chapter. |
| :number | This argument may be either a boolean or
an integer. If the argument value is #t, the block number will
be automatically computed by the Scribe compiler. If the argument value is
#f the block won't have any number. If the argument is an integer
value, the Scribe compiler sets its block counter to the provided value. |
| :toc | This argument specifies if the section
or subsection must be referenced in the
table of contents. |
Example:
(section :title "A Section" [
,(subsection :title "A first subsection" [a body])
,(subsection :title "A second subsection" [
,(subsubsection :title "A subsubsection" :number #f [a subsubsection body])])]) |
| (paragraph . body) | Scribe function |
This function introduces a paragraph in the output text. The newlines in
the source file are not significant. That is, depending on the layout
width, the Scribe compiler or the rendering engines (such as a Web browser)
decide where to introduce line breaks.
Example:
(paragraph [
This
is the
body of the paragraph]) |
| (table-of-contents [:chapter #t] [:section #t] [:subsection #f]) | Scribe function |
The function table-of-contents displays the table of contents
of a Scribe text. The table of contents may or may not display
chapters and sections.
The following example:
(table-of-contents :section #f) |
displays the chapters composing this user manual:
| (font [:size number] [:face string] body) | Scribe function |
the function font enables font selection in a Scribe text.
| argument | description |
|---|
| :size | The size of the font. The size may be relative
(with respect to the current font size) or absolute. A relative
font is either specified with a floating point value or a negative
integer value. A positive integer value specifies an absolute font size. |
| :face | The name of the font to be used. |
| body | The text the font is applied to. |
The example:
(itemize
(item (font :size -2 [A smaller font.]))
(item (font :size 6 [An absolute font size.]))
(item (font :size 4. [A larger font.]))
(item (font :face "Helvetica" [An helvetica example.]))) |
produces:
- A smaller font.
- An absolute font size.
- A larger font.
- An helvetica example.
|
| (roman . body) | Scribe function |
| (bold . body) | Scribe function |
| (it . body) | Scribe function |
| (emph . body) | Scribe function |
| (underline . body) | Scribe function |
| (kbd . body) | Scribe function |
| (tt . body) | Scribe function |
| (code . body) | Scribe function |
| (var . body) | Scribe function |
| (samp . body) | Scribe function |
| (sc . body) | Scribe function |
| (sf . body) | Scribe function |
| (sup . body) | Scribe function |
| (sub . body) | Scribe function |
The example:
(itemize (item (roman "a roman text."))
(item (bold "a bold text."))
(item (it "an italic text."))
(item (emph "an emphasized text."))
(item (underline "an underline text."))
(item (kbd "a keyboard description."))
(item (tt "a typewritter text."))
(item (code "a text representing computer code."))
(item (var "a computer program variable description."))
(item (samp "a sample."))
(item (sc "a smallcaps text."))
(item (sf "a sans-serif text."))
(item (sup "a superscripts text."))
(item (sub "a subscripts text."))
(item (underline (bold (it "an underline, bold, italic text."))))) |
produces:
- a roman text.
- a bold text.
- an italic text.
- an emphasized text.
- an underline text.
- a keyboard description.
- a typewritter text.
a text representing computer code.
- a computer program variable description.
- a sample.
- a smallcaps text.
- a sans-serif text.
- a superscripts text.
- a subscripts text.
- an underline, bold, italic text.
|
| (linebreak [num 1]) | Scribe function |
Skip num blank lines.
| (hrule [:width 1.0] [:height 1]) | Scribe function |
Introduces an horizontal rule in the produced text.
The argument :width controls the horizontal
size of the rule. A floating point number represents a percentage
of the line size. Thus a value of 1. stands for the whole line width.
An integer having a value greater than 1 stands for a pixel number.
The argument :height controls the line thickness.
A positive integer value stands for a number of pixels.
| (center . body) | Scribe function |
| (pre . body) | Scribe function |
| (flush [:side 'center] . body) | Scribe function |
These functions control the text layout. The default layout is text
justification. The possible values for the :side argument
are left, center or right.
The example:
(center [A ,(linebreak) multilines ,(linebreak) text])
(hrule)
(flush :side 'left [A ,(linebreak) multilines ,(linebreak) text])
(hrule)
(flush :side 'right [A ,(linebreak) multilines ,(linebreak) text])
(hrule)
(pre [A text layout that
preserves
linebreaks and spaces ,(it "(into which it is still legal
to use Scribe function calls)").]) |
produces:
A
multilines
text
A
multilines
text
A
multilines
text
A text layout that
preserves
linebreaks and spaces (into which it is still legal
to use Scribe function calls). |
| (list . items) | Scribe function |
Constructs a list composed of the items Scribe expressions.
| (item [:key '()] . items) | Scribe function |
| (itemize . items) | Scribe function |
| (enumerate . items) | Scribe function |
| (description . items) | Scribe function |
The key and items arguments for
item are any Scribe expression.
The items argument for itemize,
enumerate and description are item expressions.
The example:
(itemize (item [A first item.])
(item [A ,(bold "second") one.])
(item [Lists can be nested. For instance that item contains a
,(tt "description"):
,(description (item :key (bold "foo")
[is a usual Lisp dummy identifier.])
(item :key (bold "bar")
[is another one.])
(item :key (list (bold "foo") (bold "bar"))
[A description entry may contain more than
one keyword.]))])
(item [The last ,(tt "itemize") entry contains an ,(tt "enumerate"):
,(enumerate (item "One.") (item "Two.") (item "Three."))])) |
produces:
- A first item.
- A second one.
- Lists can be nested. For instance that item contains a
description:
- foo
- is a usual Lisp dummy identifier.
- bar
- is another one.
- foo
- bar
- A description entry may contain more than
one keyword.
- The last itemize entry contains an enumerate:
- One.
- Two.
- Three.
|
| (image :file [:width #f] [:height #f] [:zoom #f] . comment) | Scribe function |
| argument | description |
|---|
| :file | The filename where the image
is stored on the disk. |
| :width | The width of the image. It may be an integer for a pixel
size or a floating point number for a percentage. |
| :height | The height of the image. It may be an integer for a pixel
size or a floating point number for a percentage. |
| comment | A text describing the image. |
The example:
(image :file "linux.gif" "A first image")
(image :height 50 :file "linux.gif" "A smaller one")
(image :file "bsd.gif" "A second image")
(image :width 50 :file "bsd.gif")
(image :width 200 :height 40 :file "bsd.gif") |
produces:
Images are unfortunately unportable.
The various output formats support different image formats. For instance,
HTML supports gif and jpeg while the LaTeX back-end
only supports ps. Scribe tries, only when needed, to automatically
convert images to the format supported by the format of the target
to be produced. For this, it uses external tools. The default Scribe
translation scheme is:
- Do not translate an image that
needs no conversion.
- Uses the
fig2dev external
tool to translate Xfig images.
- Uses the
convert external
tools to translate all other formats.
The way Scribe converts images can be
customized. See the
Scribe Programming Manual.
| (color [:bg #f] [:fg #f] [:width #f] [:margin #f] . body) | Scribe function |
| argument | description |
|---|
| :bg | The optional background color. |
| :fg | The optional foreground color. |
| :width | The percentage of the horizontal space the color box
should occupy. |
| :margin | The margins of the box. |
The example:
(center (color :bg "#eeeeee" :fg "blue" :width 0.3 :margin 10 (p [This is an
example of color box that uses a color for the
background ,(emph "and") the foreground. It also specifies
a width, that is, an horizontal space, the text should
span to.]))) |
produces:
|
This is an
example of color box that uses a color for the
background and the foreground. It also specifies
a width, that is, an horizontal space, the text should
span to.
|
|
| (frame [:width #f] [:margin #f] . body) | Scribe function |
| argument | description |
|---|
| :width | The percentage of the horizontal space the frame should occupy. |
| :margin | The margins of the frame. |
The example:
(center (frame :width 0.3 :margin 10 (p [This is a frame.]))) |
produces:
| (figure :legend [:id #f] [:number #f] [:multicolumns #f] . body) | Scribe function |
| argument | description |
|---|
| :legend | A mandatory argument that is the figure legend. |
| :mark | An optional argument which is an
identifier (a character string) that may be used to refer to that
figure (see the ref function). |
| :number | If the optional argument :number is a number,
that number is used as the new Scribe compiler figure counter. If it
is #t the compiler automatically sets a number for that figure. If it
is #f the figure is numberless. |
| :multicolumns | A boolean that indicates, for back-ends supporting
multi-column rendering (e.g., TeX), if the figure spans over all
the columns. |
| body | The body of the figure. |
The example:
(center (figure :legend "This is a numbered figure" :id "daemon" (image :file "bsd.gif")))
(center (figure :legend "This is an unnumbered figure" :number #f (image :file "linux.gif"))) |
produces:
Fig. 1: This is a numbered figure
This is an unnumbered figure
|
| (char val) | Scribe function |
Introduces a character in the produced document. The purpose
of this function is to introduce escape characters or to introduce
characters that cannot be typesetted in the document (for instance because
the editors does not support them). The escapes characters are
[, ] and ;.
| argument | description |
|---|
| char | A representation of the character to be introduced. This can
be:
- A integer, which is the code of the character.
- A character.
- A string of one length 1.
|
| (copyright) | Scribe function |
These functions introduce special characters in the output text.
The example:
(itemize (item [The copyright sign: ,(copyright)])
(item [The character whose code is 65: ,(char 65)])
(item [The semi-comma character: ,(char 59)])
(item [The right angle character: ,(char 93)])) |
produces:
- The copyright sign: ©
- The character whose code is 65: A
- The semi-comma character: ;
- The right angle character: ]
|
| (footnote :note [:number #f] . body) | Scribe function |
The argument :note is the text that must appear in the
footnote. The body is the text for which the footnote
is attached. The optional argument :number can be
used to set the Scribe compiler footnote counter to a user value.
The example:
(footnote :note [And a great one!] [Scheme is a programming language.]) |
produces:
| (table [:border #f] [:width #f] [:cellpadding 0] [:cellspacing -1] . rows) | Scribe function |
| argument | description |
|---|
| :border | If the :border value is an integer, that number
specifies the border width of the table. |
| :width | If the :width value is an integer, it specifies
the pixel width of the table. If it is a floating pointer number it is
the percentage of the horizontal space the table will expand to. If no
:width value is provided the table expands if needed. |
| :cellpadding | A number of pixels around each cell. |
| :cellspacing | An optional number of pixels used to separate each
cell of the table. A negative uses the back-end default. |
| rows | The rows of the table. Each row must be constructed by
the tr Scribe function. |
| (tr [:bg #f] . cells) | Scribe function |
| argument | description |
|---|
| :bg | The background color of the table row. |
| cells | The cells of the table row. Each cell must be constructed
with either a table data introduced by the
td Scribe function or a table header,
introduced by the th Scribe function. |
| (td [:width #f] [:align "center"] [:valign "center"] [:bg #f] [:rowspan 1] [:colspan 1] . body) | Scribe function |
| (th [:width #f] [:align "center"] [:valign "center"] [:bg #f] [:rowspan 1] [:colspan 1] . body) | Scribe function |
| argument | description |
|---|
| :width | The width of the table row cell. The value can be an integer
or a floating point number. |
| :align | The horizontal alignment of the cell. The value can
be "center", "left" or "right". |
| :valign | The vertical alignment of the cell. The value can
be "top", "center", "bottom". |
| :bg | The background color of the cell. |
| :rowspan | The number of rows that the cell expands to. |
| :colspan | The number of columns that the cell expands to. |
| body | The text of the cell. |
The example:
(center
(table :border 1 :width 0.5
(tr :bg "#cccccc" (th :align 'center :colspan 3 "The table title"))
(tr (th "Col 1") (th "Col 2") (th "Col 3"))
(tr (td :align 'center "10") (td "-20") (td "30"))
(tr (td :align 'right :rowspan 2 :valign 'center "12") (td "21"))
(tr (td :align 'center :colspan 2 "1234") (td))
(tr (td :align 'center :colspan 2 "1234") (td :align 'right "5"))
(tr (td :align 'center :colspan 1 "1") (td :colspan 2 "2345")))) |
produces:
| The table title |
|---|
| Col 1 | Col 2 | Col 3 |
|---|
| 10 | -20 | 30 |
| 12 | 21 |
| 1234 | |
| 1234 | 5 |
| 1 | 2345 |
|
1: The
chapter :file argument is only used by
the Scribe HTML back-end.
2: And a great one!
|