Docbook DSSSL Stylesheets

Norm Walsh

In /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/dbparam.dsl, you will see :

(define %stylesheet%
   ;; REFENTRY stylesheet
   ;; PURP Name of the stylesheet to use
   ;; DESC
   ;; The name of the stylesheet to place in the HTML LINK TAG, or '#f' to
   ;; suppress the stylesheet LINK.
   ;; /DESC
   ;; AUTHOR N/A
   ;; /REFENTRY
   #f)

(define %stylesheet% "mystyle.css")

in my DSSSL customization had the desired effect.

Juan R Migoya

Redefine (page-inner-footer gi) in this way:

(define (page-inner-footer gi)
       (make sequence
             font-posture: 'italic
             font-family-name: "Helvetica"
             font-size: 8pt
            (literal "Acme Widgets, Inc")))

Openjade will put it in the right place for odd and even pages.

Norm Walsh

The 'loweralpha' style should be giving you the correct numeration, so I presume the problem is the ")".

Changing the label-title-sep should fix that:

(define (en-label-title-sep)
  (list
   (list (normalize "abstract")		": ")
   (list (normalize "answer")		" ")
   (list (normalize "appendix")		". ")
   (list (normalize "caution")		"")
   (list (normalize "chapter")		". ")
   (list (normalize "equation")		". ")
   (list (normalize "example")		". ")
   (list (normalize "figure")		". ")
   (list (normalize "footnote")		". ")
   (list (normalize "glosssee")		": ")
   (list (normalize "glossseealso")	": ")
   (list (normalize "important")	": ")
   (list (normalize "note")		": ")
   (list (normalize "orderedlist")	") ")  <!-- here -->
   (list (normalize "part")		". ")
   (list (normalize "procedure")	". ")
   (list (normalize "prefix")		". ")
   (list (normalize "question")		" ")
   (list (normalize "refentry")		"")
   (list (normalize "reference")	". ")
   (list (normalize "refsect1")		". ")
   (list (normalize "refsect2")		". ")
   (list (normalize "refsect3")		". ")
   (list (normalize "sect1")		". ")
   (list (normalize "sect2")		". ")
   (list (normalize "sect3")		". ")
   (list (normalize "sect4")		". ")
   (list (normalize "sect5")		". ")
   (list (normalize "section")		". ")
   (list (normalize "simplesect")	". ")
   (list (normalize "seeie")		" ")
   (list (normalize "seealsoie")	" ")
   (list (normalize "step")		". ")
   (list (normalize "table")		". ")
   (list (normalize "tip")		": ")
   (list (normalize "warning")		"")
   ))

Now, if you need a) but 1. somewhere else, you'll have to do something trickier by overriding the definition of gentext-label-title-sep.

Markus Hoenicka

Apparently dvips overrides the paper size defined in the dvi document. Either change config.ps or use the -t option to specify the paper size you need, e.g.: dvips -t letter -o doc.ps doc.dvi

Jany Quintard (I think?)

In a simple-page-sequence you have the left-header, center-header, right-header, left-footer, center-footer, right-footer characteristics, which you can use to specify what you ask for.

OK, here is my answer to the various questions.

We want to have a page header that contains

The most important thing to note that in a simple-page-sequence we can only have a single line as the header... and everything in the header must be an inlined object (rather than a displayed object).

We can have a left-header, a center-header and a right-header though, which makes things a bit easier.

So our header is going to consist of

Each of these objects can be inlined.

The literal text is naturally inlined The rule can be made inline with the 'escapement value of the orientation attribute The external-graphic can be made inline by setting the display? attribute to be #f (false).

It is a good idea if we draw the horizontal rule after all the other objects have been drawn. This is accomplished with the "layer" attribute. Objects are rendered to the output in order of "layer", starting at zero. So, for a given area, an object with layer 1 will be rendered after all the ones with a layer 0.

I'll assume that you are using openjade 1.3.2, TeX backend and with pdfjadetex 3.12. The TeX stuff is a bit fussy, so seemingly subtle changes in the DSSSL can produce quite alarming results... but the stuff below seems reasonably stable ;-).

To cope with the idiosyncracies of pdfjadetex I'm going to put the literal text and the rule as the left header - rather than, say, literal text as the left and the rule as the center. The graphic will be on the right header.

Here goes:

Firstly, we will set up a simple page sequence

(root
        (make simple-page-sequence
                page-width:     8.5in
                page-height:    11in
                top-margin:     1.75in
                bottom-margin:  .75in
                left-margin:    1in
                right-margin:   .5in
                font-size:      12pt
                header-margin:  0.25in
;; That is the obvious stuff needed for the example - now to the right
header. This is straight forward
;; I'm using the Apache powered-by logo, because it came to hand and it
;; is fairly ubiquitous and I don't think anyone will mind if I use
;; it...

                right-header:   ( make external-graphic
;;
;; The logo is a bit big for a line of 12pt text, so we will shrink it
                                      scale:  0.5
;;
;; This is the file name in the current directory
                                      entity-system-id: "apache_pb.png"
;; And it is a PNG file
                                      notation-system-id: "PNG"
;; Make sure it is inlined (this is the default, but it is good to be 
;; explicit)
                                      display?:       #f
;;
;; This is probably only needed to make it look nice with
;; openjade/pdfjadetex.. but without this it comes out
;; a bit low.
                                      position-point-y: -12pt
                                )

;;
;; OK, now for the left-header. This is going to include the
;; rule and the literal text

;; As Jany suggested, we are going to use a variable to
;; store the text we wish to render. This can be
;; passed in on the command line to openjade

;; The left-header is a single sosofo - so we need to join our
;; literal text with the rule as a single sequence.

                left-header:    ( make sequence
;;
;; Now for some literal text
;;
                                        ( literal %header-date% )
;;
;; Now for the rule
                                        ( make rule
;;
;; Escapement makes it an inlined object.
                                                orientation: 'escapement
;;
;; Length is page size less our left and right margins.
                                                length: 7in
;;
;; Render it after all the other things in the header have been
;; rendered.
                                                layer: 1
                                        )
                                 )
;; Finish things off

                (process-children)))

Jany and Brandon.

As long as you want to number all of the biblioentrys in the whole document as one sequence (don't know why you wouldn't, but you never know), you can just do:

where "be" is the biblioentry node. (Should have covered this before, but it's been a while since I've done any DSSSL stuff, so my memory is a bit rusty, and I was too lazy to look it up before. ;) You may notice, in the code, that there is an option for whether you want the stylesheet to look up the biblioentry that your citation is referencing, to make sure it exists. If you don't have it do that, of course, you wouldn't be able to label the citation with the entry's number. So, you'll either need to set that option in your customization layer (the default, false, is set in dbparam.dsl), or just have your version of the citation element rule not do the check, and just do the lookup all the time.

I would complete the Brandon example this way:

(element citation
  (make sequence
     (literal "[")
     (with-mode citation-numbering
       (process-element-with-id (attribute "id"))
     (literal "]")))

(mode citation-numbering
  (element biblioentry
     (make sequence
       (number->string (element-number (current-node))))))

I am not sure that it is complete correct, but it must be close. I am right now not sure if it is the attribute method that you must use or the attribute-string one. Javier Farreres de la Morena"

* Javier Farreres de la Morena

I believe it is attribute-string so something like :

(with-mode citation-numbering
  (process-element-with-id (attribute-string "id" (current-node)))

(current-node) is the optional parameter, so you don't need it.

this seems the same as

(with-mode citation-numbering
  (process-node-list (current-node))

Pavel adds

I basically copied the whole citation function to my customization layer for html and changed one line. I do not know how I could make it with less code duplication; probably it would require amending a docbook stylesheets with another customizable parameter or the function; unfortunately the citation function itself is pretty big. The code is at the end of this eMail (I commented the change I made, with !!!).

So far I only checked it for single-page html output, I will have to do a lot of checks, find out why my pdf does not generate correct references (even without my customization) etc.., hence the question mark in the subject.

(element citation
  (if biblio-citation-check
      (let* ((bgraphies (select-elements (descendants (sgml-root-element))
           (normalize "bibliography")))
       (bchildren1 (expand-children bgraphies
            (list (normalize "bibliography"))))
       (bchildren2 (expand-children bchildren1
            (list (normalize "bibliodiv"))))
       (bibentries (node-list-filter-by-gi
        bchildren2
        (list (normalize "biblioentry")
        (normalize "bibliomixed")))))
  (let loop ((bibs bibentries))
    (if (node-list-empty? bibs)
        (make sequence
    (error (string-append "Cannot find citation: "
              (data (current-node))))
    (literal "[") ($charseq$) (literal "]"))
        (if (citation-matches-target? (current-node)
              (node-list-first bibs))
      (make element gi: "A"
      attributes: (list
             (list "HREF" (href-to
               (node-list-first bibs))))
        (literal "[")
;;!!!        ($charseq$) ;; I commented out this line and added the next one
          (literal (number->string (element-number (node-list-first bibs))))
        (literal "]"))
      (loop (node-list-rest bibs))))))
      (make sequence
  (literal "[") ($charseq$) (literal "]"))))

Ian Zimmerman

PIs are supported in the grove by means of PI nodes. You only need to obtain PI nodes, that's all.

(q-class 'pi) or (q-class 'pi (grove-root)) will query them.

David G Maltby adds:

add

(declare-flow-object-class formatting-instruction
  "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")
to your style-specification

See jclark.com

Michael Spencer

I have used <beginpage/> and then added the following to my custom print dsl file.

<!-- Get beginpage to throw a new page -->
(element beginpage
      (make simple-page-sequence
	page-n-columns: %page-n-columns%
	page-number-restart?: (or %page-number-restart%
				  (book-start?)
				  (first-chapter?))
	page-number-format: ($page-number-format$)
	use: default-text-style
	left-header:   ($left-header$)
	center-header: ($center-header$)
	right-header:  ($right-header$)
	left-footer:   ($left-footer$)
	center-footer: ($center-footer$)
	right-footer:  ($right-footer$)
	start-indent: %body-start-indent%
	input-whitespace-treatment: 'collapse
	quadding: %default-quadding%
	(make sequence
	  (process-children))))

I use <section>, one reason being, it gives breaks for html rendering.

Jany Quintard

I always assumed that "format-number" was designed to transform exact numbers, as for lists or such things. after reading the spec (8.5.7.24. Number to String Conversion), The format-number-list is said to work on a list of *integers*. So format-number is probably designed to work on "ordinal" numbers.

Jany Quintard

I use this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" 
[
<!ENTITY intro    PUBLIC "-//MYSELF//DOCUMENT cover and intro//EN" CDATA DSSSL>
<!ENTITY layout   PUBLIC "-//MYSELF//DOCUMENT print layout//EN"    CDATA DSSSL>
<!ENTITY txtdef   PUBLIC "-//MYSELF//DOCUMENT text layout//EN"     CDATA DSSSL>
<!ENTITY page     PUBLIC "-//MYSELF//DOCUMENT page layout//EN"     CDATA DSSSL>
<!ENTITY colors   PUBLIC "-//MYSELF//DOCUMENT Colors for printed docs//EN"        CDATA DSSSL>
<!ENTITY NLS      PUBLIC "-//MYSELF//DOCUMENT NLS processing//EN"                 CDATA DSSSL>
]
>

<style-specification use="
                          intro
                          layout
                          txtdef
                          page
                          colors
                          NLS
">
.../..
;; Here my rules
i.../...
</style-specification>

<external-specification id="intro"      document="intro">
<external-specification id="txtdef"     document="txtdef">
<external-specification id="layout"     document="layout">
<external-specification id="page"       document="page">
<external-specification id="colors"     document="colors">
<external-specification id="NLS"        document="NLS">

The files, here referred to as PUBLIC, contain defines, which can be shared this way. I believe this is the canonical way to include defines and functions in a stylesheet.

Adam Di Carlo

Did you try

(literal "\carriage-return" "\line-feed") ?

Adam Di Carlo

In your paragraph construction rule, add "lines: 'asis". This will preserve that sort of whitespace, it's what the verbatim type environments use.

Oisin McGuinness

Some years back, for an SGML (ArborText Publisher fixed DTD) to RTF (for Word) conversion project, I came across this very issue, but with rows. (We had documents that produced some empty boxes for putting "stamps" in; Word collapsed these unless the heights were specified explicitly.) There is a way to specify in RTF how to set table heights, but, as you observe, no convenient way to do this in Jade. I implemented a patch to the RtfFOTBuilder.cxx file in the source, and submitted it to James Clark, and discussed it on this mailing list back in late 1997 or early 1998... I guess it never made it into the official source. Clearly it is useful enough that you should submit this to the OpenJade maintainers.

Anyway, this involves some patches to RtfFOTBuilder.cxx, rebuilding Jade, and then using a new characteristic in your .dsl. Here is an excerpt from my email to Clark:

2. table-row-height

Description: This is a length characteristic, to be used for the table-row object, which defaults to 0. If set to a non-zero length, then the table-row will have this exact height.

Declaration in .dsl:

        (declare-characteristic table-row-height
                "UNREGISTERED::James Clark//Characteristic::table-row-height" 0pt)

Usage in dsl:

        (make table-row
              ;; Used to assign header designations.
              label: 'tableheadrow
              ;; Row-height requires a Jade extension,
              table-row-height: (get-row-height)
              (process-children))
   and get-row-height (for my Publisher), extracts the "rht" attribute of tablerow,
   which  is given as a length, e.g., rht="0.78in".

Implementation Note: The RTF command is \trrhN , where N is the number of twips. Since there is no explicit row structure in the backend, and since cells_[i], seems to be the ith-row, I added a field to the Cell structure, and set it when building a cell. This might not be the most elegant thing to do, but it works...

I will send you the full details by separate email so as not to clutter the list. (I have other modifications that have been discussed on the list, anyone interested?)

Note that the diffs in my separate email were made against jade1_2 (if I recall correctly), you may have to do some manual work for OpenJade integration; I haven't kept up with the technology.

Dan Richter

The "literal" function doesn't accept formatting instructions (e.g., font size), but the "make sequence" command does. A "sequence" is just a wrapper: you can nest sequences as much as you want:

   (make paragraph font-size: 10pt
     (literal "Some ten-point text.")
     (make sequence font-size: 12pt
       (literal "Some twelve-point text.")
       (make sequence font-size: 60pt
         (literal "Some big text.")
       (literal "More twelve-point text.")))

Didier PH Martin expands

You can use an aggregator flow object such as a sequence or a display-group flow object. Both will provide inherited properties to their contained flow objects. In the case of the display-group object, this latter behaves like a block (like in css). In the case of the sequence object, since it is not a displayed area, it is used mainly to provide default properties to the contained objects. Here is a snippet of the specs about the sequence flow object:

"A sequence flow object is useful for specifying inherited characteristics. For example, a sequence flow object with a specification of a font-posture: characteristic may be constructed for an emphasized phrase element in a paragraph."

So, the thing to remember here is: If you need to provide default properties to a collection of objects and want them to behave as a single visual entity, use the display-group flow object.

If you need to provide default properties to a collection of objects but do not want to have them behave as a display area (i.e a block like in CSS) then use the sequence flow object.

In other words. you basically have two main objects:

1) objects that behaves like a block (i.e. a paragraph, a display-group, a page-sequence, etc...). they have a border, etc... they are the equivalent of the CSS block objects. The whole is more than the parts and it has its own visual characteristics.

2) inline objects. These object can only be contained inside a display area. As a whole they do not have visual characteristics.

You have two ways to aggregate a collection of flow objects and have them to inherit the same properties (i.e. the properties of the aggregator)

1) display-group flow objects. The whole (i.e. the display-group object) has visual characteristics. Thus the whole is more than the parts.

2) sequence flow objects. The whole has no visual characteristics and it needs to be contained into another object having ones (like for instance a paragraph or a display-group object). In both cases, the contained objects inherit default properties from the aggregator.

If you look at the article I wrote about display-group objects you can see that this kind of object has visual characteristics. Hence, you create a new visual object by aggregating other ones. The aggregator has also its own visual characteristics. In the case of the sequence flow object, it doesn't. It just provide a set of properties to be inherited by the contained object.

In the specs, you'll often encounter the term "port". Think of that gizmo as an attachment device. If we say that an object has a single port it means that all objects attached to it are so by this unique port (i.e. attachment). You can see that in the figure I included in the article where the display-group object is illustrated with a single port used to "attach" the aggregated object. A port is simply an attachment device to stitch the flow object together. Both the display-group and the sequence objects have a single port used to attach the flow objects. An other way to think of a collection is to think of a list. The display-group list is a visual object having its own visual characteristics, the sequence list is a..list and do not have its own visual characteristics. So, display-group creates a new visual object from other ones and sequence is only a list of flow objects. In both cases, the list container provides a set of default properties (i.e. characteristics) inherited by the list members.

??

In your customized DSSSL stylesheet:

(default
  (make element gi: "FONT"
	attributes: '(("COLOR" "RED")) ;; Replace by what you want
	(process-children)))

(The above was obtained from html/docbook.dsl by grepping for "RED".)

Jirka Kosek

AFAIK this is problem in Jade/OpenJade. Jade forces you to use same encoding for input and for output. You must either change encoding of your XML files to UTF-8, or modify suse-html.dsl and Jade environment (by command-line switch or SP_ENCODING) to change output encoding to ISO-8859-1.

If you can, I would recommend you to use XSL stylesheets for getting HTML from DocBook. Encoding of input and output can be different here and you will get better HTML code faster; XSL stylesheets also support more features than DSSSL ones.

Jirka Kosek

Try adding following into your DSSSL customization layer:

(define (page-outer-footer gi)
  (empty-sosofo))
(define (first-page-outer-footer gi)
  (empty-sosofo))

??

It works fine, thanks, here is the current stylesheet:

(define (process-contrib #!optional (sosofo (process-children)))
    (process-children))

(define (process-othercredit #!optional (sosofo (process-children)))
  (let ((author-name  (author-string))
        (author-contrib (select-elements (children (current-node))
                                          (normalize "contrib"))))
    (make sequence
      (if (first-sibling?)
	  (make paragraph
	    (literal "Remerciements a : "))
	  (empty-sosofo))
      (make paragraph
	(literal author-name)
	(literal " - ")
	(process-node-list author-contrib)))))

(mode article-titlepage-recto-mode
  (element contrib (process-contrib))
  (element othercredit (process-othercredit))
  )

N. Raghavendra

Here is one possible method. Modify the document type declaration of your DSSSL stylesheet like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN"
[
  <!ENTITY dbstyle
    SYSTEM
    "/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/docbook.dsl"
    CDATA DSSSL>

  <!ENTITY % output.independent "IGNORE">
]>

Then, in the style specification body, include a marked section like
so:

  <![ %output.independent; [
  
  ;; Suppress the default navigation bars.
  (define %header-navigation% #f)
  (define %footer-navigation% #f)
  
  ;; Produce separate HTML pages.
  (define nochunks #f)
  
  ]]>

Now, to produce the `independent' output, run `openjade', or `jade', using the `-i' option:

  openjade -i output.independent -d stylesheet-html.dsl document.xml

To produce usual output, just don't use the `-i' option.

Try "pdftk" (http://www.accesspdf.com/pdftk/) which splits (among other options) a PDF file into new documents.

Jirka Kosek

See Sourceforge

You must of course change jade command to ojade as your are using OpenJade. Rest of the process is same.

Norman Gray

Find it at astro.gla.ac.uk

I don't want to oversell it. The backend aims to help with outputting TeX-style commands and LaTeX-style environments, much like the SGML-transformation back-end. Thus it can produce output suitable for any TeX format.

Since you mention Omega, I imagine your question is really about character repertiores, Unicode, internationalisation and all that. That's a hard problem, which I'm not well qualified to address. I'd hope that, at best, this back-end would provide a basis on which someone could add such capabilities.