summaryrefslogtreecommitdiff
path: root/doc/user/markup.skb
blob: 0348325a943840b226da363e31c4a6120477bc5b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
;;; markup.skb  --  The Skribe standard markups
;;;
;;; Copyright 2003, 2004  Manuel Serrano
;;;
;;;
;;; This program 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 2 of the License, or
;;; (at your option) any later version.
;;;
;;; This program 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 this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.

;*---------------------------------------------------------------------*/
;*    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                                                          */
;*---------------------------------------------------------------------*/
(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"))