| 1 |
|
| 2 |
|
| 3 |
June 14, 1996 |
| 4 |
|
| 5 |
Fred Dalrymple |
| 6 |
|
| 7 |
|
| 8 |
Overview |
| 9 |
======== |
| 10 |
|
| 11 |
This directory contains all pieces of the docbook-to-man tool -- a |
| 12 |
batch converter that transforms UNIX-style manpages from the DocBook |
| 13 |
SGML DTD into nroff/troff -man macros. |
| 14 |
|
| 15 |
|
| 16 |
Acknowledgements |
| 17 |
================ |
| 18 |
|
| 19 |
The following companies generously funded the development of this public |
| 20 |
tool as part of the CDE/Motif Project under the auspices of the Open |
| 21 |
Software Foundation: |
| 22 |
|
| 23 |
Hewlett-Packard Company |
| 24 |
International Business Machines Corp. |
| 25 |
Sun Microsystems, Inc. |
| 26 |
Novell, Inc. |
| 27 |
Digital Equipment Corp. |
| 28 |
Fujitsu Limited |
| 29 |
Hitachi, Ltd. |
| 30 |
|
| 31 |
|
| 32 |
SETUP NOTES |
| 33 |
=========== |
| 34 |
|
| 35 |
This tool presumes that nsgmls and the DocBook DTDs have been installed |
| 36 |
into "default" places. Mainly, this means where the DTD files are |
| 37 |
expected to be found (/usr/local/sgmls, /usr/local/sgmls/Davenport/dtd). |
| 38 |
If you've installed them elsewhere, please modify the paths at the top |
| 39 |
of cmd/docbook-to-man.sh before installing this tool (or, change it and |
| 40 |
reinstall it). |
| 41 |
|
| 42 |
|
| 43 |
INSTALLATION |
| 44 |
============ |
| 45 |
|
| 46 |
This tool installs binaries for the instant and docbook-to-man programs |
| 47 |
into /usr/local/bin, and the "transpec" into /usr/local/lib/tpt. It is |
| 48 |
assumed that /usr/local and /usr/local/lib exist, but the |
| 49 |
Transpec/Makefile will attempt to create /usr/local/lib/tpt if it does |
| 50 |
not already exist. You must have permissions to write into /usr/local/bin |
| 51 |
and /usr/local/lib to install these tools. |
| 52 |
|
| 53 |
Assuming you've made and changes as noted in "SETUP NOTES" above, you |
| 54 |
should be able to install this tool by issuing a "make install" from |
| 55 |
the the current directory (the one containing this README file). |
| 56 |
Generated binaries can be cleaned up from the source directories by |
| 57 |
issuing a "make clobber". |
| 58 |
|
| 59 |
The documentation in Doc/ is not installed automatically, you should |
| 60 |
copy the files named Doc/instant.1 and Doc/transpec.1 into the proper |
| 61 |
place (eg, /usr/local/man/man1) if you want to make them available online. |
| 62 |
|
| 63 |
|
| 64 |
|
| 65 |
Components of the Tool |
| 66 |
====================== |
| 67 |
|
| 68 |
User-level command: docbook-to-man |
| 69 |
|
| 70 |
A new shell command that runs the low-level components to translate |
| 71 |
a single DocBook SGML document instance (whose document element is |
| 72 |
<RefEntry>) into pretty-much vanilla -man macros, with tables |
| 73 |
rendered in tbl. |
| 74 |
|
| 75 |
SGML parsing engine: nsgmls (or sgmls) |
| 76 |
|
| 77 |
** not included in this package -- see ftp://ftp.jclark.com/pub/sp ** |
| 78 |
|
| 79 |
The nsgmls or sgmls tool is called to parse a DocBook <RefEntry> |
| 80 |
instance and generate ESIS which is the input to the instant |
| 81 |
program. |
| 82 |
|
| 83 |
Converter engine: instant |
| 84 |
|
| 85 |
A tool originally developed at OSF (by John Bowe) but appearing |
| 86 |
here in significantly enhanced form (work performed by John |
| 87 |
Lavagnino, Carl Scholz, and particularly Fred Dalrymple). The |
| 88 |
most significant enhancement is probably support for CALS tables |
| 89 |
(which DocBook uses). Sorry, only the CALS -> tbl functionality |
| 90 |
works in this version. |
| 91 |
|
| 92 |
Converter script: docbook-to-man.ts |
| 93 |
|
| 94 |
The instant script which drives the mapping between SGML and -man. |
| 95 |
|
| 96 |
DocBook DTD: docbook.cat, docbook.dcl, docbook.dtd |
| 97 |
|
| 98 |
The tool supports DocBook V 2.4.1. |
| 99 |
|
| 100 |
** not included in this package -- see |
| 101 |
ftp://ftp.ora.com/pub/davenport/docbook/docbk241.tar.Z ** |
| 102 |
|
| 103 |
|
| 104 |
|
| 105 |
KNOWN DEFICIENCIES |
| 106 |
================== |
| 107 |
|
| 108 |
1. The current transpec generates \fP to return to a previous font, |
| 109 |
yet there may be nested font changes. It is possible that this |
| 110 |
script will generate two \fPs in a row, returning the font to |
| 111 |
not the original, but the "inner" font. The transpec with the |
| 112 |
"-PUSHPOP" name in the Transpec source directory is some initial |
| 113 |
work to resolve this problem, but it has other problems.. |
| 114 |
|
| 115 |
2. There are some CALS table features which aren't implemented (yet). |
| 116 |
Including tables within tables (<EntryTbl>). |
| 117 |
|
| 118 |
3. Numbered lists use an indent of 6 characters, while indented |
| 119 |
paragraphs (eg, a second <Para> within an <OrderedList> |
| 120 |
<ListItem>) will generate a 10 character indent. Indents should |
| 121 |
be made consistent. |
| 122 |
|
| 123 |
4. The graphic inclusion is untested because I don't own a real |
| 124 |
Documentor's Workbench (and the code for generating the graphic |
| 125 |
include doesn't seem to work with Linux). |
| 126 |
|
| 127 |
|
| 128 |
|
| 129 |
BUG POLICY |
| 130 |
========== |
| 131 |
|
| 132 |
I would like to hear of any problems, improvements, or suggestions. |
| 133 |
This tool will continue to be enhanced. Significant improvements |
| 134 |
will appear in the FTP-able version. However, there is no guarantee |
| 135 |
of turnaround time for problem reports... |
| 136 |
|
| 137 |
Please send correspondence to [email protected] |
| 138 |
|