aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/user/bib.skb20
-rw-r--r--doc/user/char.skb1
-rw-r--r--doc/user/eq.skb52
-rw-r--r--doc/user/links.skb24
-rw-r--r--doc/user/prgm.skb2
-rw-r--r--doc/user/slide.skb6
-rw-r--r--doc/user/src/eq3.skb38
-rw-r--r--doc/user/src/links1.skb4
-rw-r--r--doc/user/src/prgm2.skb4
9 files changed, 130 insertions, 21 deletions
diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index 5b26417..e7b5b77 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -52,32 +52,36 @@ tables.])
(p [The predicate ,(code "bib-table?") returns ,(code "#t") if and only
if its argument is a bibliography table as returned by
-,(markup-ref "make-bib-table") or ,(markup-ref "default-bib-table"). Otherwise
+,(markup-ref "make-bib-table") or ,(markup-ref "*bib-table*"). Otherwise
,(code "bib-table?") returns ,(code "#f").])
(doc-markup 'bib-table?
'((obj [The value to be tested]))
- :see-also '(make-bib-table default-bib-table bibliography the-bibliography)
+ :see-also '(make-bib-table *bib-table* bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
:source #f ;;"skribilo/biblio.scm"
:def '(define-markup (bib-table? obj) ...))
- (p [The function ,(code "default-bib-table") returns a global, pre-existing
+ (p [The function ,(code "*bib-table*") returns a global, pre-existing
bibliography-table:])
- (doc-markup 'default-bib-table
+ (doc-markup '*bib-table*
'()
:see-also '(bib-table? make-bib-table bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
:source #f
- :def '(define-markup (default-bib-table) ...))
+ :def '(define-markup (*bib-table*) ...))
+ (p [Technically, ,(code "*bib-table*") is actually an ,(ref :text
+[SRFI-39] :url "http://srfi.schemers.org/srfi-39/srfi-39.html")
+parameter object, so it can be queried and modified like any other
+parameter object.])
(p [The function ,(code "make-bib-table") constructs a new
bibliography-table:])
(doc-markup 'make-bib-table
'((ident [The name of the bibliography table.]))
- :see-also '(bib-table? default-bib-table bibliography the-bibliography)
+ :see-also '(bib-table? *bib-table* bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
:source #f
@@ -109,7 +113,7 @@ the ,(code "bibliography") Skribe function call before the call to the
:text "bibliograph path")). Otherwise, it is a list described
by the ,(ref :subsection "Bibliography syntax" :text "syntax")
below.]))
- :see-also '(bib-table? make-bib-table default-bib-table the-bibliography)
+ :see-also '(bib-table? make-bib-table *bib-table* the-bibliography)
:force-engines *api-engines*
:common-args '())
@@ -161,7 +165,7 @@ Here is an example of a simple Skribe database.])
filtered in by ,(param :pred). The value ,(code "full")
tells Skribe to count all entries, event those filtered out
by ,(param :pred).]))
- :see-also '(bib-table? make-bib-table default-bib-table bibliography)
+ :see-also '(bib-table? make-bib-table *bib-table* bibliography)
:force-engines *api-engines*
:common-args '())
diff --git a/doc/user/char.skb b/doc/user/char.skb
index 16c4625..b2f94e2 100644
--- a/doc/user/char.skb
+++ b/doc/user/char.skb
@@ -67,6 +67,7 @@ are replaced with the actual values of the arguments ,(param 'node).])
;*--- Symbols ---------------------------------------------------------*/
(subsection :title "Symbols"
+ :ident "symbols"
(p [The function ,(code "symbol") introduces special symbols in the
produced file. Note that the rendering of symbols is unportable. It depends
diff --git a/doc/user/eq.skb b/doc/user/eq.skb
index a611f88..fb8c3ef 100644
--- a/doc/user/eq.skb
+++ b/doc/user/eq.skb
@@ -57,7 +57,7 @@ much like any other kind of markup. However, the resulting syntax
is very verbose and hard to read.])
(p [Fortunately, the ,(tt [eq]) package allows for the use of a
-much simple syntax. ]
+much simpler syntax. ]
(example-produce
(example :legend "Example of a simple equation"
@@ -69,10 +69,56 @@ may have already recognized its ,(emph [prefix notation]). Note that,
unlike in the previous example, the equation itself if ,(emph [quoted]),
that is, preceded by the ,(tt [']) sign. Additionally, when referring
to a symbol (such as the Greek letter ,(symbol "phi")), you no longer
-need to use the ,(tt [symbol]) markup (,(ref :text [see subsection]
-:subsection "Symbols")).]))
+need to use the ,(tt [symbol]) markup (,(numref :text [see Section]
+:ident "symbols")).])
+
+ (p [It is possible to create ,(emph [equation display blocks]),
+where several equations are displayed and aligned according to a
+particular operator. ]
+
+ (example-produce
+ (example :legend "Inlined, displayed, and aligned equations"
+ (prgm :file "src/eq3.skb"))
+ (disp (include "src/eq3.skb")))))
+ ;; FIXME: Write this.
(section :title [Rendering])
+
+ (section :title [Summary]
+
+ (p [The options available for the top-level ,(code [eq]) markup
+are summarized here:])
+
+ (doc-markup 'eq
+ `((:inline? [If ,(code [auto]), Skribilo will
+automatically determine whether the equation is to be "in-line".
+Otherwise, it should be a boolean indicating whether the equation is to
+appear "in-line", i.e., within a paragraph. If the engine supports it,
+it may adjust various parameters such as in-equation spacing
+accordingly.])
+ (:renderer [The engine that should be used to render
+the equation. This allows, for instance, to use the Lout engine to
+render equations in HTML.])
+ (:mul-style [A symbol denoting the default style for
+multiplications. This should be one of ,(code [space]), ,(code
+[cross]), ,(code [asterisk]) or ,(code [dot]).])
+ (:div-style [A symbol denoting the default style for
+divisions. This should be one of ,(code [over]), ,(code [fraction]),
+,(code [div]) and ,(code [slash]). Per-,(code [eq:/]) ,(code
+[:div-style]) options override this setting.])
+ (:align-with [Within a ,(code [eq-display]) block,
+this should be a symbol specifying according to which operator equations
+are to be aligned with one another.]))
+ :source "skribilo/package/eq.scm")
+
+ (p [Equation display blocks can be defined using ,(code
+[eq-display]). Display blocks define the scope of the alignment among
+equations as specified by the ,(code [:align-with]) options of ,(code
+[eq]).])
+
+ (doc-markup 'eq-display
+ `()
+ :source "skribilo/package/eq.scm"))
)
diff --git a/doc/user/links.skb b/doc/user/links.skb
index ae7301c..c6e37a0 100644
--- a/doc/user/links.skb
+++ b/doc/user/links.skb
@@ -71,9 +71,9 @@ automatically sets a mark whose value is the legend of the figure.]))
;*---------------------------------------------------------------------*/
;* ref ... @label ref@ */
;*---------------------------------------------------------------------*/
-(section :title "Reference"
+(section :title "Reference" :ident "refs"
-(p [Skribe proposes only one single function for all the references.
+(p [Skribilo proposes a single function that can be used for most references.
This same ,(code "ref") function is used for introducing references to
section, to bibliographic entries, to source code line number, etc.])
@@ -92,7 +92,8 @@ section, to bibliographic entries, to source code line number, etc.])
(:section [The title of a ,(markup-ref "section").])
(:subsection [The title of a ,(markup-ref "subsection").])
(:subsubsection [The title of a ,(markup-ref "subsubsection").])
- (:page [A boolean enabling/disabling page reference.])
+ (:page [A boolean enabling/disabling page reference (for
+ hard copies as produced by the Lout and LaTeX engines).])
(:bib ,[A name or a list of names of
,(ref :chapter "Bibliographies" :text "bibliographic") entry.])
(:bib-table ,[The
@@ -108,8 +109,21 @@ section, to bibliographic entries, to source code line number, etc.])
a ,(tt "mark") located in the Skribe document
described by the ,(var "file") ,(sc "sui").]))
:force-args '(:url :bib :line :skribe)
- :see-also '(index))
-
+ :see-also '(index numref))
+
+(p [Sometimes, it is useful to produce phrases that refer a section by
+its number, as in ``See Section 2.3''. This is especially useful on
+printed documents, as produced by the Lout and LaTeX engines. The
+,(code "numref") markup is provided to that end:])
+
+(doc-markup 'numref
+ `((:text [Text preceding the reference number.])
+ (:ident [The identifier of the node (a chapter, section,
+ subsection, etc.) being referenced.])
+ (:page [A boolean enabling/disabling page reference (for
+ hard copies as produced by the Lout and LaTeX engines).])
+ (:separator [The separator between numbers.]))
+ :see-also '(ref))
(example-produce
(example :legend "Some references" (prgm :file "src/links1.skb"))
diff --git a/doc/user/prgm.skb b/doc/user/prgm.skb
index 6fb44c9..1007268 100644
--- a/doc/user/prgm.skb
+++ b/doc/user/prgm.skb
@@ -29,7 +29,7 @@
;*---------------------------------------------------------------------*/
;* Computer programs */
;*---------------------------------------------------------------------*/
-(chapter :title "Computer programs"
+(chapter :title "Computer Programs"
(p [It is common that some parts of a Skribe text represent other
texts. For instance, for a document describing a computer programming
diff --git a/doc/user/slide.skb b/doc/user/slide.skb
index a381e04..35332f2 100644
--- a/doc/user/slide.skb
+++ b/doc/user/slide.skb
@@ -153,6 +153,8 @@ projection. This may not be supported by all engines.])
(doc-markup 'slide-embed
`((:command [The binary file for running the embedded
application.])
+ (:arguments [Additional arguments to be passed to the
+application (a list of strings).])
(:geometry-opt [The name of the geometry option to be sent
to the embedded application.])
(:geometry [The geometry value to be sent.])
@@ -192,8 +194,8 @@ output format does not support embedded application.]))
(markup-writer 'slide-vspace e
:options '(:alt)
:action dummy-slide-vspace-output)
- (markup-writer 'slide-embed e
- :options '(:alt)
+ (markup-writer 'slide-embed
+ :options '(:command :arguments :alt)
:action dummy-slide-embed-output)
e))
(include "src/slides.skb"))))
diff --git a/doc/user/src/eq3.skb b/doc/user/src/eq3.skb
new file mode 100644
index 0000000..e229b6c
--- /dev/null
+++ b/doc/user/src/eq3.skb
@@ -0,0 +1,38 @@
+(p [This paragraph contains this equation: ,(eq :inline? #t '(/ alpha
+beta)). This is actually an ,(emph [inline]) equation, meaning that it
+occurs within a paragraph. Typesetting has to be adjusted
+accordingly.])
+
+(eq-display
+
+ (p [This is an equation display block, within which equations can be
+aligned with one another.])
+
+ (eq :ident "eq-limit-b-over-l"
+ :renderer 'lout
+ :align-with '=
+ '(= (limit (/ lambda beta) 0
+ (apply IPL n k))
+
+ ;; non-simplified
+ (/ (expt (+ alpha beta) k)
+ (* beta
+ (sum :from (= x 0)
+ :to (- k 1)
+ (* (combinations k x)
+ (expt beta (- k 1 x))
+ (expt alpha x)))))))
+
+ [This equation can be simplified as follows:]
+
+ (eq :ident "eq-limit-b-over-l-simplified"
+ :renderer 'lout
+ :align-with '=
+ '(= ;; simplified
+ (/ (expt (+ alpha beta) k)
+ (- (expt (+ alpha beta) k)
+ (expt alpha k)))
+
+ (limit (/ lambda beta) 0
+ (apply IPL n k)))))
+
diff --git a/doc/user/src/links1.skb b/doc/user/src/links1.skb
index e0b393b..bfe6f86 100644
--- a/doc/user/src/links1.skb
+++ b/doc/user/src/links1.skb
@@ -11,6 +11,10 @@ That other one points to a well known
,(code ":text"): ,(ref :url "http://slashdot.org/").
,(linebreak)
+And one can also refer to sections by number, as in ``see ,(numref :text
+[Wonderful Section] :ident "refs")''.
+
+,(linebreak)
With more complex tricks that are explained in Section
,(ref :section "Resolve"), it is also possible use, for the text of the
reference, a container number such as chapter:
diff --git a/doc/user/src/prgm2.skb b/doc/user/src/prgm2.skb
index 5b5644b..2996cc8 100644
--- a/doc/user/src/prgm2.skb
+++ b/doc/user/src/prgm2.skb
@@ -5,8 +5,8 @@
;!start
(frame :width 100.
- (prog :line 11 :mark #f
- (source :language skribe :file "prgm.skb" :start 11 :stop 24)))
+ (prog :line 21 :mark #f
+ (source :language skribe :file "prgm.skb" :start 20 :stop 27)))
;!stop
(p [Here is the source of the frame above:])