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 NOTES: 12/2/96 =============== The docbook-to-man package made available on 12/2/96 includes the following changes from the previous version (circa August '96): 1. A fix for missing newlines in the -man output 2. The − character entity is now mapped to "-" (rather than "\(mi").