Initial import of Skribe 1.2d.

Initial import of Skribe 1.2d.


git-archimport-id: lcourtes@laas.fr--2004-libre/skribilo--devel--1.2--base-0

1 files changed, 118 insertions, 0 deletions

diff --git a/doc/user/index.skb b/doc/user/index.skb
new file mode 100644
index 0000000..dd5e8fa
--- /dev/null
+++ b/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.])))