June 14, 1996
Fred Dalrymple
Overview
========
This directory contains all pieces of the docbook-to-man tool -- a
batch converter that transforms UNIX-style manpages from the DocBook
SGML DTD into nroff/troff -man macros.
Acknowledgements
================
The following companies generously funded the development of this public
tool as part of the CDE/Motif Project under the auspices of the Open
Software Foundation:
Hewlett-Packard Company
International Business Machines Corp.
Sun Microsystems, Inc.
Novell, Inc.
Digital Equipment Corp.
Fujitsu Limited
Hitachi, Ltd.
SETUP NOTES
===========
This tool presumes that nsgmls and the DocBook DTDs have been installed
into "default" places. Mainly, this means where the DTD files are
expected to be found (/usr/local/sgmls, /usr/local/sgmls/Davenport/dtd).
If you've installed them elsewhere, please modify the paths at the top
of cmd/docbook-to-man.sh before installing this tool (or, change it and
reinstall it).
INSTALLATION
============
This tool installs binaries for the instant and docbook-to-man programs
into /usr/local/bin, and the "transpec" into /usr/local/lib/tpt. It is
assumed that /usr/local and /usr/local/lib exist, but the
Transpec/Makefile will attempt to create /usr/local/lib/tpt if it does
not already exist. You must have permissions to write into /usr/local/bin
and /usr/local/lib to install these tools.
Assuming you've made and changes as noted in "SETUP NOTES" above, you
should be able to install this tool by issuing a "make install" from
the the current directory (the one containing this README file).
Generated binaries can be cleaned up from the source directories by
issuing a "make clobber".
The documentation in Doc/ is not installed automatically, you should
copy the files named Doc/instant.1 and Doc/transpec.1 into the proper
place (eg, /usr/local/man/man1) if you want to make them available online.
Components of the Tool
======================
User-level command: docbook-to-man
A new shell command that runs the low-level components to translate
a single DocBook SGML document instance (whose document element is
) into pretty-much vanilla -man macros, with tables
rendered in tbl.
SGML parsing engine: nsgmls (or sgmls)
** not included in this package -- see ftp://ftp.jclark.com/pub/sp **
The nsgmls or sgmls tool is called to parse a DocBook
instance and generate ESIS which is the input to the instant
program.
Converter engine: instant
A tool originally developed at OSF (by John Bowe) but appearing
here in significantly enhanced form (work performed by John
Lavagnino, Carl Scholz, and particularly Fred Dalrymple). The
most significant enhancement is probably support for CALS tables
(which DocBook uses). Sorry, only the CALS -> tbl functionality
works in this version.
Converter script: docbook-to-man.ts
The instant script which drives the mapping between SGML and -man.
DocBook DTD: docbook.cat, docbook.dcl, docbook.dtd
The tool supports DocBook V 2.4.1.
** not included in this package -- see
ftp://ftp.ora.com/pub/davenport/docbook/docbk241.tar.Z **
KNOWN DEFICIENCIES
==================
1. The current transpec generates \fP to return to a previous font,
yet there may be nested font changes. It is possible that this
script will generate two \fPs in a row, returning the font to
not the original, but the "inner" font. The transpec with the
"-PUSHPOP" name in the Transpec source directory is some initial
work to resolve this problem, but it has other problems..
2. There are some CALS table features which aren't implemented (yet).
Including tables within tables ().
3. Numbered lists use an indent of 6 characters, while indented
paragraphs (eg, a second within an ) will generate a 10 character indent. Indents should
be made consistent.
4. The graphic inclusion is untested because I don't own a real
Documentor's Workbench (and the code for generating the graphic
include doesn't seem to work with Linux).
BUG POLICY
==========
I would like to hear of any problems, improvements, or suggestions.
This tool will continue to be enhanced. Significant improvements
will appear in the FTP-able version. However, there is no guarantee
of turnaround time for problem reports...
Please send correspondence to fld@veloce.com