                           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).
