Debian Codegraph @

README

raw ◀ ▶
1 Debian patch touch this file
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 onsgmls 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: onsgmls (or nsgmls or sgmls)
76
77 ** not included in this package -- see ftp://ftp.jclark.com/pub/sp **
78
•79 The onsgmls or nsgmls or sgmls tool is called to parse a DocBook
80 <RefEntry> instance and generate ESIS which is the input to the
81 instant 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