README
1
2
3June 14, 1996
4
5Fred Dalrymple
6
7
8Overview
9========
10
11This directory contains all pieces of the docbook-to-man tool -- a
12batch converter that transforms UNIX-style manpages from the DocBook
13SGML DTD into nroff/troff -man macros.
14
15
16Acknowledgements
17================
18
19The following companies generously funded the development of this public
20tool as part of the CDE/Motif Project under the auspices of the Open
21Software 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
32SETUP NOTES
33===========
34
35This tool presumes that nsgmls and the DocBook DTDs have been installed
36into "default" places. Mainly, this means where the DTD files are
37expected to be found (/usr/local/sgmls, /usr/local/sgmls/Davenport/dtd).
38If you've installed them elsewhere, please modify the paths at the top
39of cmd/docbook-to-man.sh before installing this tool (or, change it and
40reinstall it).
41
42
43INSTALLATION
44============
45
46This tool installs binaries for the instant and docbook-to-man programs
47into /usr/local/bin, and the "transpec" into /usr/local/lib/tpt. It is
48assumed that /usr/local and /usr/local/lib exist, but the
49Transpec/Makefile will attempt to create /usr/local/lib/tpt if it does
50not already exist. You must have permissions to write into /usr/local/bin
51and /usr/local/lib to install these tools.
52
53Assuming you've made and changes as noted in "SETUP NOTES" above, you
54should be able to install this tool by issuing a "make install" from
55the the current directory (the one containing this README file).
56Generated binaries can be cleaned up from the source directories by
57issuing a "make clobber".
58
59The documentation in Doc/ is not installed automatically, you should
60copy the files named Doc/instant.1 and Doc/transpec.1 into the proper
61place (eg, /usr/local/man/man1) if you want to make them available online.
62
63
64
65Components of the Tool
66======================
67
68User-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
75SGML 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
83Converter 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
92Converter script: docbook-to-man.ts
93
94 The instant script which drives the mapping between SGML and -man.
95
96DocBook 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
105KNOWN 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
129BUG POLICY
130==========
131
132I would like to hear of any problems, improvements, or suggestions.
133This tool will continue to be enhanced. Significant improvements
134will appear in the FTP-able version. However, there is no guarantee
135of turnaround time for problem reports...
136
137Please send correspondence to fld@veloce.com
138
139