;;; index.skb  --  Skribe indexes
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
;;;
;;;
;;; This file is part of Skribilo.
;;;
;;; Skribilo 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 3 of the License, or
;;; (at your option) any later version.
;;;
;;; Skribilo 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 Skribilo.  If not, see <http://www.gnu.org/licenses/>.

;*---------------------------------------------------------------------*/
;*    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 "skribilo/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.])))