| Send to a friend | PDF | RTF | PS | TXT | Other formats |
In Section 4.2 we copied these .dsl files to the current working directory:
lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl and lyxtox-print-howto.dsl. These control the style of the print formats (i.e. all formats except HTML).
lyxtox-html.dsl: this file controls the HTML output in many HTML files (one HTML file per section).
lyxtox-onehtml.dsl: this file controls the HTML output in one big HTML file (Jade option: nochunks).
Every change you wish to do should normally go in one of these three files - often even to more than one, e.g. when your change affects the HTML output for both one and many files (“chunks”). You should leave the original files that came with the Norman Walsh stylesheets unchanged and put your changes in the above files instead. Technically, this amounts to writing your own “driver” file. This is the easiest way to incorporate your preferences and remain flexible during upgrades.
 |
TXT and HOWTO print targets |
|---|---|
|
Currently, the lyxtox-print-txt.dsl and lyxtox-print-howto.dsl are not used, but are included here for your convenience and for the sake of completeness. You can thus see the common pattern used in all print stylesheets and use it for your own purposes. For the TXT format I currently use the “onehtml” target: after the one, big HTML file has been rendered, Lynx (the text browser) is called with the -dump and -nolist options to create a text version directly from HTML, without any stylesheet for text. Note that, for a very complex document like the PHP-Nuke HOWTO (more than 500 pages, 1000 links to external URLs, 1500 cross-references, 2500 Index entries, 400 files in the “chunked” HTML version), the call to sgmltools with the “-b txt” option breaks with an error (caused probably by too many warnings about cross-references), although it works with smaller and less complex documents. The “howto” print target is not used at all, but is included following the example of the print.dsl file that comes with the original sgmltools package. |
The basic driver file looks like this (see Customizing the Stylesheets):
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY dbstyle SYSTEM "docbook.dsl" CDATA DSSSL> ]> <style-sheet> <style-specification use="docbook"> <style-specification-body> ;; your stuff goes here... </style-specification-body> </style-specification> <external-specification id="docbook" document="dbstyle"> </style-sheet> |
Make sure that you specify, in the system identifier, the full path to the docbook.dsl file that you want to customize; for example, /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/docbook.dsl (this is already done in the stylesheets provided, at least as long as your other settings, like Catalogs (Section 4.5) are correct).
You can add your own definitions, or redefinitions, of stylesheet rules and parameters where
;; your stuff goes here... |
occurs in the example above.
A lot of work, research and experimentation has been invested in the above three stylesheet files, so let's explain some of the most important changes they introduce:
To generate a Table of Contents for articles, %generate-article-toc% has been set to true:
(define %generate-article-toc% ;; Should a Table of Contents be produced for Articles? #t) |
To get a title page for articles, %generate-article-titlepage% has been set to true:
(define %generate-article-titlepage% ;; Should an article title page be produced? #t) |
The CSS has been set to “ck-style.css”:
(define %stylesheet% ;; Name of the stylesheet to use ;; #f) "ck-style.css") |
Note that this setting will be overwritten by the technique described in Chapter 8. You will have to enter the correct CSS in part2 too. The CSS file used here, ck-style.css, is a CSS for DocBook, especially crafted for the classes that appear in the automatically generated HTML code of the DocBook stylesheets. It incorporates some other fine features as well, like an elaborate font-controlling mechanism that passes the accessibility tests (see Chapter 9) and is still browser-independent, or a user-specified icon as a list bullet - up to a rotating globe that appears besides links that do not belong to a user-specifiable “local” domain (i.e. links that point “outside” the document collection currently viewed). The CSS file is discussed in detail in Section 7.1.8.
The width of the table that contains verbatim environments (like program listings) has been set to max. 95%. This is not the same as the value used in the CSS (see Section 7.1.8) for the PRE.SCREEN and PRE.PROGRAMLISTING environments, which should be 100%.
(define ($table-width$)
;; REFENTRY table-width
;; PURP Calculate table width
;; DESC
;; This function is called to calculate the width of tables that should
;; theoretically be "100%" wide. Unfortunately, in HTML, a 100% width
;; table in a list hangs off the right side of the browser window. (Who's
;; mistake was that!). So this function provides a way to massage
;; the width appropriately.
;;
;; This version is fairly dumb.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
(if (has-ancestor-member? (current-node) '("LISTITEM"))
"90%"
"95%"))
|
|
|
“PDF” has been added to the list of mediaobject notations. Otherwise, no images will be displayed in PDF (see also Section 7.2.2):
(define preferred-mediaobject-notations (list "PDF" "EPS" "PS" "JPG" "JPEG" "PNG" "linespecific")) (define preferred-mediaobject-extensions (list "pdf" "eps" "ps" "jpg" "jpeg" "png")) |
The default graphic extension has been changed to “png”:
(define %graphic-default-extension% ;; REFENTRY graphic-default-extension ;; PURP Default extension for graphic FILEREFs ;; DESC ;; The '%graphic-default-extension%' will be ;; added to the end of all 'fileref' filenames on ;; 'Graphic's if they do not end in one of the ;; '%graphic-extensions%'. Set this to '#f' ;; to turn off this feature. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY ;; #f) "png") |
“pdf” and “tex” have been added to the list of graphic extensions - otherwise you will get errors (see Chapter 6):
(define %graphic-extensions%
;; REFENTRY graphic-extensions
;; PURP List of graphic filename extensions
;; DESC
;; The list of extensions which may appear on a 'fileref'
;; on a 'Graphic' which are indicative of graphic formats.
;;
;; Filenames that end in one of these extensions will not have
;; the '%graphic-default-extension%' added to them.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
'("gif" "jpg" "jpeg" "png" "tif" "tiff" "eps" "epsf" "pdf" "tex"))
|
Use graphics for admonitions (see Section 4.7) and callouts (see Section 4.8):
(define %admon-graphics% ;; Use graphics in admonitions? #t) (define %callout-graphics% ;; If true, callouts are presented with graphics (e.g., reverse-video ;; circled numbers instead of "(1)", "(2)", etc.). ;; Default graphics are provided in the distribution. #t) |
The admonition graphics path has been set to “./images”:
(define %admon-graphics-path% ;; Path to admonition graphics ;; Sets the path, probably relative to the directory ;; where the HTML files are created, to the admonition ;; graphics. ;; ;; This needs to be "./images/" for tar distributed articles ;; This needs to be "../images/" for tar distributed Newbiedoc book ;; This needs to be "../images/" for individual articles on our website "./images/") |
The callouts graphics path has been set to "./images/callouts/":
(define %callout-graphics-path% ;; Sets the path, probably relative to the directory where the HTML ;; files are created, to the callout graphics. "./images/callouts/") |
The callout graphics extension has been set to “png”:
(define %callout-graphics-extension% ;; REFENTRY callout-graphics-extension ;; PURP Extension for callout graphics ;; DESC ;; Sets the extension to use on callout graphics. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY ".png") |
The code that produces the full name of admonitions has been changed:
(define ($admon-graphic$ #!optional (nd (current-node)))
;; Admonition graphic file
;; Given an admonition node, returns the name of the
;; graphic that should be used for that admonition.
(cond ((equal? (gi nd) (normalize "tip"))
(string-append %admon-graphics-path% "tip."
%graphic-default-extension%))
((equal? (gi nd) (normalize "note"))
(string-append %admon-graphics-path% "note."
%graphic-default-extension%))
((equal? (gi nd) (normalize "important"))
(string-append %admon-graphics-path% "important."
%graphic-default-extension%))
((equal? (gi nd) (normalize "caution"))
(string-append %admon-graphics-path% "caution."
%graphic-default-extension%))
((equal? (gi nd) (normalize "warning"))
(string-append %admon-graphics-path% "warning."
%graphic-default-extension%))
(else (error (string-append (gi nd) " is not an admonition.")))))
|
In lyxtox-print.dsl (which uses elements taken from Mandrake's manual-print.dsl), in order to be able to have URLs in PDF:
;; Inserted in order to be able to get URLs in PDF documents.
;; Adapted from manual-print.dsl of <productname>Mandrake</productname>.
;; Include the flow object class "formatting-instruction" : ONLY for Jade
(declare-flow-object-class formatting-instruction
"UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")
;; *** URLs ***
;; Original : dblink.dsl
(element ulink
(sosofo-append
;; If you allow process-children here, you will get the text printed once more!
;; (process-children) ;; Write the text with its format (anchor in HTML)
(make formatting-instruction ;; Write : " \href{" + theUrl + "}{" + theText + "}"
data: (string-append " \\href{" (attribute-string (normalize "url")) "}{" (data-of (current-node)) "}")
)
)
)
;; These three elements are from "dbindex.dsl".
;; Must be placed here because of the redifinition of "ulink".
;; Otherwise the Index entries will point to HTML files,
;; instead of page numbers.
(element (primaryie ulink)
(indexentry-link (current-node)))
(element (secondaryie ulink)
(indexentry-link (current-node)))
(element (tertiaryie ulink)
(indexentry-link (current-node)))
|
To be able to use Computer Modern fonts:
;; Inserted in order to be able to use Computer Modern fonts in PS and PDF documents.
;; The font names _must_ be written exactly as follows ("Computer-Modern",
;; not "Computer Modern") for pdfjadetex to recognize them and use the T1
;; fonts istead of the PK (Type 3) ones (which will look ugly on screen)!
;;
;; Gnuishly correct fonts...
;;
(define %body-font-family% "Computer-Modern")
(define %mono-font-family% "Computer-Modern-Typewriter")
(define %title-font-family% "Computer-Modern-Sans")
(define %admon-font-family% "Computer-Modern-Sans")
(define %guilabel-font-family% "Computer-Modern-Sans")
|
To use chapter/section/subsection labels as filenames for the respective HTML files:
(define %use-id-as-filename% ;; Use <acronym>ID</acronym> attributes as name for component HTML files? #t) |
|
|
In lyxtox-html.dsl, to be able control what section levels get put into separate HTML files (chunks) in the chunked version, the chunk-section-depth has been included (taken from the html/dbchunk.dsl file, which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name):
(define (chunk-section-depth) 2) |
A value of 1 for chunk-section-depth means that the chunks are the individual SECT1 elements, i.e. the Sections. A value of 2 means that the chunks are the individual SECT2 elements, i.e. the SubSections and so on. SECT1, SECT2 and SECT3 are the SGML tags used to denote a Section, SubSection and SubSubSection respectively. There is no meaning in using chunk-section-depth with values higher than 3, at least not with LyX, since SubSubSubsections is the deepest level you can use in LyX (at least with the default settings).
However, as painful experimentation has shown, setting a higher value for chunk-section-depth will have no effect, if “sect2”, “sect3” etc. are not contained in the chunk-element-list list. The list
(define (chunk-element-list)
(list (normalize "preface")
(normalize "chapter")
(normalize "appendix")
(normalize "article")
(normalize "glossary")
(normalize "bibliography")
(normalize "index")
(normalize "colophon")
(normalize "setindex")
(normalize "reference")
(normalize "refentry")
(normalize "part")
(normalize "sect1")
(normalize "sect2")
(normalize "section")
(normalize "book") ;; just in case nothing else matches...
(normalize "set") ;; sets are definitely chunks...
))
|
contains the elements that constitute chunks. If you take an element out of the list, the chunk-section-depth above will not have any effect. Thus, to have chunks on sect2, sect3 etc., you must have them included in this list. chunk-element-list is originally defined in the html/dbchunk.dsl file (just like chunk-section-depth), which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name. See also Naming of generated html code from sgml documents. Note that if you include “sect3” (SubSubSubsections) in the chunk-element-list list, you will get chunks on SubSubSubsections, no matter if your chunk-section-depth is only 2 and not 3!
To force the table of contents to be on a separate HTML page and not contain any section:
(define (chunk-skip-first-element-list) ;; forces the Table of Contents on separate page '()) |
The reason that Norm added support for merging the first sect1 into the file with its parent is because the alternative is really ugly in the case that you have a chapter (title) immediately followed by a section (title) (see Use of <Para> within <ListItem> mangles list items).
 |
Tip |
|---|---|
|
That's why you should try to put at least some introductory text after a chapter title and before the first section of the chapter! |
FIXME: LyX inserts an extra </listitem> here, if I don't have this line...
To get a list of figures at the start of the document, the generate-book-lot-list must contain “figure”, as in the following example:
(define ($generate-book-lot-list$) ;; REFENTRY generate-book-lot-list ;; PURP Which Lists of Titles should be produced for Books? ;; DESC ;; This parameter should be a list (possibly empty) of the elements ;; for which Lists of Titles should be produced for each 'Book'. ;; ;; It is meaningless to put elements that do not have titles in this ;; list. If elements with optional titles are placed in this list, only ;; the instances of those elements that do have titles will appear in ;; the LOT. ;; ;; /DESC ;; AUTHOR N/A ;; /REFENTRY (list (normalize "table") (normalize "figure") (normalize "example") (normalize "equation"))) |
The same must be the case if you want a list of tables (“table”), examples (“example”) or equations (“equation”). Normally, you will not have to touch this (i.e. your customization layer need not contain this code), as the above setting is the default one (for books).
|
|
To be able to display “other credit”, “release info” and “publisher” information on a book's title page, these elements must be added to the book-titlepage-recto-elements list:
(define (book-titlepage-recto-elements)
;; elements on a book's titlepage
;; note: added revhistory to the default list
;; note: added othercredit to the default list
;; note: added releaseinfo to the default list
;; note: added publisher to the default list
(list (normalize "title")
(normalize "subtitle")
(normalize "graphic")
(normalize "mediaobject")
(normalize "corpauthor")
(normalize "authorgroup")
(normalize "author")
(normalize "othercredit")
(normalize "releaseinfo")
(normalize "publisher")
(normalize "editor")
(normalize "copyright")
(normalize "pubdate")
(normalize "revhistory")
(normalize "abstract")
(normalize "legalnotice")))
|
and the same must be done for the article-titlepage-recto-elements list, if we want to display them in articles' title pages too:
(define (article-titlepage-recto-elements)
;; elements on an article's titlepage
;; note: added othercredit to the default list
(list (normalize "title")
(normalize "subtitle")
(normalize "authorgroup")
(normalize "author")
(normalize "othercredit")
(normalize "releaseinfo")
(normalize "copyright")
(normalize "pubdate")
(normalize "revhistory")
(normalize "abstract")
(normalize "legalnotice")))
|
and the following code must be added:
(define (process-contrib #!optional (sosofo (process-children)))
;; print out with othercredit information; for translators, etc.
(make sequence
(make element gi: "SPAN"
attributes: (list (list "CLASS" (gi)))
(process-children))))
(define (process-othercredit #!optional (sosofo (process-children)))
;; print out othercredit information; for translators, etc.
(let ((author-name (author-string))
(author-contrib (select-elements (children (current-node))
(normalize "contrib"))))
(make element gi: "P"
attributes: (list (list "CLASS" (gi)))
(make element gi: "B"
(literal author-name)
(literal " - "))
(process-node-list author-contrib))))
(mode article-titlepage-recto-mode
(element contrib (process-contrib))
(element othercredit (process-othercredit))
)
(mode book-titlepage-recto-mode
(element contrib (process-contrib))
(element othercredit (process-othercredit))
)
(define (article-title nd)
(let* ((artchild (children nd))
(artheader (select-elements artchild (normalize "artheader")))
(artinfo (select-elements artchild (normalize "articleinfo")))
(ahdr (if (node-list-empty? artheader)
artinfo
artheader))
(ahtitles (select-elements (children ahdr)
(normalize "title")))
(artitles (select-elements artchild (normalize "title")))
(titles (if (node-list-empty? artitles)
ahtitles
artitles)))
(if (node-list-empty? titles)
""
(node-list-first titles))))
|
...and many other details. You are encouraged to read the source of the stylesheets (lyxtox-html.dsl, lyxtox-onehtml.dsl, lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl, lyxtox-print-howto.dsl)!
|
Important DocBook files |
|---|---|
|
FYI, all changes presented here refer to variables that were originally defined in one of the following files:
For a list of all parameters, with references to the files that use them, see the
file. If you are looking for a parameter and you can't find the file it's in, the XREF file is your friend. |
| Last updated Mon Sep 24 01:19:25 CEST 2007 | Permalink: http://www.karakas-online.de/mySGML/explain-dsssl-stylesheets.html | All contents © 2002-2007 Chris Karakas |
|
|
|
||
|
|
|
||