[ANN] Pomade - Poor Man's DSSSL Environment

[Andreas.Saremba@xxxxxxxxxxx (Andreas Saremba)]

This is the first semi-public release of Pomade, a graphical frontend
for James Clark's DSSSL engine Jade. (Semi-public means that it is
available for everyone, but this announcement is limited to the
members of the DSSSL mailing list.)

As you might guess from Pomade's full name, "Poor Man's DSSSL
Environment", it is freeware. Use it and have fun, but be warned that
it hasn't been tested by anybody except me.

I have attached the (draft) documentation with the images omitted. The
package itself is small, less than 90 KB compressed (most of the size
comes from the gif images of the documentation). You find Pomade at

  http://home.t-online.de/home/andreas.saremba/pomade.zip 
or
  http://home.t-online.de/home/andreas.saremba/pomade.tar.gz

The zip file doesn't contain the directory name, so create a directory
first to unpack it there.

Whether you are enthusiastic or furious, I would like to hear your
comments if you give it a try.

  Andreas

=====================================================================


<!DOCTYPE article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!-- $Name:  $ -->
<!-- $Id: pomade.sgm,v 1.1 1998/04/19 20:50:54 sar Exp $ -->
<!-- Begin Document Specific Declarations -->

<!ENTITY graphic2 SYSTEM "images\APP-FSD.gif" NDATA GIF>
<!ENTITY graphic3 SYSTEM "images\SGM-FSD.gif" NDATA GIF>
<!ENTITY graphic4 SYSTEM "images\docbook.gif" NDATA GIF>
<!ENTITY graphic5 SYSTEM "images\PRPAGES.gif" NDATA GIF>
<!ENTITY graphic6 SYSTEM "images\OPTIONS.gif" NDATA GIF>
<!ENTITY graphic7 SYSTEM "images\FGROUPS.gif" NDATA GIF>
<!ENTITY graphic8 SYSTEM "images\AUTO-1.gif" NDATA GIF>
<!ENTITY graphic9 SYSTEM "images\AUTO-2.gif" NDATA GIF>

<!-- End Document Specific Declarations -->

]>

<article><artheader><title>Pomade V0.01</title>
<subtitle>User Documentation (first draft)</subtitle>
<authorgroup><author><firstname>Andreas</firstname>
<surname>Saremba</surname>
<authorblurb><para>Andreas Saremba (andreas.saremba@xxxxxxxxxxx)
works for the Solutions &#38; Business Services division of Siemens
Nixdorf in Berlin, Germany. He lives in Brieselang, a village near the
German capital.</para></authorblurb></author></authorgroup>
<artpagenums></artpagenums></artheader> <abstract><para>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 it's call
syntax, command line parameters and with the location of a myriad of
SGML support files like catalogs, entity files and the like.</para>
<para>Pomade is implemented in Tcl/Tk; therefore, it can be used on
virtually every Unix platform and on Windows 95/NT. (It is tested on
Linux, the development platform, and on Windows 95.)</para>
<para>Pomade still has many limitations, including the incompleteness
of this documentation and lousy 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.</para></abstract>
<sect1><title>Introduction</title> <sect2><title>What's
needed?</title> <para>Pomade is for people like Dilbert, not for his
boss. It will teach you neither SGML 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 will in the future,
however, contain some small examples; you may also use this SGML
document together with Norman Walsh's Docbook DSSSL scripts as a
starter. See the appendix.)</para> <para>In addition, you need
<productname>Jade</productname>, James (Clark)'s Amazing DSSSL engine,
for processing the DSSSL scripts. The current distribution of Pomade
(V0.01) was tested with version 1.0 of Jade. See the Appendix for
information how to get it.</para> <para>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.</para></sect2> <sect2><title>What's provided?</title>
<para>Pomade does the following things that are not difficult but
tiresome for an experienced Jade user:<itemizedlist><listitem><para>It
lets you add application specific catalog files to those defined in
<literal>SGML_CATALOG_FILES</literal>. In addition, you may specify
which directories are to be searched for files whose
<literal>SYSTEM</literal> identifiers do not contain a fully qualified
path name.</para></listitem> <listitem><para>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.)</para></listitem> <listitem><para>If
instructed to do so, it builds a temporary catalog file that maps
<literal>PUBLIC</literal> identifiers used in the DTD or in a DSSSL
script to <literal>SYSTEM</literal> identifiers reflecting your
current choices. It also makes sure that this catalog file overrides
the other catalog files.</para></listitem> <listitem><para>It builds a
Jade call with all necessary parameters for the output format(s) of
your choice. </para></listitem></itemizedlist></para> <para>All this
is done behind the scenes, if you want; you just click the buttons and
fill in the blanks.</para> <para>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.</para></sect2>
<sect2><title>Execution environment</title> <para>Pomade doesn't need
heavy setup celebrations. There is one requirement and a few
recommendations:<itemizedlist><listitem><para>The
<productname>Jade</productname> executable's directory must be in your
<literal>PATH</literal> environment variable.</para></listitem>
<listitem><para>When displaying the dialog box for the selection of
the Pomade application (<literal>.pmd)</literal> file, Pomade will
check whether the environment variable <literal>SGML_DIR</literal> is
defined. It will then display the contents of the directory
<filename>$SGML_DIR/sys</filename> or (if it does not exist) of
<filename>$SGML_DIR</filename>. I have set
<literal>SGML_DIR</literal>=<filename>e:\sgml</filename> and collected
all my different doctype directories under
<filename>$SGML_DIR/sys</filename>. The <literal>.pmd</literal> files
live in their respective doctype directories, but they could just as
well be collected in
<filename>$SGML_DIR/sys</filename>.</para></listitem>
<listitem><para>When displaying the file selection dialog for the
selection of an SGML file for processing, Pomade looks whether there
exists a subdirectory named <filename>documents</filename> of the
BASE_DIR defined in the <literal>.pmd</literal> file. If so, it will
display this directory, otherwise selection starts from
<filename>BASE_DIR</filename>
itself.</para></listitem></itemizedlist></para></sect2></sect1>
<sect1><title>A sample session</title> <para>In this section, we'll
walk through a sample Pomade session to give you a feeling of what you
can do with Pomade. This will give you a better background for the
next section covering the syntax of the application specification
file.</para> <sect2><title>Starting Pomade</title> <para>If you use
Pomade on a Unix system, you have to call
<filename>pomade.tcl</filename>, either from a shell prompt or from
your preferred window manager. Make sure you have a Tcl interpreter
(version >= 8.0p2) named <command>wish</command> in your
<literal>PATH</literal>. You may optionally add the name of a
<literal>.pmd</literal> file as the first (and only) argument. Here is
an example:</para> <para><userinput>cd
/home/dilbert/sgml/sys/docbook</userinput> </para> <para>
<userinput>/home/dilbert/sgml/tools/pomade/pomade.tcl
docbook.pmd</userinput></para> <para>If you use Pomade on Windows, the
installation of the Tcl interpreter will have associated the
<literal>.tcl</literal> extension with the <literal>wish</literal>
interpreter, so double clicking on <filename>pomade.tcl</filename> in
the Explorer or on an associated desktop icon will start Pomade.
Optionally, you may associate the <literal>.pmd</literal> extension
with <filename>pomade.tcl</filename> to make a double click on, say,
<filename>docbook.pmd</filename> start Pomade with the Docbook
application.</para> <para>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 <literal>.pmd</literal> file as call argument).</para>
<para><screenshot><graphic role = "importedgraphic"
    entityref = "graphic2"></graphic></screenshot></para>
<para>In the screen shot you see that the <literal>.pmd</literal> file
is in the docbook directory, which contains the following
subdirectories:<itemizedlist> <listitem><para><filename>dtd</filename>
with the standard Docbook DTD distribution (version
3.0).</para></listitem> <listitem><para><filename>dsssl</filename>,
containing Norman Walsh's Modular Docbook
Stylesheets.</para></listitem>
<listitem><para><filename>documents</filename>, containing several
documents both of my own and by others.</para></listitem>
<listitem><para><filename>tmp</filename>, where Pomade stores its
temporary files. This directory is created if it doesn't
exist.</para></listitem></itemizedlist></para> <para>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. At this point, you know that Pomade has
sucessfully read and processed your application specification
file.</para> <para>The directory shown will be the subdirectory
<literal>documents</literal> of the <literal>BASE_DIR</literal>
defined in the <literal>docbook.pmd</literal> file. You navigate the
file system and select a file to process, for example this
document:</para> <screenshot><graphic role = "importedgraphic"
entityref = "graphic3"></graphic></screenshot> <para>At this point,
Pomade will silently register your choice but do nothing with the
selected file (not even parse it). Instead, it will display its main
window as configured by the application specification in
<filename>docbook.pmd</filename>. 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.)</para>
<para><screenshot><graphic role = "importedgraphic"
    entityref = "graphic4"></graphic></screenshot></para></sect2>
<sect2><title>Adjusting the options</title> <para>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.</para> <para>Each of the buttons in the middle part of
the window opens a window that offers several choices giving you
access to the configuration variables of the Docbook DSSSL scripts.
The Pages button of the Print output format, for example, activates
this window:</para> <para><screenshot><graphic role =
"importedgraphic"
    entityref = "graphic5"></graphic></screenshot></para>
<para>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.</para> <para>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 it isn't happy with this
value.</para> <para>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 <literal>PUBLIC</literal> and
<literal>SYSTEM</literal> identifiers; in the Docbook application it
is (only) used for the selection of the language for generated text.
(And this is only a proposal, because it's implemented without a
<literal>PUBLIC</literal> identifier in the current
distribution.)</para></sect2> <sect2><title>Running Jade</title>
<para>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.)</para>
<para>If things go well, you will see the message "Ok" in the log
window; in the other case, Pomade will, in addition to it's own error
message in the log window, show you Jade's error messages in a
window.</para></sect2></sect1> <sect1><title>A sample
<literal>.pmd</literal> file</title> <para>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. Note that the comments from
the original file were stripped and line numbers added for better
readability.</para> <sect2><title>The file listing</title>
<para><literallayout> 01  POMADE_APP=Docbook 02  BASE_DIR=. 03 
LOCAL_CATALOG_FILES=dsssl/CATALOG 04 
SEARCH_DIRS=tmp:dtd:dsssl/common:dsssl/lib 05 06  MAPPINGS=language 07
 PUBLIC_ID(language)="-//user//DOCUMENT generated text//EN" 08 
SYSTEM_ID(language:german)=dbl1dege.dsl 09 
SYSTEM_ID(language:english)=dbl1usen.dsl 10 
SYSTEM_ID(language:russian)=dbl1ru.dsl

11  FORMATGROUP HTML
12  JADE_BACKENDS=SGML
13  DSSSL_SCRIPT=dsssl/html/docbook.dsl
14
15  PARAGROUP Autonumbering 
16  PARA autonumber chapters?:%chapter-autolabel%:BOOLEAN:1
17  PARA autonumber sections?:%section-autolabel%:BOOLEAN:1
18
19  PARAGROUP Table of Contents
20  PARA generate toc?:%generate-toc%:BOOLEAN:1
21  PARA generate toc for sets?:%generate-set-toc%:BOOLEAN:1
22  PARA force chapter toc?:%force-chapter-toc%:BOOLEAN:0
23
24  PARAGROUP Misc
25  PARA level for simple sections:%default-simplesect-level%:NUMBER:4
26  PARA function synopsis
style:%funcsynopsis-style%:CHOICE:'ansi@'k&#38;r 27  PARA title
page?:%generate-titlepage%:BOOLEAN:1 28  PARA one single HTML
file?:nochunks:BOOLEAN:1 29 30  FORMATGROUP Print 31 
JADE_BACKENDS=RTF:RTF-95:TeX 32  DSSSL_SCRIPT=dsssl/print/docbook.dsl
33 34  PARAGROUP Autonumbering 35  PARA autonumber
chapters?:%chapter-autolabel%:BOOLEAN:1 36 37  PARAGROUP Pages 38 
PARA page size:%paper-type%:CHOICE:"A4"@"USletter" 39  PARA two sided
output?:%two-side%:BOOLEAN:0 40  PARA left
margin:%left-margin%:NUMBER:1.5cm 41  PARA right
margin:%right-margin%:NUMBER:1cm 42  PARA produce running
heads?:%chap-app-running-heads%:BOOLEAN:1 43  PARA autonumber running
heads?:%chap-app-running-head-autolabel%:BOOLEAN:1 44 45  PARAGROUP
Fonts 46  PARA body font:%body-font-family%:CHOICE:"Times"@"Helvetica"
47  PARA fixed width font:%mono-font-family%:CHOICE:"Courier" 48  PARA
title font:%title-font-family%:CHOICE:"Helvetica"@"Times" 49 50 
PARAGROUP Indentation 51  PARA indentation for block
elements:%block-start-indent%:NUMBER:0pt 52  PARA indentation for body
text:%body-start-indent%:NUMBER:0.5cm 53 54  PARAGROUP Justification
55  PARA component subtitle
justification:%component-subtitle-quadding%:CHOICE:'start@'center@'end
56  PARA component title
justification:%component-title-quadding%:CHOICE:'start@'center@'end 57
 PARA default
justification:%default-quadding%:CHOICE:'start@'center@'end
</literallayout></para></sect2> <sect2><title>The comments</title>
<sect3><title>Line 1: <literal>POMADE_APP</literal></title> <para>Line
1 contains 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 Pomade's main window.</para></sect3>
<sect3><title>Line 2: <literal>BASE_DIR</literal></title> <para>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 (<filename>LOCAL_CATALOG_FILES</filename>,
<filename>SEARCH_DIRS</filename>, <filename>DSSSL_SCRIPT</filename>).
In the example, the value <filename>.</filename> means that the
directory where the <literal>.pmd</literal> file is located is the
base directory.</para></sect3> <sect3><title>Line 3:
<literal>LOCAL_CATALOG_FILES</literal></title> <para>This line
specifies a colon separated list of application specific catalog files
that are used in addition to those defined in the environment variable
<literal>SGML_CATALOG_FILES</literal>. In the example, there is no
colon because we have just one file. (Remember that
<filename>CATALOG</filename> lives in the subdirectory
<filename>dsssl</filename> of the <literal>.pmd</literal> file's
directory.)</para></sect3> <sect3><title>Line 4:
<literal>SEARCH_DIRS</literal></title> <para>Jade offers the
possibility of specifying directories where files are searched that
are needed for satisfying a <literal>PUBLIC->SYSTEM</literal>
identifier mapping but cannot be found by their given path name. Here
we have specified that the subdirectories <filename>tmp</filename>,
<filename>dtd</filename>, <filename>dsssl/common</filename>and
<filename>dsssl/lib</filename> of <literal>BASE_DIR</literal> are to
be searched for such files.</para></sect3> <sect3><title>Line 6:
<literal>OPTIONS</literal></title> <para>The
<literal>MAPPINGS</literal> line gives one or more symbolic names for
options that can be specified by a <literal>PUBLIC->SYSTEM</literal>
identifier mapping. In this case, we use it only once, for selecting a
language.</para> <para>Each mapping will be displayed as a cascade
button in the Mappings menu of Pomade's main window.</para>
<para><screenshot><graphic role = "importedgraphic"
    entityref = "graphic6"></graphic></screenshot></para></sect3>
<sect3><title>Line 7: <literal>PUBLIC_ID(...)</literal></title>
<para>This specifies the <literal>PUBLIC</literal> identifier that is
used for the mapping with the symbolic name
<literal>language</literal> mentioned above. This identifier must, of
course, be used somewhere (either in the DTD or in a DSSSL script) to
have any effect.</para> <para>This line does not have any effect on
Pomade's user interface.</para></sect3> <sect3><title>Lines 8-9:
<literal>SYSTEM_ID(...)</literal></title> <para>Each of these lines
specifies a possible value for the mapping with the symbolic name
<literal>language</literal>. and associates a SYSTEM identifier with
it. You see these values as choices in the submenu in the picture
above, with the first one preselected.</para></sect3>
<sect3><title>Line 11/30: <literal>FORMATGROUP</literal></title>
<para>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.</para></sect3>
<sect3><title>Lines 12/31: <literal>JADE_BACKENDS</literal></title>
<para>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.</para></sect3>
<sect3><title>Lines 13/32: <literal>DSSSL_SCRIPT</literal></title>
<para>Each format group needs its DSSSL script, and here you specify
which one is it. Note again that you can use a relative name
here.</para></sect3> <sect3><title>Lines 15/19/24/34/37/45/50/54:
<literal>PARAGROUP</literal></title> <para>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
<literal>PARAGROUP</literal>'s parameters.</para>
<para><screenshot><graphic role = "importedgraphic"
    entityref = "graphic7"></graphic></screenshot></para></sect3>
<sect3><title>Lines 16-17/20-22/...: <literal>PARA</literal></title>
<para>Here the parameters proper are specified. Each
<literal>PARA</literal> line belongs to the last
<literal>PARAGROUP</literal> the parser has seen.</para> <para>Each of
the <literal>PARA</literal> lines should correspond to a configurable
parameter in a DSSSL script (otherwise it makes no sense). </para>
<para>Let's take the first one (line 16) as an example. It consists of
four entries, separated by colons:</para>
<variablelist><varlistentry><term>Variable Description
(<literal>autonumber chapters?</literal>)</term> <listitem><para>This
is the name of the variable as it appears in the user interface, i.e.
in the dialog box of it's
<literal>PARAGROUP</literal>.</para></listitem></varlistentry>
<varlistentry><term>Variable name
(<literal>%chapter-autolabel%</literal>)</term> <listitem><para>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).</para></listitem></varlistentry>
<varlistentry><term>Variable Type (<literal>BOOLEAN</literal>)</term>
<listitem><para>Pomade knows three types of variables all of which
appear in this example:</para>
<variablelist><varlistentry><term><literal>NUMBER</literal></term>
<listitem><para>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" (line 25) has to be an integer, while "left margin"
in line 40 may be 1.5cm. In addition, The user has to respect DSSSL's
syntax for numbers (decimal <emphasis>point</emphasis>, not comma as
in Germany).</para></listitem></varlistentry>
<varlistentry><term><literal>BOOLEAN</literal></term>
<listitem><para>This is 0 or 1, which is mapped to
<literal>#f</literal> and <literal>#t</literal> in the DSSSL file. In
the user interface, you see a
checkbutton.</para></listitem></varlistentry>
<varlistentry><term><literal>CHOICE</literal></term>
<listitem><para>Here the user can select between other values than
simply true or false, for example A4 and USletter as in the page
format (line 38). Note that the choices are separated by an ampersand
character (@) and must be written <emphasis>exactly</emphasis> as they
appear in the DSSSL
file.</para></listitem></varlistentry></variablelist></listitem></varl
istentry> <varlistentry><term>Default value
(<literal>1</literal>)</term> <listitem><para>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 into the DSSSL file
if the user does not change it.
</para></listitem></varlistentry></variablelist> <para>There's a
hidden subtlety in the definition of the variable descrition that has
to with the implementation of the user interface elements. Their names
are built from the parameter descritions (replacing spaces by
underscores). This means that you should <emphasis>never</emphasis>
use the same descrition 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 <emphasis>can</emphasis> put this knowledge to good
use if you wanr to change a parameter in both paragroups from one
place. If you want to see an example, open the two "Autonumbering"
dialog boxes, where the same description "autonumber chapters?" has
been deliberately chosen. Click a checkbutton in one box and see the
the corresponding checkbutton in the other box automagically change
its value!<screenshot><graphic role = "importedgraphic"
    entityref = "graphic8"></graphic></screenshot><screenshot><graphic
    role = "importedgraphic" entityref =
    "graphic9"></graphic></screenshot></para></sect3></sect2></sect1>
<appendix>
<title>Resources</title>
<sect1><title>Docbook</title>
<para>You find the Docbook DTD at <ulink
url="http://www.oreilly.com/davenport/docbook/current";> O'Reilly's web
site</ulink>. Norman Walsh's Modular Docbook Stylesheets are located
at his <ulink url="http://nwalsh.com/docbook/dsssl";>web
site</ulink>.</para></sect1> <sect1><title>Tcl/Tk</title> <para>For
downloading Tcl/Tk, see <ulink
url="http://sunscript.sun.com/TclTkCore";> Sun's Tcl download
page.</ulink></para></sect1></appendix></article>

=====================================================================

Andreas Saremba
Amselweg 19, 14656 Brieselang
Tel. 033232/38264
Email: andreas.saremba@xxxxxxxxxxx


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist