diff options
| -rw-r--r-- | doc/user/Makefile.am | 10 | ||||
| -rw-r--r-- | doc/user/lib.skb | 166 | ||||
| -rw-r--r-- | doc/user/skribe-config.skb | 55 | ||||
| -rw-r--r-- | doc/user/skribilo-config.skb | 66 | ||||
| -rw-r--r-- | doc/user/user.skb | 9 |
5 files changed, 128 insertions, 178 deletions
diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am index 1526813..d71c5a4 100644 --- a/doc/user/Makefile.am +++ b/doc/user/Makefile.am @@ -4,7 +4,7 @@ EXTRA_DIST = bib.skb char.skb colframe.skb document.skb emacs.skb \ font.skb footnote.skb htmle.skb image.skb index.skb \ justify.skb latexe.skb lib.skb line.skb links.skb \ markup.skb ornament.skb package.skb pie.skb prgm.skb sectioning.skb \ - skribe-config.skb skribec.skb skribeinfo.skb slide.skb spacing.skb \ + skribilo-config.skb skribec.skb skribeinfo.skb slide.skb spacing.skb \ start.skb syntax.skb table.skb toc.skb user.skb xmle.skb \ lout/book-style.lout @@ -28,9 +28,11 @@ html_DATA = user.html CLEANFILES = $(BUILT_SOURCES) $(html_DATA) skribilo = $(top_builddir)/src/pre-inst-skribilo -skrflags = -I $(srcdir) -P $(top_srcdir)/doc/img \ - -S $(srcdir) -S $(top_srcdir)/src/guile \ - -B $(srcdir) +skrflags = -I $(srcdir) -P $(top_srcdir)/doc/img \ + -S $(srcdir) -S $(top_srcdir)/src/guile \ + -B $(srcdir) \ + -e '(define %top-srcdir "$(top_srcdir)")' \ + -e '(define %top-builddir "$(top_builddir)")' skrflags += --compat=skribe load_path = $(top_srcdir)/doc/modules diff --git a/doc/user/lib.skb b/doc/user/lib.skb index 0cdfe80..f61382a 100644 --- a/doc/user/lib.skb +++ b/doc/user/lib.skb @@ -1,5 +1,6 @@ ;;; lib.skb -- Standard library. ;;; +;;; Copyright 2007 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2003 Erick Gallesio <eg@essi.fr> ;;; ;;; @@ -20,10 +21,11 @@ (chapter :title "Standard Library" - (p [This section describes the Skribe standard library]) + (p [This section describes Skribilo's standard library.]) + ;;; -(section :title "File functions" +(section :title "File Functions" (p [The function ,(code "include") is particularily useful to spread a long document amongst several files.]) @@ -33,47 +35,15 @@ long document amongst several files.]) These nodes are included in the document in place of the ,(code "include") call.])) :common-args '() - :see-also '(skribe-load skribe-path skribe-path-set!) + :see-also '(*document-path*) :idx *function-index*) - (p [The given file is searched in the current -,(ref :mark "skribe-path" :text "Skribe path")]) - - (p [The function ,(code "skribe-load") is generally used to load in the -Skribe memory, a package or an extension. In general the prelude of a -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").]) + (p [The given file is searched in the current ,(ref :mark +"*document-path*" :text "document path").]) - (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" - :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 '*load-options* - '() - :skribe-source? #f- - ;;:source "skribilo/evaluator.scm" - :source #f - :def '(define (*load-options* #!optional opt) ...) - :common-args '() - :see-also '(load-document) - :idx *function-index*) - - (p [Skribe provides functions for dealing with paths. These functions + (p [Skribilo provides functions to deal with paths. These functions are related to the path that can be specified on the command line, -when the Skribe compiler is invoked (see Chapter +when the Skribilo compiler is invoked (see Chapter ,(ref :chapter "Skribe compiler").)]) (doc-markup '*document-path* @@ -84,100 +54,62 @@ when the Skribe compiler is invoked (see Chapter :def '(define (*document-path* #!optional opt) ...) :common-args '() :others '() ;;'(*image-path* *bib-path* *source-path*) - :see-also '(include-document load-document image source -bibliography) + :see-also '(include image source bibliography) :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* '("." -"/some/path"))]) changes the value of the current path. An equivalent -way to achieve this is by using ,(tt [skribe-path-set!]):]) +"/some/path"))]) changes the value of the current path. This is +equivalent to Skribe's ,(tt [skribe-path]) and ,(tt [skribe-path-set!]) +functions.])) - (doc-markup 'skribe-path-set! - '((path [A list of strings which is the new Skribe search path.])) - :skribe-source? #f - :source "skribilo/utils/compat.scm" - :common-args '() - :others '() - :see-also '(*document-path*) - :idx *function-index*)) - + ;;; Misc -(section :title "Misc. Functions" +(section :title "Configuration Functions" + :ident "config-module" - (p [The function ,(code "skribe-release") returns the Skribe version -as a string]) - (doc-markup 'skribe-release + (p [Several functions describing the configuration of Skribilo are +exported by the ,(code [(skribilo config)]) module. First, the ,(code +"skribilo-version") function returns the version of Skribilo being used +as a string.] + + (doc-markup 'skribilo-version '() :common-args '() - :source #f - :def '(define (skribe-release) ...) - :idx *function-index*) + :source "skribilo/config.scm" + :idx *function-index*)) (p [For instance, the following piece of code:]) - (prgm :language skribe - "[This manual documents the ,(bold (skribe-release)) Skribe release]") + (prgm :language skribe + "[This manual documents version ,(bold (skribilo-version)) of Skribilo.]") (p [produces the following output]) - (disp [This manual documents the ,(bold (skribe-release)) Skribe release])) - - (p [The function ,(code "skribe-configure") accesses the whole -Skribe configuration. It can be used to ,(emph "get") or ,(emph "check") -the configuration.]) - - (doc-markup 'skribe-configure - '((#!rest opt... [Optional arguments.])) - :common-args '() - :source #f - :def '(define (skribe-configure #!rest opt...) ...) - :idx *function-index*) - - (p [The function ,(code "skribe-configure") can be used in three distinct -ways depending on the number of provided arguments:]) - - (enumerate - (item [If no argument is provided, ,(code "skribe-configure") returns -a fresh list of Skribe configuration.]) - (item [If one keyword argument is provided, ,(code "skribe-configure") -returns the value associated with this keyword in the configuration list. -If this value does not exist, it returns the symbol ,(code "void").]) - (item [(code "skribe-configure") is invoked with a list composed -of ,(emph "keyword") ,(emph "value"). The actual configuration is checked -against the provided values. Values are compared with ,(code "equal") except -if the value to check has to be compared with a procedure. In that particular -case the value of the check is the value produces by ,(emph "applying") the -function to the actual value. The result of ,(code "skribe-configure") is a -boolean.])) + (disp [This manual documents version ,(bold (skribilo-version)) of Skribilo.]) - (p [Here are some examples.]) - (prgm :language skribe [ -;; fetch the whole configuration list -(skribe-configure) - -;; fetch the release number -(skribe-configure :release) - -;; test if the release number is 1.0b -(skribe-configure :release "1.0b") - -;; test if the release number is greater or equal than "1.0b" -(skribe-configure :release (lambda (v) (string>=? v "1.0b"))) - -;; test if the release number is greater or equal than "1.0b" -;; and the implementation is bigloo -(skribe-configure :release (lambda (v) (string>=? v "1.0b")) :scheme "bigloo")]) + (p [The ,(code "skribilo-url") function returns, not surprisingly, +the URL of the project:] - (p [The function ,(code "skribe-enforce-configure") checks for the Skribe -configuration. In case of mismatch, it raises an error. The syntax of the -arguments if the same as that of ,(code "skribe-configure") when invoked -with several arguments.]) + (doc-markup 'skribilo-url + '() + :common-args '() + :source "skribilo/config.scm" + :idx *function-index*)) - (doc-markup 'skribe-enforce-configure - '((#!rest opt... [Optional arguments.])) + (p [The ,(code [skribilo-module-directory]) returns the directory +under which Skribilo modules were installed:] + + (doc-markup 'skribilo-module-directory + '() :common-args '() - :source #f - :def '(define (skribe-enforce-configure #!rest opt...) ...) - :idx *function-index*)) - + :source "skribilo/config.scm" + :idx *function-index*) + + [Similar information can be obtained using the ,(code +[skribilo-config]) program, as described in ,(numref :text [Section] +:ident "skribilo-config").]))) +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/skribe-config.skb b/doc/user/skribe-config.skb deleted file mode 100644 index 7c5e4bb..0000000 --- a/doc/user/skribe-config.skb +++ /dev/null @@ -1,55 +0,0 @@ -;;; skribe-config.skb -- The skribe-config tool -;;; -;;; Copyright 2004 Manuel Serrano -;;; -;;; -;;; This program 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 2 of the License, or -;;; (at your option) any later version. -;;; -;;; This program 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 this program; if not, write to the Free Software -;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, -;;; USA. - -;*---------------------------------------------------------------------*/ -;* The skribe-config tool */ -;*---------------------------------------------------------------------*/ -(chapter :title "Getting Skribe configuration information" -(index "skribe-config") - -(p [ -In this chapter we present ,(code "skribe-config") that gives -information about the current Skribe configuration.]) - -;; Synopsis -(section :title "SYNOPSIS" :number #f -(compiler-command "skribe-config" "options")) - -;; Description -(section :title "DESCRIPTION" :number #f [ -The ,(code "skribe-config") gives information about the Skribe configuration. -This information can be the directories used to install Skribe, the Scheme -implementation used for compiling Skribe, etc.]) - -;; Options (FIXME) -; (section :title "OPTIONS" :number #f [ -; ,(pre (let* ((proc (run-process "../etc/skribe-config" "--help" error: pipe:)) -; (port (process-error-port proc))) -; (let loop ((line (read-line port)) -; (lines '())) -; (if (eof-object? line) -; (reverse! lines) -; (begin -; (loop (read-line port) (cons* line "\n" lines)))))))]) - -) - - - diff --git a/doc/user/skribilo-config.skb b/doc/user/skribilo-config.skb new file mode 100644 index 0000000..1016a50 --- /dev/null +++ b/doc/user/skribilo-config.skb @@ -0,0 +1,66 @@ +;;; skribilo-config.skb -- The `skribilo-config' tool +;;; +;;; Copyright 2007 Ludovic Courtès <ludo@gnu.org> +;;; Copyright 2004 Manuel Serrano +;;; +;;; +;;; This program 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 2 of the License, or +;;; (at your option) any later version. +;;; +;;; This program 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 this program; if not, write to the Free Software +;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +;;; USA. + +;*---------------------------------------------------------------------*/ +;* The `skribilo-config' tool */ +;*---------------------------------------------------------------------*/ +(chapter :title "Getting Configuration Information" + :ident "skribilo-config" + +(index "skribilo-config") + +(p [This chapter presents ,(code "skribilo-config"), a stand-alone +program that gives information about the current configuration.]) + +;; Synopsis +(section :title "Synopsis" :number #f +(compiler-command "skribilo-config" "options")) + +;; Description +(section :title "Description" :number #f + + [The ,(code "skribilo-config") program gives information about the +Skribilo configuration, such as the module installation path, version +number, etc. The full list of supported options and their meaning is +the following:] + + (linebreak) + + (pre (let ((port (open-input-pipe (string-append %top-builddir + "/src/skribilo-config " + "--help 2>&1")))) + (let loop ((line (read-line port)) + (lines '())) + (if (eof-object? line) + (reverse! lines) + (begin + (loop (read-line port) + (cons* line "\n" lines))))))) + + [Note that the same information can be obtained through the +programming interface exposed by the ,(code [(skribilo config)]) module +(,(numref :text [see Section] :ident "config-module")).])) + + +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/user.skb b/doc/user/user.skb index 38ea61c..f78f1b0 100644 --- a/doc/user/user.skb +++ b/doc/user/user.skb @@ -39,6 +39,11 @@ (load "doc-config.scm") (if %have-ploticus? (set! %ploticus-program %ploticus-path)) + +;; Modules needed, e.g., to get the output of "skribilo-config --help". +(use-modules (ice-9 popen) + (ice-9 rdelim)) + ;*---------------------------------------------------------------------*/ ;* HTML custom */ @@ -172,8 +177,8 @@ as HTML, PostScript, Info pages, etc.]))))) ;;; Packages (include "package.skb") -;;; skribe-config -(include "skribe-config.skb") +;;; skribilo-config +(include "skribilo-config.skb") ;;; List of examples (include "examples.skb") |