diff options
Diffstat (limited to 'skribe/doc/user/index.skb')
| -rw-r--r-- | skribe/doc/user/index.skb | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/skribe/doc/user/index.skb b/skribe/doc/user/index.skb new file mode 100644 index 0000000..dd5e8fa --- /dev/null +++ b/skribe/doc/user/index.skb @@ -0,0 +1,118 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/index.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Sun Dec 2 10:02:56 2001 */ +;* Last change : Mon Feb 23 18:59:00 2004 (eg) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Skribe indexes */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* Index */ +;*---------------------------------------------------------------------*/ +(chapter :title "Indexes" (p [ +Skribe support indexes. One may accumulate all entries inside one +unique index or dispatch them amongst user declared indexes. Indexes +may be ,(emph "monolithic") or ,(emph "split"). They only differ in +the way they are rendered by the back-ends. For a split index a sectioning +based on the specific (e.g., "the first one") character of +index entries is deployed.]) + +;*---------------------------------------------------------------------*/ +;* make-index ... @label make-index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Making indexes" + +(p [The function ,(code "make-index") declares a new index.]) + +(doc-markup 'make-index + '((ident "A string, the name the index (currently unused).")) + :common-args '() + :see-also '(default-index index the-index ref mark)) + +(p [For instance, the following Skribe expression declares an index named +,(tt "*index1*"):]) + +(example-produce + (example :legend "Creation of a new index" (prgm :file "src/index1.skb"))) + +(include "src/index1.skb") + +(p [This example produces no output but enables entries to be added to that +index. In general it is convenient to declare indexes ,(emph "before") +the call to the ,(markup-ref "document") function.]) + +(p [The function ,(code "default-index") returns the default index +that pre-exists to all execution.]) + +(doc-markup 'default-index + '() + :common-args '() + :source "src/common/index.scm")) + +;*---------------------------------------------------------------------*/ +;* Index ... @label index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Adding entries to an index" + +(p [The function ,(code "index") adds a new entry into one existing +index and sets a mark in the text where the index will point to. It is +an error to add an entry into an index that is not already declared.]) + +(doc-markup 'index + '((:index [The name of the index whose index entry belongs to. + A value of ,(tt "#f") means that the + ,(markup-ref :mark "default-index") owns this entry.]) + (:note [An optional note added to the index entry. This note + will be displayed in the index printing.]) + (:shape [An optional shape to be used for rendering the entry.]) + (:url [An optional URL that is referenced in the index table + instead of the location of the ,(code "index").]) + (#!rest name [The name of the entry. This must be a string.])) + :see-also '(make-index default-index the-index)) + +(p [The following expressions add entries to the index ,(code "*index1*"):]) + +(example-produce + (example :legend "Adding entries to an index" (prgm :file "src/index2.skb"))) + +(include "src/index2.skb") + +(p [There is no output associated with these expressions.])) + +;*---------------------------------------------------------------------*/ +;* Print-index ... @label the-index@ */ +;*---------------------------------------------------------------------*/ +(section :title "Printing indexes" + + (p [The function ,(code "the-index") displays indexes in the produced +document.]) + + (doc-markup 'the-index + '((:split [If ,(tt "#t"), character based sectioning is deployed. + Otherwise all the index entries are displayed one next to + the other.]) + (:char-offset [The character number to use when split is + required. This option may be useful when printing index whose + items share a common prefix. The ,(param :char-offset) + argument can be used to skip this prefix.]) + (:header-limit [The number of entries from which an index header + is introduced.]) + (:column [The number of columns of the index.]) + (#!rest index... [The indexes to be displayed. If index + is provided, the global index ,(markup-ref "default-index") + is printed.]))) + + (p [If the engine custom +,(ref :chapter "Engines" :text (code "index-page-ref")) is true when a +index is rendered then, page reference framework is used instead of +a direct reference framework.]) + +(example-produce + (example :legend "Printing indexes" (prgm :file "src/index3.skb")) + (disp (include "src/index3.skb"))) + +(p [See the Skribe ,(ref :mark "global index" :text "global index") for +a real life index example.]))) |