More progress towards a working user manual.

* doc/skr/api.skr (define-markup?): Support `define*' and
  `define*-public'.

* doc/user/bib.skb: Commented out problematic `skribebibtex'-related
  things.

* doc/user/lib.skb (skribe-load): Replaced by `load-document'.
  (skribe-load-options): Replaced by `*load-options*'.
  (skribe-path): Replaced by `*document-path*'.

* src/guile/skribilo/coloring/lisp.scm (definition-search): Removed
  debugging statement.

* src/guile/skribilo/engine.scm (find-engine): For documentation
  purposes, explicitly list all keyword parameters.

* src/guile/skribilo/source.scm (source-read-lines): Start line numbers
  from 0.

* src/guile/skribilo/utils/compat.scm (skribe-path-set!): New.
  (skribe-image-path-set!): New.
  (skribe-source-path-set!): New.
  (skribe-bib-path-set!): New.

git-archimport-id: lcourtes@laas.fr--2005-mobile/skribilo--devel--1.2--patch-30

8 files changed, 90 insertions, 34 deletions

diff --git a/ChangeLog b/ChangeLog
index 5ef0b9d..fb6c7ed 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,6 +2,44 @@
 # arch-tag: automatic-ChangeLog--lcourtes@laas.fr--2005-mobile/skribilo--devel--1.2
 #
 
+2006-01-25 22:57:34 GMT	Ludovic Courtes <ludovic.courtes@laas.fr>	patch-30
+
+    Summary:
+      More progress towards a working user manual.
+    Revision:
+      skribilo--devel--1.2--patch-30
+
+    * doc/skr/api.skr (define-markup?): Support `define*' and
+      `define*-public'.
+    
+    * doc/user/bib.skb: Commented out problematic `skribebibtex'-related
+      things.
+    
+    * doc/user/lib.skb (skribe-load): Replaced by `load-document'.
+      (skribe-load-options): Replaced by `*load-options*'.
+      (skribe-path): Replaced by `*document-path*'.
+    
+    * src/guile/skribilo/coloring/lisp.scm (definition-search): Removed
+      debugging statement.
+    
+    * src/guile/skribilo/engine.scm (find-engine): For documentation
+      purposes, explicitly list all keyword parameters.
+    
+    * src/guile/skribilo/source.scm (source-read-lines): Start line numbers
+      from 0.
+    
+    * src/guile/skribilo/utils/compat.scm (skribe-path-set!): New.
+      (skribe-image-path-set!): New.
+      (skribe-source-path-set!): New.
+      (skribe-bib-path-set!): New.
+
+    modified files:
+     ChangeLog doc/skr/api.skr doc/user/bib.skb doc/user/lib.skb
+     src/guile/skribilo/coloring/lisp.scm
+     src/guile/skribilo/engine.scm src/guile/skribilo/source.scm
+     src/guile/skribilo/utils/compat.scm
+
+
 2006-01-24 20:02:40 GMT	Ludovic Courtes <ludovic.courtes@laas.fr>	patch-29
 
     Summary:
diff --git a/doc/skr/api.skr b/doc/skr/api.skr
index ec51e95..00c6a38 100644
--- a/doc/skr/api.skr
+++ b/doc/skr/api.skr
@@ -105,7 +105,7 @@
 ;*---------------------------------------------------------------------*/
 (define (define-markup? id o)
    (match o
-      (((or 'define-markup 'define 'define-public 'define-inline)
+      (((or 'define-markup 'define 'define* 'define-public 'define*-public)
 	((? (lambda (x) (eq? x id)))
 	 . (? (lambda (x) (or (pair? x) (null? x)))))
 	. _)
diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index 83e6360..aa357e8 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -230,9 +230,9 @@ entries identifier. The last one sorts according to entries date.])
 In this section we present the Skribebibtex translator that compiles Bibtex
 source files into a Skribe bibliography.])
 
-;; Synopsis
-(subsection :title "SYNOPSIS" :number #f
-   (compiler-command *skribebibtex-bin* "options" "input"))
+;; Synopsis (FIXME)
+;;(subsection :title "SYNOPSIS" :number #f
+;;   (compiler-command *skribebibtex-bin* "options" "input"))
 
 ;; Description
 (subsection :title "DESCRIPTION" :number #f [
@@ -250,7 +250,9 @@ These suffixes are:
 
 ,(description (item :key (it ".bib") [a ,(bold "Bibtex") source file.]))])
 
-;; Options
-(subsection :title "OPTIONS" :number #f 
-(compiler-options *skribebibtex-bin*))))
+;; Options (FIXME)
+;;(subsection :title "OPTIONS" :number #f 
+;;(compiler-options *skribebibtex-bin*))
+
+   ))
 
diff --git a/doc/user/lib.skb b/doc/user/lib.skb
index e2921fa..3a35687 100644
--- a/doc/user/lib.skb
+++ b/doc/user/lib.skb
@@ -34,26 +34,30 @@ Skribe document (the expressions placed before the ,(markup-ref "document")
 call) contains several ,(code "skribe-load"). The file is search
 in the ,(ref :mark "skribe-path" :text "Skribe path").])
    
-   (doc-markup 'skribe-load
+   (doc-markup 'load-document
 	       `((file [The file containing the expressions to be loaded.])
 		 (:engine [The engine used to evaluate the expressions.])
 		 (:path ,[The optional path where to find the file. The default
                           path is ,(markup-ref "skribe-path").])
 		 (#!rest opt... [Additional user options.]))
-               :skribe-source? #f
-	       :source "skribilo/evaluator.scm"
+               ;;:skribe-source? #f
+	       ;;:source "skribilo/evaluator.scm"
+               :source #f
+      	       :def '(define (load-document file #!rest opt #!key engine path) ...)
 	       :common-args '()
 	       :see-also '(skribe-load-options skribe-path skribe-path-set!)
 	       :idx *function-index*)
    
    (p [Returns the user of options of the last call to 
 ,(markup-ref "skribe-load")])
-   (doc-markup 'skribe-load-options
+   (doc-markup '*load-options*
 	       '()
                :skribe-source? #f-
-	       :source "skribilo/evaluator.scm"
+	       ;;:source "skribilo/evaluator.scm"
+               :source #f
+               :def '(define (*load-options* #!optional opt) ...)
 	       :common-args '()
-	       :see-also '(skribe-load)
+	       :see-also '(load-document)
 	       :idx *function-index*)
    
    (p [Skribe provides functions for dealing with paths. These functions
@@ -61,23 +65,31 @@ are related to the path that can be specified on the command line,
 when the Skribe compiler is invoked (see Chapter 
 ,(ref :chapter "Skribe compiler").)])
    
-   (doc-markup 'skribe-path
+   (doc-markup '*document-path*
 	       '()
-               :skribe-source? #f
-	       :source "skribilo/evaluator.scm"
+               ;;:skribe-source? #f
+	       ;;:source "skribilo/parameters.scm"
+               :source #f
+               :def '(define (*document-path* #!optional opt) ...)
 	       :common-args '()
-	       :others '(skribe-image-path skribe-bib-path skribe-source-path)
-	       :see-also '(include skribe-load image source bibliography skribe-path-set! skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!)
+	       :others '()  ;;'(*image-path* *bib-path* *source-path*)
+	       :see-also '(include-document load-document image source
+bibliography)
 	       :idx *function-index*)
    
-   (p [The function ,(code "skribe-path-set!") sets a new path.])
+   (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* '("."
+"/some/path"))]) changes the value of the current path.  An equivalent
+way to achieve this is by using ,(tt [skribe-path-set!]):])
+
    (doc-markup 'skribe-path-set!
 	       '((path [A list of strings which is the new Skribe search path.]))
                :skribe-source? #f
-	       :source "skribilo/evaluator.scm"
+	       :source "skribilo/utils/compat.scm"
 	       :common-args '()
-	       :others '(skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!)
-	       :see-also '(skribe-path skribe-image-path skribe-bib-path skribe-source-path)
+	       :others '()
+	       :see-also '(*document-path*)
 	       :idx *function-index*))
    
 ;;; Misc   
@@ -103,10 +115,10 @@ Skribe configuration. It can be used to ,(emph "get") or ,(emph "check")
 the configuration.])
    
    (doc-markup 'skribe-configure
-	       '((opt... [Optional arguments.]))
+	       '((#!rest opt... [Optional arguments.]))
 	       :common-args '()
 	       :source #f
-	       :def '(define (skribe-configure . opt...) ...)
+	       :def '(define (skribe-configure #!rest opt...) ...)
 	       :idx *function-index*)
    
    (p [The function ,(code "skribe-configure") can be used in three distinct 
@@ -150,10 +162,10 @@ arguments if the same as that of ,(code "skribe-configure") when invoked
 with several arguments.])
    
    (doc-markup 'skribe-enforce-configure
-	       '((opt... [Optional arguments.]))
+	       '((#!rest opt... [Optional arguments.]))
 	       :common-args '()
 	       :source #f
-	       :def '(define (skribe-enforce-configure . opt...) ...)
+	       :def '(define (skribe-enforce-configure #!rest opt...) ...)
 	       :idx *function-index*))
    
 
diff --git a/src/guile/skribilo/coloring/lisp.scm b/src/guile/skribilo/coloring/lisp.scm
index 33ecc48..1db9a3f 100644
--- a/src/guile/skribilo/coloring/lisp.scm
+++ b/src/guile/skribilo/coloring/lisp.scm
@@ -55,8 +55,6 @@
       (if (def? exp)
 	  (let ((start (and (pair? exp) (source-property exp 'line)))
 		(stop  (port-line inp)))
-	    (format (current-error-port) "READ-LINES: `~a' ~a->~a~%"
-		    exp start stop)
 	    (source-read-lines (port-filename inp) start stop tab))
 	  (Loop (read inp))))))
 
diff --git a/src/guile/skribilo/engine.scm b/src/guile/skribilo/engine.scm
index 7c1348b..d747ea0 100644
--- a/src/guile/skribilo/engine.scm
+++ b/src/guile/skribilo/engine.scm
@@ -143,7 +143,7 @@
 ;;;
 ;;; MAKE-ENGINE
 ;;;
-(define* (make-engine ident #:key (version 'unspecified)
+(define* (make-engine ident :key (version 'unspecified)
 				(format "raw")
 				(filter #f)
 				(delegate #f)
@@ -163,7 +163,7 @@
 ;;;
 ;;; COPY-ENGINE
 ;;;
-(define* (copy-engine ident e #:key (version 'unspecified)
+(define* (copy-engine ident e :key (version 'unspecified)
 				  (filter #f)
 				  (delegate #f)
 				  (symbol-table #f)
@@ -184,7 +184,7 @@
 ;;;	FIND-ENGINE
 ;;;
 
-(define* (lookup-engine id #:key (version 'unspecified))
+(define* (lookup-engine id :key (version 'unspecified))
   "Look for an engine named @var{name} (a symbol) in the @code{(skribilo
 engine)} module hierarchy.  If no such engine was found, an error is raised,
 otherwise the requested engine is returned."
@@ -197,8 +197,8 @@ otherwise the requested engine is returned."
 	   (module-ref m engine)
 	   (error "no such engine" id)))))
 
-(define (find-engine . args)
-  (false-if-exception (apply lookup-engine args)))
+(define* (find-engine id :key (version 'unspecified))
+  (false-if-exception (apply lookup-engine (list id version))))
 
 
 
diff --git a/src/guile/skribilo/source.scm b/src/guile/skribilo/source.scm
index a632f18..4027372 100644
--- a/src/guile/skribilo/source.scm
+++ b/src/guile/skribilo/source.scm
@@ -68,7 +68,7 @@
 		(format (current-error-port) "  [source file: ~S]\n" p))
 	    (let ((startl (if (string? start) (string-length start) -1))
 		  (stopl  (if (string? stop)  (string-length stop)  -1)))
-	      (let loop ((l      1)
+	      (let loop ((l      0) ;; In Guile, line nums are 0-origined.
 			 (armedp (not (or (integer? start) (string? start))))
 			 (s      (read-line))
 			 (r      '()))
diff --git a/src/guile/skribilo/utils/compat.scm b/src/guile/skribilo/utils/compat.scm
index c6e95bf..a7ce781 100644
--- a/src/guile/skribilo/utils/compat.scm
+++ b/src/guile/skribilo/utils/compat.scm
@@ -109,6 +109,12 @@
 (define-public skribe-source-path *source-path*)
 (define-public skribe-bib-path    *bib-path*)
 
+(define-public (skribe-path-set! path)        (*document-path* path))
+(define-public (skribe-image-path-set! path)  (*image-path* path))
+(define-public (skribe-source-path-set! path) (*source-path* path))
+(define-public (skribe-bib-path-set! path)    (*bib-path* path))
+
+
 
 ;;;
 ;;; Evaluator.