From 1c48e83c54179144b82f8e1323101baf0c6b1a8d Mon Sep 17 00:00:00 2001
From: Ludovic Courtès
Date: Tue, 22 Jan 2008 19:17:15 +0100
Subject: 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.
---
doc/modules/skribilo/documentation/manual.scm | 11 +++++++++++
doc/user/bib.skb | 16 ++++++++++++----
doc/user/image.skb | 23 +++++++++++++++++------
doc/user/lib.skb | 19 ++++++++++++-------
doc/user/prgm.skb | 23 +++++++++++++++++++----
doc/user/skribec.skb | 3 +++
doc/user/user.skb | 1 +
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
@@ -292,6 +292,17 @@
(define-markup (markup-ref mk)
(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 ... */
;*---------------------------------------------------------------------*/
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 */
;*---------------------------------------------------------------------*/
--
cgit v1.2.3