doc: Update "Standard Packages" section.

* TODO: Add new item.

* doc/user/package.skb (Standard Packages): Remove references to
  `skribe-load', mention `use-modules'.
  [Web](web-article): Commented out since it sucks.

* src/guile/skribilo/package/web-article.scm: Add FIXMEs.

3 files changed, 72 insertions, 38 deletions

diff --git a/TODO b/TODO
index fe405c5..4328be3 100644
--- a/TODO
+++ b/TODO
@@ -21,6 +21,14 @@ Expressions like `(if (engine-format? "lout") xxx yyy)' are wrong,
 because they look at the value of `*current-engine*' rather than the
 engine actually used during resolution and output.
 
+** Find a clean way to have packages customize engines
+Currently, most packages have side-effects at `use-modules'-time, e.g.,
+they `engine-custom-set!' the current engine, which kinda sucks (see,
+e.g., `(skribilo package slide)').
+
+Likewise, there's no replacement for the `*load-options*' mechanism
+implemented by `skribe-load' (see, e.g., `web-article').
+
 ** Write an Info engine based on Scribe's one
 ** Write an XHTML engine
 ** Write a nice GUI based on Andy's STexi browser
diff --git a/doc/user/package.skb b/doc/user/package.skb
index f51dacf..2bfe4e1 100644
--- a/doc/user/package.skb
+++ b/doc/user/package.skb
@@ -1,6 +1,6 @@
 ;;; package.skb  --  Packages
 ;;;
-;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
+;;; Copyright 2007, 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2001, 2004, 2005  Manuel Serrano
 ;;;
 ;;;
@@ -24,28 +24,32 @@
 ;*---------------------------------------------------------------------*/
 (chapter :title "Standard Packages"
    
-   (p [
-This chapter describes the standard Skribe packages. Additional
-packages can be found from the 
-,(ref :url (skribe-url) :text "Skribe web page").
-This chapter only describes the packages that are contained in the standard
-Skribe distribution.])
+   (p [This chapter describes the standard packages that come with
+Skribilo.  Additional packages may be found from the ,(ref :url
+(skribe-url) :text "Skribe web page"), but they may require slight
+modifications to work correctly with Skribilo.])
    
-   (p [
-In order to use the facilities described in the following sections, the 
-Skribe source file must contains expressions such as:])
+   (p [In order to use the facilities described in the following
+sections, the Skribilo source file must contains statements such as:]
 
-(prgm "(skribe-load \"package.skr\" ...)")
+(prgm "(use-modules (skribilo package THE-PACKAGE))")
 
-[where ,(it (tt "package.skr")) is the described package.]
+[where ,(tt "THE-PACKAGE") is the desired package.  GNU Guile users will
+recognize that this is Guile's standard way to use Scheme modules.  The
+effect of the ,(tt [use-modules]) clause is to insert the bindings
+exported by ,(tt "THE-PACKAGE") into the current module's name space.
+Note that third-party Skribilo packages can have arbitrary Guile module
+names.  And of course, the ,(tt [use-modules]) clause can be used to
+import ,(emph [any]) Guile module, not just Skribilo packages.])
 
 ;*---------------------------------------------------------------------*/
 ;*    jfp                                                              */
 ;*---------------------------------------------------------------------*/
 (section :title "Articles"
 
-   (subsection :title (tt "acmproc.skr") :ident "acmproc"
-      (index :index *package-index* "acmproc.skr" :note "package")
+   (subsection :title (tt "acmproc") :ident "acmproc"
+
+      (index :index *package-index* "acmproc" :note "package")
       (p [
 This package enables producing LaTeX documents conforming to the
 ,(emph "ACM proceeding") (ACMPROC) style. It introduces the
@@ -60,8 +64,8 @@ markup ,(code "abstract"):])
 	 :force-engines *api-engines*
 	 :source "skribilo/package/acmproc.scm"))
 
-   (subsection :title (tt "jfp.skr") :ident "jfp"
-      (index :index *package-index* "jfp.skr" :note "package")
+   (subsection :title (tt "jfp") :ident "jfp"
+      (index :index *package-index* "jfp" :note "package")
       (p [
 This package enables producing LaTeX documents conforming to the
 ,(emph "Journal of Functional Programming") (JFP) style. It introduces the
@@ -75,8 +79,8 @@ markup ,(code "abstract"):])
 	 :force-engines *api-engines*
 	 :source "skribilo/package/jfp.scm"))
 
-   (subsection :title (tt "lncs.skr") :ident "lncs"
-      (index :index *package-index* "lncs.skr" :note "package")
+   (subsection :title (tt "lncs") :ident "lncs"
+      (index :index *package-index* "lncs" :note "package")
       (p [
 This package enables producing LaTeX documents conforming to the
 ,(emph "Lecture Notes on Computer Science") (LNCS) style. It introduces the
@@ -105,16 +109,25 @@ markups ,(code "abstract") and ,(code "references"):])
 ;*    french                                                           */
 ;*---------------------------------------------------------------------*/
 (section :title "Languages"
-   (subsection :title (tt "french.skr")
-      (index :index *package-index* "french.skr" :note "package")
+
+   ;; FIXME: Provide proper i18n.
+
+   (p [Currently, native language support in Skribilo is rudimentary,
+limited to the following package.  In the future, it should be possible
+to specify a document's language so that the output engine behaves
+accordingly, e.g., by choosing the right typographical rules and the
+right phrases.])
+
+   (subsection :title (tt "french")
+      (index :index *package-index* "french" :note "package")
       (p [
 Enables French typesetting and typographical rules.])))
 
 ;*---------------------------------------------------------------------*/
 ;*    letter                                                           */
 ;*---------------------------------------------------------------------*/
-(section :title (tt "letter.skr")
-   (index :index *package-index* "letter.skr" :note "package")
+(section :title (tt "letter")
+   (index :index *package-index* "letter" :note "package")
    (p [
 This package is to be used to authoring simple letters. It redefines the
 ,(markup-ref "document") markup.])
@@ -134,30 +147,35 @@ This package is to be used to authoring simple letters. It redefines the
 ;*---------------------------------------------------------------------*/
 (section :title "Web"
    
-   (subsection :title (tt "web-article.skr")
-      (index :index *package-index* "web-article.skr" :note "package")
-      (p [
-A convenient mode for rendering articles (i.e., documents made of
-sections) in HTML. The Slide package supports two ,(markup-ref "skribe-load")
-user options:
-,(param :style) and ,(param :css). The ,(param :style) option can either
-be ,(code "'traditional") which forces traditional HTML code
-emission or ,(code "'css") which forces HTML code emission using CSS
-annotations. The CSS style used is specified in the (code "css")
-HTML engine ,(ref :subsection "The HTML customization" :text "custom").
-The ,(param :css) is a shorthand for ,(param :style). For instance:])
+   #;(subsection :title (tt "web-article")
+      (index :index *package-index* "web-article" :note "package")
+
+      (p [This module provides a convenient mode for rendering articles
+(i.e., documents made of sections) in HTML.])
+      
+      ;; FIXME: We don't have any clean way to pass load options through
+      ;; `use-modules'.
+      (p [The ,(tt [web-article]) package supports two ,(markup-ref
+"skribe-load") user options: ,(param :style) and ,(param :css). The
+,(param :style) option can either be ,(code "'traditional") which forces
+traditional HTML code emission or ,(code "'css") which forces HTML code
+emission using CSS annotations. The CSS style used is specified in the
+(code "css") HTML engine ,(ref :subsection "The HTML customization"
+:text "custom").  The ,(param :css) is a shorthand for ,(param
+:style). For instance:]
 (prgm [(skribe-load "web-article.skr" :css "style.css")])
 [is equivalent to:]
 (prgm [(skribe-load "web-article.skr" :style 'css)
 (engine-custom-set! (find-engine 'html) :css "style.css")]))
+      )
    
-   (subsection :title (tt "web-book.skr")
-      (index :index *package-index* "web-book.skr" :note "package")
+   (subsection :title (tt "web-book")
+      (index :index *package-index* "web-book" :note "package")
       (p [
 A convenient mode for rendering books (i.e., documents made of
 chapters and sections) in HTML.]))
    
-   (subsection :title [HTML Navigation Tabs]
+   (subsection :title (tt [html-navtabs])
 
       (p [The ,(tt [html-navtabs]) package enables quick navigation
 inside HTML documents by means of tabs.  The produced HTML code uses CSS
diff --git a/src/guile/skribilo/package/web-article.scm b/src/guile/skribilo/package/web-article.scm
index 31a88fa..d291c7c 100644
--- a/src/guile/skribilo/package/web-article.scm
+++ b/src/guile/skribilo/package/web-article.scm
@@ -1,7 +1,7 @@
 ;;; web-article.scm  --  A style to produce web articles.
 ;;;
+;;; Copyright 2007, 2008  Ludovic Courtès <ludo@chbouib.org>
 ;;; Copyright 2003, 2004  Manuel Serrano
-;;; Copyright 2007  Ludovic Courtès <ludo@chbouib.org>
 ;;;
 ;;;
 ;;; This program is free software; you can redistribute it and/or modify
@@ -36,6 +36,11 @@
 
 (fluid-set! current-reader %skribilo-module-reader)
 
+;; FIXME: The purpose of this package is unclear, and it relies on "documents
+;; made of sections" (according to the doc), which sucks (we want all
+;; documents to consist of chapters at the top-level, so that engines can at
+;; least assume that), so better not advertise it.
+
 
 ;*---------------------------------------------------------------------*/
 ;*    &web-article-load-options ...                                    */
@@ -242,6 +247,9 @@
 ;*---------------------------------------------------------------------*/
 ;*    Setup ...                                                        */
 ;*---------------------------------------------------------------------*/
+;; FIXME: The `*load-options*' stuff is not usable from `use-modules', so we
+;; must provide another mechanism, e.g., exporting a `customize-engine!'
+;; method or so.
 (let* ((opt &web-article-load-options)
        (p (memq :style opt))
        (css (memq :css opt))