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(-) (limited to 'doc') 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 ;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano -;;; Copyright 2007 Ludovic Courtès ;;; ;;; ;;; 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 ;;; 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 +;;; Copyright 2007, 2008 Ludovic Courtès ;;; Copyright 2003 Erick Gallesio ;;; ;;; @@ -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 ;;; 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 ;;; 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