diff options
| -rw-r--r-- | TODO | 8 | ||||
| -rw-r--r-- | doc/user/package.skb | 92 | ||||
| -rw-r--r-- | src/guile/skribilo/package/web-article.scm | 10 |
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)) |