Pomade: Poor Man's DSSSL Environment

User Documentation for Version 1.00

Andreas Saremba

This is the user documentation for Pomade, which stands for "Poor Man's DSSSL Environment". Pomade is a tool for developers who want to process their DSSSL scripts with Jade without having to deal with its call syntax, command line parameters and with the location of a myriad of SGML support files like catalogs, entity files and the like.

Pomade is implemented in Tcl/Tk; therefore, it can be used on virtually every Unix platform and on Windows 9x/NT. (It is tested on Linux and Windows NT 4.0.)

Pomade still has many limitations, including the incompleteness of this documentation and, ahem, suboptimal error checking. Feel invited to make proposals for improvements, but please be aware that this is a spare time effort, so no promises are made.

This software is copyrighted by the author, but freely usable and distributable. About the only thing you are not allowed to do is to claim authorship. See the file COPYRIGHT in the Pomade distribution.

Table of Contents
1. Introduction
1.1. What's the idea?
1.2. What's needed?
1.3. What's provided?
2. Execution environment
3. A sample session
3.1. Starting Pomade
3.2. The user interface
3.3. Adjusting the options
3.4. Running Jade
4. A sample .pmd file
4.1. The file listing
4.2. The comments
4.2.1. POMADE_APP
4.2.2. BASE_DIR
4.2.3. LOCAL_CATALOG_FILES
4.2.4. SEARCH_DIRS_BASEREL
4.2.5. SEARCH_DIRS_DOCREL
4.2.6. FORMATGROUP
4.2.7. JADE_BACKENDS
4.2.8. DSSSL_SCRIPT
4.2.9. SUFFIX
4.2.10. PARAGROUP
4.2.11. PARA
5. Resources
5.1. Jade
5.2. Docbook
5.3. Tcl/Tk
5.4. Pomade

Chapter 1. Introduction

1.1. What's the idea?

DSSSL scripts can be configured in a rather straightforward way if they supply the necessary hooks, but doing so is a bit cumbersome and cannot be reasonably expected from normal users. The idea behind Pomade is that an expert writes down all the configurable parameters and their legal values, then the tool translates this specification into a graphical user interface that allows easy handling for non-expert users (or lazy experts, like Pomade's author). From the user's choices (and the defaults values, if s/he choosse to keep them) Pomade then builds a DSSSL script and a Jade call for execution.

1.2. What's needed?

Pomade is for people like Dilbert, not for his boss. It will teach you neither SGML or XML nor DSSSL. You'll have to write SGML documents and DSSSL scripts yourself or get them from somebody who knows how to do this. (The Pomade distribution might in the future contain more useful samples than it does now; feel free to contribute. At present, you may use this SGML document and the file samples/docbook.pmd together with Norman Walsh's Docbook DSSSL scripts as a starter. See the appendix.)

In addition, you need Jade, James (Clark)'s Amazing DSSSL engine, for processing the DSSSL scripts. The current distribution of Pomade (1.00) was tested with version 1.2 of Jade. See the Appendix for information how to get it.

Finally, you need a fairly current release of Tcl/Tk (8.0p2 or newer) for the platform(s) you plan to use Pomade on; see the appendix for exact information. Tcl is a scripting language that comes bundled with a toolkit (Tk) for implementing cross-platform Graphical User Interfaces. Pomade is implemented entirely in standard Tcl/Tk with no extensions, so no compilation is required once you have the Tcl interpreter up and running.

1.3. What's provided?

Pomade does the following things that are not difficult but tiresome for an experienced Jade user:

  • It builds a Jade call with all necessary parameters for the output format(s) of your choice.

  • It builds a top level DSSSL script that does not only invoke your main script responsible for the actual work, but also contains your current configuration choices (fonts, margins etc.)

  • It lets you add application specific catalog files to those defined in SGML_CATALOG_FILES. In addition, you may specify which directories are to be searched for files whose SYSTEM identifiers do not contain a fully qualified path name.

  • If the file name has the suffix .xml, Pomade automatically adds a reference to the standard XML declaration xml.dcl to the Jade call. SGML tools like Jade don't do that automatically and therefore sometimes fail mysteriously, which can be a source of frustration for many users.

  • If instructed to do so, it builds a temporary catalog file that maps PUBLIC identifiers used in the DTD or in a DSSSL script to SYSTEM identifiers reflecting your current choices. It also makes sure that this catalog file overrides the other catalog files. (This feature is not used in the Docbook example presented in this documentation.)

All this is done behind the scenes, if you want; you just click the buttons and fill in the blanks.

But Pomade cannot read your thoughts, so prior to the first usage you have to specify what configuration options your application offers. You do this by writing a specification file, which is a normal ASCII file, but you need only do this once for an application. Pomade will read the specification and build the graphical user interface.

Chapter 2. Execution environment

Pomade doesn't need heavy setup celebrations. There is one requirement and a few recommendations:

Chapter 3. A sample session

In this section, we'll walk through a sample Pomade session to get a feeling of what you can do with the tool. This will give you a better background for the next section covering the syntax of the application specification file.

3.1. Starting Pomade

If you use Pomade on a Unix system, you have to call pomade.tcl, either from a shell prompt or from your preferred window manager. Make sure you have a Tcl interpreter (version >= 8.0p2) named wish in your PATH . You may optionally add the name of a .pmd file as the first argument and the name of an SGML file as the second. Here is an example:

cd /home/dilbert/sgml/sys/docbook

/home/dilbert/sgml/tools/pomade/pomade.tcl docbook.pmd

If you use Pomade on Windows, the installation of the Tcl interpreter will have associated the .tcl extension with the wish interpreter, so double clicking on pomade.tcl in the Explorer or on an associated desktop icon will start Pomade. Optionally, you may associate the .pmd extension with pomade.tcl to make a double click on, say, docbook.pmd start Pomade with the Docbook application.

Let's assume you have started Pomade without a parameter; in this case, you will see a file selection dialog prompting you to select a Pomade application. (This step is omitted if you specified a .pmd file as call argument). Navigate the file system and find the Pomade application file you want to use:

In the screen shot you see that the .pmd file is in the docbook directory, which contains (among others) the following subdirectories:

  • dtd with the standard Docbook DTD distribution (version 3.0).

  • dsssl, containing Norman Walsh's Modular Docbook Stylesheets.

  • documents, containing several documents both of my own and by others.

  • tmp, where Pomade stores its temporary files. This directory is created if it doesn't exist.

After selecting and confirming your choice (the docbook application in our example), you will see a second file selection dialog prompting you to select an SGML file for processing. (This step is omitted if you specified two arguments on the command line.) At this point, you know that Pomade has successfully read and processed your application specification file.

The directory shown will be the subdirectory documents of the BASE_DIR defined in the docbook.pmd file. You navigate the file system and select a file to process, for example this document you are just reading:

At this point, Pomade will silently register your choice but do nothing with the selected file (not even have it parsed). Instead, it will display its main window as configured by the application specification in docbook.pmd. Only the general layout of the window is determined by the program itself, the specific content is defined by the application. (Note that the log window at the bottom will be empty when you start Pomade.)

3.2. The user interface

Most of the user interface should be self-evident, but there are a few points that need comments:

  • The upper part of the window is dynamically generated from the Pomade specification, as you might have suspected. The configurable parameters are grouped in order to avoid too much clutter, and each group is represented by a button; pushing that button will open a dialog box. See the next section for more details.

  • The middle part contains not only a button for starting Jade and a text area naming the input file, but also a button named Output file and an empty text area. This is for those rare cases where a DSSSL script writes to STDOUT and you want to redirect this to an arbitrarily named file. Pushing the Output file button will open a file selection dialog, where you can specify that name. In analogy, the Input file button allows to to open a different SGML input file. (This should conform to the same DTD, of course.)

  • The lower part is a log window; here you see the commands that are built by Pomade and processed by Jade. You can copy and use them if you like to. This makes sense only in context with the DSSSL scripts generated by Pomade; you can see them by using the menu bar's item Windows/DSSSL Code.

3.3. Adjusting the options

The Docbook application offers a choice between two types of output (HTML and Print), the latter with various formats each of which corresponds to a Jade backend.

Each of the buttons in the upper part of the main window opens a dialog that offers several choices giving you access to the configuration variables of the Docbook DSSSL scripts. The Pages button of the Print format group, for example, activates this window:

By making your choices or entering values you determine what values will be written into the DSSSL script that Pomade produces for the Jade call. You will see later how this is done in the Pomade application specification file.

You may enter values in as many of the windows as you like, but you need not. You see the values exactly as they will be written, and if you don't change them they will be used as they are. No error checking is done when you enter values, so if you specify the left margin to be "Donald Duck", only Jade will complain (later) that this value is slightly inappropriate.

(There is another possibility for specifying options, but it's hidden in the menu bar under the Mappings button. This is for defining the mapping between PUBLIC and SYSTEM identifiers; in the Docbook application it is not used, however.)

3.4. Running Jade

After having finished the preparations, you select the output format(s) you want and push the big button labelled "Run Jade" to actually produce output. Use the checkbuttons to select one or more formats. Pomade will build the required files (a DSSSL script for each group of output chosen and a temporary catalog file, if necessary), and it will issue the Jade call(s). (You will see each call in the log window for your information, and if you want to just learn from it or want to steal it for your makefile or batch script, you are invited to do so. Use the platform specific cut and paste method.)

If things go well, you will see an Ok message in the log window, specifying which format was produced; in addition, Pomade will tell how much time it took to generate the output. In the other case, Pomade will, in addition to its own error message in the log window, show you Jade's error messages in a separate text window.

Chapter 4. A sample .pmd file

Before describing the format of a Pomade application specification file, we'll look at a commented example. This will be, of course, the specification for the example you saw in the previous section.

4.1. The file listing

  1 # 
  2 #-----------------------------------------------------------------------------
  3 # This file is part of Pomade (Poor Man's DSSSL Environment)
  4 # (C) 1998 Andreas Saremba
  5 #
  6 # Pomade Version: V1_00
  7 # File Name:      docbook.pmd,v  
  8 # File Revision:  1.18
  9 # Checkin Date:   2000/02/26 11:10:39
 10 #-----------------------------------------------------------------------------
 11 
 12 #==============================================================================
 13 # This is a Pomade application specification file for Docbook (to be used with
 14 # Norman Walsh's Modular Docbook Stylesheets).
 15 #==============================================================================
 16 
 17 POMADE_APP=Docbook
 18 
 19 #------------------------------------------------------------------------------
 20 # This is the base path for all the relative file/directory names defined later
 21 # If you use a relative path name for BASE_DIR, it is relative to the location
 22 # of this configuration file. This is useful if you plan to use it on 
 23 # different platforms like Unix and Windows.
 24 # If this configuration file is somewhere else in the file system, you should
 25 # consider using an absolute path for BASE_DIR.
 26 #
 27 # In this case, we assume that the Docbook DTD lives in the subdirectory ./dtd
 28 # and the current distribution of the Modular Docbook Stylesheets is in the
 29 # subdirectory ./dsssl. (You have to rename Norman's directory "docbook"
 30 # to "dsssl" for that!)
 31 #------------------------------------------------------------------------------
 32 BASE_DIR=.
 33 
 34 #------------------------------------------------------------------------------
 35 # The following catalog files are used in addition to those defined in 
 36 # $SGML_CATALOG_FILES. You can override the global PUBLIC -> SYSTEM mappings 
 37 # in these files because they are searched before the global ones.
 38 # LOCAL_CATALOG_FILES is a colon separated list of catalog files names 
 39 # (not of directories!).
 40 # You need not mention tmp/catalog.tmp here. It is added automatically to the
 41 # jade call.
 42 #------------------------------------------------------------------------------
 43 LOCAL_CATALOG_FILES=dsssl/catalog
 44 
 45 #------------------------------------------------------------------------------
 46 # SEARCH_DIRS is a colon separated list of directores where those files are 
 47 # searched that are referenced in the catalog files but are not found 
 48 # elsewhere.
 49 # BASEREL means relative to the BASE_DIR specified above
 50 # DOCREL means relative to the document's directory (in this example, Jade
 51 #        will look for a subdirectory named images in the doc's directory)
 52 #------------------------------------------------------------------------------
 53 SEARCH_DIRS_BASEREL=dtd:dsssl/common:dsssl/lib
 54 SEARCH_DIRS_DOCREL=images
 55 
 56 #------------------------------------------------------------------------------
 57 # This is the format group that is responsible for the HTML output 
 58 #------------------------------------------------------------------------------
 59 FORMATGROUP HTML
 60 JADE_BACKENDS=SGML
 61 DSSSL_SCRIPT=dsssl/html/docbook.dsl
 62 SUFFIX=.htm
 63 
 64 PARAGROUP Navigation
 65 PARA use tables?:%gentext-nav-use-tables%:BOOLEAN:1
 66 PARA table width?:%gentext-nax-tblwidth%:CHOICE:"50%"@"100%"
 67 PARA fast forward?:%gentext-nav-use-ff%:BOOLEAN:1
 68 
 69 PARAGROUP Organization 
 70 PARA one single HTML file?:nochunks:BOOLEAN:0
 71 
 72 PARAGROUP Title pages
 73 PARA Elements in Info Order ?:%titlepage-in-info-order%:BOOLEAN:0
 74 PARA Book title page ?:%generate-book-titlepage%:BOOLEAN:1
 75 PARA Chapter title page ?:%generate-chapter-titlepage%:BOOLEAN:1
 76 
 77 PARAGROUP Table of Contents
 78 PARA generate toc for sets?:%generate-set-toc%:BOOLEAN:1
 79 PARA generate toc for books?:%generate-book-toc%:BOOLEAN:1
 80 PARA generate toc for parts?:%generate-part-toc%:BOOLEAN:1
 81 PARA generate toc for articles?:%generate-article-toc%:BOOLEAN:1
 82 PARA generate toc for reference?:%generate-reference-toc%:BOOLEAN:1
 83 PARA parts toc on title page?:%generate-part-toc-on-titlepage%:BOOLEAN:1
 84 PARA reference toc on title page?:%generate-reference-toc-on-titlepage%:BOOLEAN:1
 85 PARA force chapter toc?:%force-chapter-toc%:BOOLEAN:0
 86 
 87 PARAGROUP Literal parts
 88 PARA shaded?:%shade-verbatim%:BOOLEAN:1
 89 PARA Line group length ?:%linenumber-mod%:NUMBER:1
 90 PARA Line number in program listings ?:%number-programlisting-lines%:BOOLEAN:1
 91 PARA Line number in literallayout ?:%number-literallayout-lines%:BOOLEAN:0
 92 PARA Line number in screen ?:%number-screen-lines%:BOOLEAN:0
 93 PARA Line number in synopsis ?:%number-synopsis-lines%:BOOLEAN:0
 94 
 95 PARAGROUP Misc
 96 PARA Language:%gentext-language%:CHOICE:#f@"usen"@"dege"@"ru"
 97 PARA autonumber chapters?:%chapter-autolabel%:BOOLEAN:1
 98 PARA autonumber sections?:%section-autolabel%:BOOLEAN:1
 99 PARA level for simple sections:%default-simplesect-level%:NUMBER:4
100 PARA function synopsis style:%funcsynopsis-style%:CHOICE:'ansi@'k&r
101 
102 #------------------------------------------------------------------------------
103 # This is the format group that is responsible for the print output 
104 # (RTF/TEX)
105 #------------------------------------------------------------------------------
106 FORMATGROUP Print
107 JADE_BACKENDS=RTF:RTF-95:TeX
108 DSSSL_SCRIPT=dsssl/print/docbook.dsl
109 
110 PARAGROUP Pages
111 PARA page size:%paper-type%:CHOICE:"A4"@"USletter"
112 PARA two sided output?:%two-side%:BOOLEAN:0
113 PARA left margin:%left-margin%:NUMBER:2cm
114 PARA right margin:%right-margin%:NUMBER:1.5cm
115 PARA produce running heads?:%chap-app-running-heads%:BOOLEAN:1
116 PARA autonumber running heads?:%chap-app-running-head-autolabel%:BOOLEAN:1
117 
118 PARAGROUP Title pages
119 PARA Elements in Info Order?:%titlepage-in-info-order%:BOOLEAN:0
120 PARA Book title page?:%generate-book-titlepage%:BOOLEAN:1
121 PARA Book TOC on title page?:%generate-book-toc-on-titlepage%:BOOLEAN:1
122 PARA Chapter title page?:%generate-chapter-titlepage%:BOOLEAN:0
123 PARA Chapter TOC on title page?:%generate-chapter-toc-on-titlepage%:BOOLEAN:1
124 
125 PARAGROUP Lines and Characters
126 PARA Line spacing factor:%line-spacing-factor%:NUMBER:1.1
127 PARA title font:%title-font-family%:CHOICE:"Helvetica"@"Times"
128 PARA GUI label font:%guilabel-font-family%:CHOICE:"Helvetica"@"Times"@"Courier"
129 PARA body font:%body-font-family%:CHOICE:"Times"@"Helvetica"
130 PARA body font size:%visual-acuity%:CHOICE:"normal"@"tiny"@"presbyopic"@"large-type"
131 PARA font upscaling factor:%hsize-bump-factor%:NUMBER:1.2
132 PARA font downscaling factor:%smaller-size-factor%:NUMBER:0.9
133 PARA verbatim font:%mono-font-family%:CHOICE:"Courier"
134 PARA verbatim scaling factor:%verbatim-size-factor%:NUMBER:0.8
135 PARA verbatim # of chars per line:%verbatim-default-width%:NUMBER:120
136 
137 PARAGROUP Paragraphs
138 PARA indentation for block elements:%block-start-indent%:NUMBER:0cm
139 PARA indentation for body text:%body-start-indent%:NUMBER:0.5cm
140 PARA component subtitle justification:%component-subtitle-quadding%:CHOICE:'start@'center@'end
141 PARA component title justification:%component-title-quadding%:CHOICE:'start@'center@'end
142 PARA default justification:%default-quadding%:CHOICE:'start@'center@'end@'justify
143 
144 PARAGROUP Literal parts
145 PARA Line group length?:%linenumber-mod%:NUMBER:1
146 PARA Line number in program listings?:%number-programlisting-lines%:BOOLEAN:1
147 PARA Line number in literallayout?:%number-literallayout-lines%:BOOLEAN:0
148 PARA Line number in screen?:%number-screen-lines%:BOOLEAN:0
149 PARA Line number in synopsis?:%number-synopsis-lines%:BOOLEAN:0
150 
151 PARAGROUP Misc
152 PARA Language:%gentext-language%:CHOICE:#f@"usen"@"dege"@"ru"
153 PARA autonumber chapters?:%chapter-autolabel%:BOOLEAN:1
154 PARA autonumber sections?:%section-autolabel%:BOOLEAN:1
155 
156 # 
157 

4.2. The comments

4.2.1. POMADE_APP

First comes the name of the Pomade application. Pomade doesn't use this name for other purposes than for the user's information. You see this name at the top of the program's main window.

4.2.2. BASE_DIR

In general, this is the directory that will be used as the base for all relative file and directory names used later in this specification file (LOCAL_CATALOG_FILES, SEARCH_DIRS, DSSSL_SCRIPT). In the example, the value . means that the directory where the .pmd file is located is the base directory.

4.2.3. LOCAL_CATALOG_FILES

This line specifies a colon separated list of application specific catalog files that are used in addition to those defined in the environment variable SGML_CATALOG_FILES . In the example, there is no colon because we have just one file. (Remember that CATALOG lives in the subdirectory dsssl of the .pmd file's directory.)

4.2.4. SEARCH_DIRS_BASEREL

Jade offers the possibility of specifying directories where files are searched that are needed for satisfying a PUBLIC->SYSTEMidentifier mapping but cannot be found by their given path name. Here we have specified that the subdirectories tmp, dtd, dsssl/common and dsssl/lib of BASE_DIR are to be searched for such files.

4.2.5. SEARCH_DIRS_DOCREL

This is analogous to the specification of the BASE_DIR relative search path, but here the directories are relative to the location of the current document. Here we have specified that the subdirectoryimages is to be searched.

Note: Usage of this feature depends on the DSSSL scripts you are using; it is not without problems. The Docbook scripts generate correct RTF output (with absolute filenames), but in the HTML output file names are the same as in the original SGML file, so the location where Jade found the (image) files is not reflected here!

4.2.6. FORMATGROUP

Two format groups are specified in this application, HTML and Print. These are symbolic names that are used for grouping related backends. You see these names in the user interface as title strings in the middle part of Pomade's main window.

4.2.7. JADE_BACKENDS

As the name indicates, these are the names of the backends as used by Jade. Each of these names is represented by a checkbutton in the user interface, so you can selectively turn on and off the generation of the respective format.

4.2.8. DSSSL_SCRIPT

Each format group needs its DSSSL script, and here you specify which one is it. Note again that you can use a relative path name here.

You can address a DSSSL spec in a file with the usual <file>#<spec> syntax although this is not used in the example.

4.2.9. SUFFIX

Some DSSSL scripts write their output to STDOUT instead of a file. If you specify a suffix here, Pomade will redirect STDOUT to a file with the same name as the original, but with this suffix (instead of .sgm or .xml.

4.2.10. PARAGROUP

The names specified here are purely symbolic. Their purpose is simply to logically group parameters and make things look a bit more organized in the user interface. For each of these names, you see a button that, when pressed, open a dialog box that lets you specify values for the PARAGROUP's parameters.

In our example application, there are 6 PARAGROUPs in each formatgroup, yielding 2 columns of 6 buttons each.

4.2.11. PARA

Here the parameters proper are specified. Each PARA line belongs to the last PARAGROUP the parser has seen.

Each of the PARA lines should correspond to a configurable parameter in a DSSSL script (it makes no sense otherwise ).

Let's take the first one as an example. It consists of four entries, separated by colons:

Variable Description (autonumber chapters? )

This is the name of the variable as it appears in the user interface, i.e. in the dialog box of its PARAGROUP .

Variable name (%chapter-autolabel% )

This is the name of the variable as it appears in the DSSSL script. Don't be fooled by the percent signs; they are not part of DSSSL's or Pomade's syntax but just a convention used by the DSSSL script's author (Norman Walsh).

Variable Type (BOOLEAN )

Pomade knows three types of variables all of which appear in this example:

NUMBER

This is a numerical value that can be entered by the user via the keyboard. No distinction is made between integers and fractional values. For example, the user has to know that "level for simple sections" has to be an integer, while "left margin" may be 1.5cm. In addition, the user has to respect DSSSL's syntax for numbers (decimal point , not comma as in Germany).

BOOLEAN

This is 0 or 1, which is mapped to #f and #t in the DSSSL file. In the user interface, you see a checkbutton.

CHOICE

Here the user can select between other values than simply true or false, for example "A4" and "USletter" as in the page format. Note that the choices are separated by an ampersand character (@) and must be written exactly as they appear in the DSSSL file, including the quotes.

Default value (1 )

This is the value that is presented in the user interface the first time the user opens the respective dialog box. This value will be written to the DSSSL file if the user does not change it.

There's a hidden subtlety in the definition of the variable description that has to do with the implementation of the user interface elements. Their names are built from the parameter descriptions (replacing spaces by underscores). This means that you should never use the same description for two parameters in the same format group (that is, if you are the type of person who does not like two tires in a car!). But you can put this knowledge to good use if you really intendto change a parameter in both paragroups from one place. If you want to see an example, open the two "Misc" dialog boxes, where the same description "autonumber chapters?" has been deliberately chosen. Click a checkbutton in one box and see the corresponding checkbutton in the other box automagically change its value!

Chapter 5. Resources

5.1. Jade

James Clark's popular DSSSL engine Jade used to have its home under http://www.jclark.com/jade. This is still true, but since James has shifted his primary interest to XML and XSL, development is largely finished. You will still find source code and binaries for MS Windows, though.

A group of developers has taken over the development. You get the source code and Windows binaries of OpenJade at http://peano.mathematik.uni-freiburg.de/jade-cvs. The OpenJade homepage with more interesting material and links is http://www.netfolder.com/DSSSL .

5.2. Docbook

You find the Docbook DTD at the OASIS web site under http://www.oasis-open.org/docbook.

Norman Walsh's Modular Docbook Stylesheets are located at his web site under http://nwalsh.com/docbook/dsssl. As of this writing, the release I use is 1.49. Norman also maintains an XML port of Docbook, which you will find at his website, too.

5.3. Tcl/Tk

For downloading Tcl/Tk, see Scriptic's Tcl download page under http://www.scriptics.com/products/tcltk/8.2.html. You'll find a binary distribution that installs easily under Windows 95/NT. For Unix platforms, there is a source distribution that should compile out of the box.

Pomade should work with any version of Tcl starting with 8.0p2. Please report if you encounter problems.

5.4. Pomade

You find the current version of Pomade (including this documentation) at my website. Please visit http://www.saremba.de/pomade.