1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
|
ANS Modifications
David Bolen (db3l@ans.net)
2/23/99
This package is derived from the docbook-to-man package made available
on the Davenport (later OASIS) DocBook web site. Various modifications
were made (as described below) to resolve some issues when processing
our own documents. I have attempted to contact Fred Dalrymple with
respect to these changes, but have not received a reply.
This modified version of the package is being released AS-IS, without
any promise of support nor guarantee as to function. All I can say is
that this changed version appears to suit our needs for the generation
of man pages from our DocBook sources. I have compiled and run this
version on the following platforms:
* AIX 3.2.5 (RS/6000)
* Solaris 2.5.1 (Sparc)
* BSDI 2.1 and 4.0 (i386)
* Linux 2.0.36 (Slackware - i386)
* FreeBSD 2.2.7-RELEASE (i386)
We use the package as follows:
* Install Jade and DocBook as normal - the command below assumes that
the 'onsgmls' binary is available to parse a DocBook document.
* Install 'instant' binary into appropriate directory (/usr/local/bin
or wherever).
* Place these auxiliary files into /usr/local/share/sgml/transpec:
* One of either docbook-to-man.ts or the pair of
docbook-to-man.ts-PUSHPOP and docbook-to-man.prolog. We
use the PUSHPOP version but rename to just .ts.
* roff.cmap
* roff.sdata
* Translate a source with a command such as (shown on multiple lines
but entered as a single line command):
onsgmls -i roff {document} |
instant -t docbook-to-man.ts -c roff.cmap -s roff.sdata > {output}
This assumes a document with a RefEntry as the top level element.
To extract a single RefEntry from a larger document, the "-i id"
option should be given to instant. For documents containing a
number of RefEntry elements, the initial onsgmls output may be saved
and reused for each instant execution (thus saving the SGML parsing
overhead).
Note: the "-i roff" to onsgmls is not required, but we use that to
control conditional entities in our documents)
-- David
- - - - - - - - - - - - - - - - - - - - - - - - -
Modifications
Most significant changes are notated within the source with "[ANS-db3l]"
along with explanatory comments, but such markup is not exhaustive.
The primary changes made were as described below. A patch file with the
exact set of changes (already contained in the files, patch based on
FLD's 6/4/1996 release) can be found in the root directory of the
package as ans.patch.
General
-------
* Adjusted default file location (used for .ts, .cmap, .sdata files)
to /usr/local/share/sgml/transpec. Controlled by TPTLIB definition
in Makefiles, or can be overridden at run-time by TPT_LIB
environment variable or "-l" command line option.
* Use STRERROR define (in Instant and Instant/tptregexp Makefiles) to
conditionally include strerror() replacement function. Does not
include by default. Should be re-defined for older Sun systems
for example, but its presence by default was causing crashes on
systems such as FreeBSD and BSDI in calls to perror().
Instant
-------
* Process ESIS data for document (output from onsgmls) during the first
stage of input rather than waiting until eventual output in the
DoData/OutputString functions. The "pre-processing" handles
quoting, CMAP and SDATA and cleans up a lot of the trickier issues
with "\" translation in the earlier code, since "\" is used both by
onsgmls for quoting as well as by the instant output processing for
items such as the cmap file.
* Absorb whitespace during ESIS parsing unless within an environment
that has a FORMAT of LINESPECIFIC (or has inherited such a format
from a parent environment). Previously, docbook-to-man would only
work best if the input document had no extraneous indentation. This
caused problems if, for example, the input document was written in
Emacs with PSGML with sgml-indent-data. Such extraneous whitespace
in the output often caused erroneous paragraph breaks or wide
regions of spacing within paragraphs.
The current parsing has worked in the documents I have thrown at it
so far. If necessary, the existing (but undocumented) "-d" option
may be used to implement the previously existing "datahack" option
or "-d -d" may be used to restore the previously default behavior of
no whitespace adjustment at all.
* Some adjustment made for the CALS table support, generally dealing
with rows containing spanning columns, or tables that changed their
row definitions within the table.
*.ts
----
* Prolog includes header to automatically include table support on
Solaris. This appears system specific (works under Solaris), but
ignored on other systems (it's a roff comment), so on most other
systems the output will still need to be manually sent through tbl
or an adjustment must be made appropriate to the system (such as
an appropriate file extension or another option to man).
* Always reset tab definitions after use of ".nf"
* Fixed XREF to use the title if no XREFLABEL available.
* Added TITLE in REFSYNOPSYSDIV, and PROMPT in general.
* Tidied up cross reference text.
* Moved pf/fP macros into external .prolog file, now included by the
PUSHPOP version. This removes the dependence on the controlling
shell script to manually append the definition.
Note that while both the normal and "PUSHPOP" versions of the transpec
files were adjusted, we use the PUSHPOP version for our own
conversions. So far, I haven't noticed any significant problems (as
alluded to in the older README) - some of this may be due to
side-effects of the above parsing changes to Instant.
roff.cmap
---------
* Added back in the \ -> \e sequence so that actual backslashes in the
input source are properly escaped in the roff output. (This works
cleanly now with the above parsing changes to Instant).
roff.sdata
----------
* Map vellip to be hellip (personal preference given lack of options).
|