Subject: [ANN] Pomade - Poor Man's DSSSL Environment From: Andreas.Saremba@xxxxxxxxxxx (Andreas Saremba) Date: Mon, 20 Apr 1998 20:30:55 +0000 Comments: Authenticated sender is <00002168067203323238264#0001@pop.btx.dtag.de> |
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 & 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&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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: Creating a Title Page (STILL!), Norman Walsh | Thread | Sorting like elements, Steven L. Anderson |
Re: Creating a Title Page (STILL!), Chuck Darney | Date | Sorting like elements, Steven L. Anderson |
Month |