doc: Document all the `*xxx-path*' parameters.

* doc/modules/skribilo/documentation/manual.scm (srfi-ref): New.

* doc/user/bib.skb: Add `*bib-path*'.

* doc/user/image.skb: Add `*image-path*'.

* doc/user/lib.skb: Mention `-I' command-line option for
  `*document-path*'.

* doc/user/prgm.skb: Add `*source-path*'.

* doc/user/skribec.skb: Add `:ident' for chapter.

7 files changed, 75 insertions, 21 deletions

diff --git a/doc/modules/skribilo/documentation/manual.scm b/doc/modules/skribilo/documentation/manual.scm
index 01d2bda..4010982 100644
--- a/doc/modules/skribilo/documentation/manual.scm
+++ b/doc/modules/skribilo/documentation/manual.scm
@@ -293,6 +293,17 @@
    (ref :mark mk :text (code mk)))
 
 ;*---------------------------------------------------------------------*/
+;*    srfi-ref ...                                                     */
+;*---------------------------------------------------------------------*/
+(define-markup (srfi-ref num . text)
+   (ref :url (format #f "http://srfi.schemers.org/srfi-~a/srfi-~a.html"
+                     num num)
+        :text (if (null? text)
+                  (format #f "SRFI-~a" num)
+                  text)))
+
+
+;*---------------------------------------------------------------------*/
 ;*    &the-index ...                                                   */
 ;*---------------------------------------------------------------------*/
 (markup-writer '&the-index
diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index 4ede5fd..f5dde61 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -1,7 +1,7 @@
 ;;; bib.skb  --  The Skribilo bibliography.
 ;;;
+;;; Copyright 2007, 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
-;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
 ;;;
 ;;;
 ;;; This program is free software; you can redistribute it and/or modify
@@ -73,8 +73,7 @@ bibliography-table:])
 	       :common-args '()
                :source #f
                :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")
+   (p [Technically, ,(code "*bib-table*") is actually an ,(srfi-ref 39)
 parameter object, so it can be queried and modified like any other
 parameter object.])
    
@@ -110,7 +109,7 @@ the ,(code "bibliography") Skribe function call before the call to the
 	      (:bib-table ,[The ,(ref :mark "make-bib-table" :text "table") 
                where entry is searched.])
 	      (#!rest entry... ,[If ,(param 'entry) is a string, it denotes
-              a file containing the entry (see ,(ref :mark "skribe-bib-path" 
+              a file containing the entry (see ,(ref :mark "*bib-path*" 
               :text "bibliograph path")). Otherwise, it is a list described
               by the ,(ref :subsection "Bibliography Syntax" :text "syntax") 
               below.]))
@@ -118,6 +117,15 @@ the ,(code "bibliography") Skribe function call before the call to the
 	    :force-engines *api-engines*
 	    :common-args '())
 
+(mark "*bib-path*")
+(p [Files passed as an argument to ,(markup-ref "bibliography") are
+searched in the current ,(emph [bibliography path]), which is defined by
+the ,(tt [*bib-path*]) ,(srfi-ref 39) parameter.  This parameter
+contains a list of directories and its value can be obtained using
+,(code [(*bib-path*)]).  Its value can be altered using the ,(tt
+[-B]) command-line option of the ,(tt [skribilo]) compiler (see ,(numref
+:text [Chapter] :ident "compiler") for details).])
+
 (p [The ,(param :command) option can be used to import foreign bibliography.
 The following example, shows how to directly use a Bibtex bibliography
 using the ,(ref :section "Skribebibtex") translator.])
diff --git a/doc/user/image.skb b/doc/user/image.skb
index f74da22..5af20d8 100644
--- a/doc/user/image.skb
+++ b/doc/user/image.skb
@@ -1,5 +1,6 @@
-;;; image.skb  --  Skribe images
+;;; image.skb  --  Images.
 ;;;
+;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -21,13 +22,13 @@
 ;*---------------------------------------------------------------------*/
 ;*    Image ...  @label image@                                         */
 ;*---------------------------------------------------------------------*/
-(section :title "Image" :file #t
+(section :title "Images" :file #t
 
 (p [Images are defined by the means of the ,(code "image") function])
 
 (doc-markup 'image
 	    `((:file ,[The file where the image is stored on the disk
-                       (see ,(ref :mark "skribe-image-path" 
+                       (see ,(ref :mark "*image-path*" 
 				:text "image path")).
                        The image is converted 
                        (see ,(markup-ref "convert-image")) into a format 
@@ -42,11 +43,21 @@
                         percentage.])
 	      (:zoom [A zoom factor.])
 	      (#!rest comment [A text describing the image.]))
-	    :see-also '(skribe-image-path convert-image))
+	    :see-also '(*image-path* convert-image))
 
 (example-produce
  (example :legend "The image markup" (prgm :file "src/api16.skb"))
  (disp (include "src/api16.skb")))
+   
+(mark "*image-path*")
+(p [Files passed as a ,(tt [:file]) argument to ,(markup-ref "image")
+are searched in the current ,(emph [image path]), which is defined by
+the ,(tt [*image-path*]) ,(srfi-ref 39) parameter.  This parameter
+contains a list of directories and its value can be obtained using
+,(code [(*image-path*)]).  Its value can be altered using the ,(tt [-P])
+command-line option of the ,(tt [skribilo]) compiler (see ,(numref :text
+[Chapter] :ident "compiler") for details).])
+
 
 ;*--- Image format ----------------------------------------------------*/
 (subsection :title "Image formats"
@@ -79,12 +90,12 @@ returns the name of the new converted image. On failure, it returns
 ,(code "#f").]) 
    (doc-markup 'convert-image 
 	       `((file [The image file to be converted. The file is
-searched in the ,(ref :mark "skribe-image-path" :text "image path").])
+searched in the ,(ref :mark "*image-path*" :text "image path").])
 		 (formats [A list of formats into which images are converted to.]))
 	       :common-args '()
                :skribe-source? #f
 	       :source #f ;;"skribilo/runtime.scm"
                :def '(define-markup (convert-image file formats) ...)
-	       :see-also '(skribe-image-path)
+	       :see-also '(*image-path*)
 	       :idx *function-index*)))
    
diff --git a/doc/user/lib.skb b/doc/user/lib.skb
index f61382a..dcf8d6e 100644
--- a/doc/user/lib.skb
+++ b/doc/user/lib.skb
@@ -1,6 +1,6 @@
 ;;; lib.skb  --  Standard library.
 ;;;
-;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
+;;; Copyright 2007, 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003  Erick Gallesio <eg@essi.fr>
 ;;;
 ;;;
@@ -53,16 +53,21 @@ when the Skribilo compiler is invoked (see Chapter
                :source #f
                :def '(define (*document-path* #!optional opt) ...)
 	       :common-args '()
-	       :others '()  ;;'(*image-path* *bib-path* *source-path*)
-	       :see-also '(include image source bibliography)
+	       :others '()  
+	       :see-also '(include *image-path* *bib-path* *source-path*)
 	       :idx *function-index*)
    
-   (p [,(tt [*document-path*]) is a procedure as returned by SRFI-39
-,(tt [make-parameter]).  As such, ,(tt [(*document-path*)]) returns the
-current document path, while ,(tt [(*document-path* '("."
+   (index :index *function-index* "skribe-path")
+   (index :index *function-index* "skribe-path-set!")
+
+   (p [,(tt [*document-path*]) is a procedure as returned by ,(srfi-ref
+39) ,(tt [make-parameter]).  As such, ,(tt [(*document-path*)]) returns
+the current document path, while ,(tt [(*document-path* '("."
 "/some/path"))]) changes the value of the current path.  This is
 equivalent to Skribe's ,(tt [skribe-path]) and ,(tt [skribe-path-set!])
-functions.]))
+functions.  The value of ,(tt [*document-path*]) can also be changed
+using the ,(tt [-I]) command-line option of the compiler (see ,(numref
+:text [Chapter] :ident "compiler") for details).]))
 
 
 ;;; Misc   
diff --git a/doc/user/prgm.skb b/doc/user/prgm.skb
index 1007268..95a69bf 100644
--- a/doc/user/prgm.skb
+++ b/doc/user/prgm.skb
@@ -1,5 +1,6 @@
 ;;; prgm.skb  --  Computer programs
 ;;;
+;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -74,7 +75,7 @@ program. It may automatically introduce line numbers.])
 ;*---------------------------------------------------------------------*/
 ;*    Source code ... @label source@                                   */
 ;*---------------------------------------------------------------------*/
-(section :title "Source code"
+(section :title "Source Code"
 
 (p [The ,(code "source") function extracts part of the source code and
 enables ,(emph "fontification"). That is, some words of the program
@@ -84,19 +85,28 @@ can be rendered using different colors or faces.])
 (doc-markup 'source
 	    `((:language ,[The ,(markup-ref "language") of the source code.])
 	      (:file ,[The file containing the actual source code. The file
-               is searched in the ,(markup-ref "skribe-source-path") path.])
+               is searched in the ,(markup-ref "*source-path*") path.])
 	      (:start [A start line number or a start marker.])
 	      (:stop [A stop line number or a stop marker.])
 	      (:definition [The identifier of the definition to extract.])
 	      (:tab [The tabulation width.]))
 	    :common-args '()
 	    :force-engines *api-engines*
-	    :see-also '(prog language ref skribe-source-path))
+	    :see-also '(prog language ref *source-path*))
 ;!source-stop
    
 (example-produce 
  (example :legend "The source markup" (prgm :file "src/prgm2.skb"))
- (disp (include "src/prgm2.skb"))))
+ (disp (include "src/prgm2.skb")))
+
+(mark "*source-path*")
+(p [Files passed as the ,(tt [:file]) argument of ,(markup-ref "source")
+are searched in the current ,(emph [source path]), which is defined by the
+,(tt [*source-path*]) ,(srfi-ref 39) parameter.  This parameter contains
+a list of directories and its value can be obtained using ,(code
+[(*source-path*)]).  Its value can be altered using the ,(tt [-S])
+command-line option of the ,(tt [skribilo]) compiler (see ,(numref :text
+[Chapter] :ident "compiler") for details).]))
 
 ;*---------------------------------------------------------------------*/
 ;*    Language ... @label language@                                    */
@@ -128,3 +138,8 @@ in ,(markup-ref "source") function call.])
      (disp (include "src/prgm3.skb"))))
    (else
     '()))))
+
+;;; Local Variables:
+;;; coding: latin-1
+;;; ispell-local-dictionary: "american"
+;;; End:
diff --git a/doc/user/skribec.skb b/doc/user/skribec.skb
index 9ea2fad..ec83d3d 100644
--- a/doc/user/skribec.skb
+++ b/doc/user/skribec.skb
@@ -1,5 +1,6 @@
 ;;; skribec.skb  --  The Skribe compiler
 ;;;
+;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -22,6 +23,8 @@
 ;*    The Skribe compiler                                              */
 ;*---------------------------------------------------------------------*/
 (chapter :title "Skribe compiler"
+         :ident "compiler"
+
 (index "skribe" :note "manual page")
 (p [
 In this chapter we present the Skribe compiler that compiles Skribe
diff --git a/doc/user/user.skb b/doc/user/user.skb
index 9300e75..b1469d9 100644
--- a/doc/user/user.skb
+++ b/doc/user/user.skb
@@ -51,6 +51,7 @@
    (engine-custom-set! he 'body-width 100.))
 
 
+
 ;*---------------------------------------------------------------------*/
 ;*    The document                                                     */
 ;*---------------------------------------------------------------------*/