;*=====================================================================*/
;*    serrano/prgm/project/skribe/doc/user/markup.skb                  */
;*    -------------------------------------------------------------    */
;*    Author      :  Manuel Serrano                                    */
;*    Creation    :  Tue Sep  2 06:09:18 2003                          */
;*    Last change :  Wed Feb  4 06:11:45 2004 (serrano)                */
;*    Copyright   :  2003-04 Manuel Serrano                            */
;*    -------------------------------------------------------------    */
;*    The Skribe standard markups                                      */
;*=====================================================================*/

;*---------------------------------------------------------------------*/
;*    API                                                              */
;*---------------------------------------------------------------------*/
(chapter :title "Standard Markups" [

This chapter describes the forms composing Skribe texts. In XML/HTML
these forms are called ,(emph "markups"). In LaTeX they are called
,(emph "macros"). In Skribe these forms are called ,(emph
"functions"). In this manual, we will say that we ,(emph "call a
function") when a function is used in a form. The values used in a
function call are named the ,(emph "actual parameters") of the
function or ,(emph "parameters") in short. When calling a function
with parameters we say that we are ,(emph "passing") arguments to the
function.

,(p [ In this documentation function names are typesetted in bold
face. We call a ,(emph "keyword argument"), an argument whose
identifier starts with the ,(tt ":") character. Arguments whose
identifier does not start with this character are called ,(emph "plain
arguments") or ,(emph "arguments") in short. An ,(emph "optional
argument") is represented by a list, starting with the character ,(q
(char 91)) and ending with the character ,(q (char 93)), whose first
element is a keyword argument and the optional second (,(code "#f")
when not specified) 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 ,(emph "mandatory"). If a plain argument is
preceeded with a ,(tt ".")  character, this argument may be used to
accumulate several values. There are two ways to pass actual arguments
to a function.])

,(itemize (item [for keyword arguments: the value of the parameter
must be preceeded by the name of the argument.])
	  (item [for plain arguments: a value is provided.]))

Example: Let us consider the function ,(tt "section") defined as follows:
,(prgm "(section :title [:number #t] [:toc #t] . body)")

,(p [
The argument ,(param :title) is a mandatory keyword argument.
The keyword arguments ,(param :number) and ,(param :toc) are
optional. The plain argument ,(param 'body) is preceeded with a
,(tt ".") character so it may receive several values. All the following
calls are legal ,(tt "section") calls:])

,(prgm (source :file "src/api1.skb"))]

;*---------------------------------------------------------------------*/
;*    Markup index ...                                                 */
;*---------------------------------------------------------------------*/
(section :title "Markup index" :ident "markups-index" :file #f :number #f :toc #t
   (the-index :class 'markup-index 
      :column (if (engine-format? "latex") 2 4)
      :split #f
      *markup-index*))

;*---------------------------------------------------------------------*/
;*    Markups                                                          */
;*---------------------------------------------------------------------*/
;; FIXME: Processors (used by the following files) are broken!
;;(include "document.skb")
;;(include "sectioning.skb")
(include "toc.skb")
(include "ornament.skb")
(include "line.skb")
(include "font.skb")
(include "justify.skb")
(include "enumeration.skb")
(include "colframe.skb")
(include "figure.skb")
(include "image.skb")
(include "table.skb")
(include "footnote.skb")
(include "char.skb"))