home
software
  sgml
    sgmlnt
    refdb
    dbslide
    sop
  scientific sw
  cygwin ports
  hacks
  history
photography
about
contact

SOP

A DTD and stylesheets for method sheets and SOPs:

Overview

Overview

The SOP DTD is designed to write biomedical method sheets and standard operating procedures. It sports all necessary features to write nice-looking and, more important, complete and thorough method sheets. Besides standard elements like itemized lists and tables there are some specific elements to describe the chemicals you use and to describe the solutions that you have to prepare. It is possible to use these elements as hyperlinks, so the reader is left with no doubt which chemical he has to use (this feature works best in HTML and RTF output). The link elements can "pull in" the displayed text from the link target to obtain uniform spelling throughout the document even with long and complicated chemical names.

Some optional elements allow to convert SOP documents to standard operating procedures. E.g. each document can have a unique ID, and there are elements for persons who have to approve methods and elements for persons who have to be trained on a method.

While the SOP DTD is well suited to write individual method sheets, the real fun starts if you set up a method repository for your workgroup or department. Pooling knowledge and making things accessible makes a lot of sense anyway, but finding and recycling existing information is a snap with sgrep and the provided m4 macros.

License information

The package is released under the GNU General Public License. This essentially allows you to distribute and modify the stuff for commercial or non-commercial purposes with some constraints. Read the GPL for the legalese.

Download information

The current version is 1.4, released on 03-07-01.

The SOP DTD package comes in two flavors. The contents are identical, except that sop.tar.gz contains all files with Unix-style LF instead of CR/LF as line endings, just in case:

sop.zip (202 kb)
sop.tar.gz (99 kb)

Example

A real-world example of a method sheet written with the SOP DTD and transformed with the SOP stylesheets is available as a HTML page and as a PDF file. To see how it works check out the SGML source.

Package contents

However, you're not left alone with just a DTD. The package contains:

DSSSL stylesheets to render the documents as HTML, RTF, MIF, DVI, PostScript, or PDF documents. It is easy to provide the same document as a printed version for the lab bench and as a HTML version for informational purposes on the intranet.
Bash scripts to run the transformation with Jade (and TeX/PDFTeX/dvips where necessary). These are some simple scripts which minimize the fingertwisting necessary to convert the SGML source to the desired output format.
m4 macros for use with sgrep to retrieve information or textual content from your SOP documents. sgrep and the macros make it easy to search for any kind of information in existing documents and to recycle parts of existing documents when you write new documents.
an embarrassingly crude but still helpful patch for PSGML which lets you display chapters, sections, links, and link targets in speedbar and jump to the locations with a mouseclick. This is very convenient to keep track of your links and link targets when hyperlinking your document. The patches also provide the same functionality for HTML and DocBook DTDs. To remind you that imenu support is available for a given DTD, an exclamation mark is added to the identifier string in the Emacs modeline. Please be warned that the code is extremely crude and perfectly reflects my close-to-nil Lisp knowledge.
and, of course, full documentation for both the DTD and the m4 macros.

Prerequisites

You need a functional SGML system which allows the desired transformations with DSSSL. You'll need at least Jade or its successor, OpenJade. You'll also need a TeX installation if you plan to use the TeX backend (for DVI, PostScript, and PDF output). For a suggestion how to set up a free SGML system on the Win32 platform, see SGML for Windows NT. Many Linux distributions (the most complete with regard to SGML seems to be Debian) allow to install such a system with just a few packages, and TeX and friends are included anyway. The software also compiles on a variety of other Unices.

In addition to the SGML stuff you should install sgrep and m4. sgrep is a grep-like tool for structured texts of any kind. The authors also provide a Win32 binary including a version of the macro preprocessor m4. The latter is available for other platforms at the GNU ftp site and should compile on any Unix-like system. Most Linux distributions contain it anyway. A Win32 version is also included in the free Cygwin tools. sgrep for Cygwin can be found here.

Life will also be easier if you have a Bash (Bourne again shell) on your system to run the included shell scripts. Bash is part of all (afaik) Linux distributions and will compile on most Unix systems. A Win32 port is available with the free CygWin tools.

Installation of the components

To install the various parts of this package, follow these instructions:

sop.dtd and catalog

Copy sop.dtd and catalog to a convenient directory and include the full path to catalog in your SGML_CATALOG_FILES environment variable. Alternatively, append the contents of catalog to an existing catalog file and adjust the path accordingly.

The DSSSL stylesheets sop.dsl, sop-html.dsl, and sopcommon.dsl

Copy the stylesheets to a convenient directory. Make customizations, or make copies and customize these. The files sop.dsl and sop-html.dsl start with a section of customizable variables, which should satisfy most needs.

sopjade

Select the script which matches your needs (either sopjade-miktex or sopjade-tetex, depending on your TeX package) and copy or rename it to sopjade. This file should reside in a directory which is in your $PATH, probably ~/scripts. If necessary, make the script executable by issuing chmod u+x sopjade. Adjust the paths to the stylesheets in the first few lines of the scripts.

sop.m4

Copy sop.m4 to a convenient directory. You may want to include this file into the SGREPOPT environment variable. To this end, run export SGREPOPT='-p m4 -f /full/path/to/sop.m4' in your Bash or in a Bash startup file.

The PSGML diffs

Apply these patches to any recent version of PSGML (1.1.6, 1.2.0, 1.2.1 were tested). Copy the two diff files to your PSGML directory, make backup copies of psgml.el and psgml-parse.el, and patch these files with the commands:

cd /where/your/psgml/files/are
patch -u psgml.el psgml.diff
patch -u psgml-parse.el psgml-parse.diff

Don't forget to recompile the files after patching.

The documentation

The folder sop in the archive contains the DTD documentation which was created with Norm Walsh's fabulous dtdparse scripts and sgrep. The documentation contains a thorough description of all elements including their content models and parent/child relationships. Each element description contains a short example which shows the usage.

The folder sopdoku contains the documentation for the sop.m4 macros and their use with sgrep. Start to read the HTML version with the file book1.html or print out the PostScript version. The SGML/DocBook3.1 source is also included in case you wish to use a different output format.