aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--TODO8
-rw-r--r--doc/user/package.skb92
-rw-r--r--src/guile/skribilo/package/web-article.scm10
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))