3. Scribe User Manual -- Standard Library

3. Scribe User Manual -- Standard Library

Browsing

Home: Scribe User Manual

Previous chapter: Syntax
Next chapter: Hyperlinks and References


Standard Library

Document
Author
Chapter
Sections
Paragraph
Table of contents
Ornaments
Line break
Horizontal rule
Justification
List
Enumerations
Image
Figure
Special characters
Footnote
Table


Chapters

Getting Started
Syntax
Standard Library
Hyperlinks and References
Index
Bibliography
Computer programs
Graphical User Interfaces
Customization
Scribe style files
Editing Scribe Programs
Compiling Scribe programs
Compiling Texi documents
Using Bibtex databases
Functions and Variables


Scribe

Home page:Scribe

Documentation:user
expert


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")

3.1 Document

(document :title [:author '()] . 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...")


3.2 Author

(author :name [: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:

argumentdescription
:nameThe name of the author.
:affiliationHis affiliation, such as a university or a company.
:emailHis email.
:urlHis web page URL.
:phoneHis phone and fax numbers.
:addressHis address.
:photoA picture (see image function 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


3.3 Chapter

(chapter [:title #f] [:subtitle #f] [:number #t] [:toc #t] [:file #t] . body)Scribe function

This function creates a new chapter of a Scribe document. Its arguments are:

argumentdescription
:titleThe title of the chapter.
:subtitleIf 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.
:numberThis 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.
:tocThis argument controls if the chapter must be referenced in the table of contents.
:fileThe 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.

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.])


3.4 Sections

(section :title [:number #t] [:toc #t] . body)Scribe function
(subsection :title [:number #t] [:toc #t] . body)Scribe function
(subsubsection :title [:number #t] . body)Scribe function

argumentdescription
:titleThe mandatory :title is the name of the block (e.g.,the section, subsection or subsubsection)
:numberThis 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.
:tocThis 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])])])


3.5 Paragraph

(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])


3.6 Table of contents

(table-of-contents [:chapter #t] [:section #t])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:

Getting Started
Syntax
Standard Library
Hyperlinks and References
Index
Bibliography
Computer programs
Graphical User Interfaces
Customization
Scribe style files
Editing Scribe Programs
Compiling Scribe programs
Compiling Texi documents
Using Bibtex databases
Functions and Variables


3.7 Ornaments

(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
(sup . body)Scribe function
(sub . body)Scribe function

The example:

(itemize (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 (sup "a superscripts text."))
         (item (sub "a subscripts text."))
         (item (underline (bold (it "an underline, bold, italic text.")))))

produces:

  • 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 superscripts text.
  • a subscripts text.
  • an underline, bold, italic text.


3.8 Line break

(linebreak [num 1])Scribe function

Skip num blank lines.


3.9 Horizontal rule

(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.


3.10 Justification

(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).


3.11 List

(list . items)Scribe function

Constructs a list composed of the items Scribe expressions.


3.12 Enumerations

(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:
    1. One.
    2. Two.
    3. Three.


3.13 Image

(image :file [:width #f] [:height #f] [:zoom #f] . comment)Scribe function

argumentdescription
:fileThe filename where the image is stored on the disk.
:widthThe width of the image. It may be an integer for a pixel size or a floating point number for a percentage.
:heightThe height of the image. It may be an integer for a pixel size or a floating point number for a percentage.
commentA 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:

A first imageA smaller oneA second image


3.14 Figure

(figure :legend [:id #f] [:number #f] . body)Scribe function

argumentdescription
:legendA mandatory argument that is the figure legend.
:markAn optional argument which is an identifier (a character string) that may be used to refer to that figure (see the ref function).
:numberIf 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.
bodyThe 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


3.15 Special characters

(copyright)Scribe function
(space)Scribe function
(tab)Scribe function
(char integer)Scribe function

These functions introduce special characters in the output text. The integer argument of the char function is an integer with the internal code of the character to be displayed. The example:

(itemize (item [The copyright sign: ,(copyright)])
         (item [The character whose code is 65: ,(char 65)]))

produces:

  • The copyright sign: ©
  • The character whose code is 65: A


3.16 Footnote

(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:

Scheme is a programming language.2


3.17 Table

(table [:border #f] [:width #f] [:cellpadding 0] . rows)Scribe function

argumentdescription
:borderIf the :border value is an integer, that number specifies the border width of the table.
:widthIf 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.
:cellpaddingA number of pixels used to separate each cell of the table.
rowsThe rows of the table. Each row must be constructed by the tr Scribe function.

(tr [:bg #f] . cells)Scribe function

argumentdescription
:bgThe background color of the table row.
cellsThe 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

argumentdescription
:widthThe width of the table row cell. The value can be an integer or a floating point number.
:alignThe horizontal alignment of the cell. The value can be "center", "left" or "right".
:valignThe vertical alignment of the cell. The value can be "top", "center", "bottom".
:bgThe background color of the cell.
:rowspanThe number of rows that the cell expands to.
:colspanThe number of columns that the cell expands to.
bodyThe 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"))))

produces:

The table title
Col 1Col 2Col 3
10-2030
1221
1234





1: The chapter :file argument is only used by the Scribe HTML back-end.
2: And a great one!

This
Scribe page is generated by scribeinfo.
Last update Sun Feb 17 11:18:32 2002