Subject:   -16- How can I format unformatted manpages?
Date: 23 Jun 1995 00:00:01 EST

  SGI provides manpages in formatted form, and does not therefore
  provide us all with the formatting software. Most FTPable manpages,
  however, come in nroff ("unformatted") form.

  To install an unformatted manpage, one needs to format it (more on
  this in a moment), pack it with pack(1) and put it in the appropriate
  place under one of the 'catman' directories (see man(1)).
  Alternatively, one might simply put the unformatted manpage under one
  of the 'man' directories (again, see man(1)) and let IRIX run the
  formatting software on it as needed. Which method one uses is a matter
  of taste. In any case, one needs formatting software, and that is what
  the rest of this entry is about.

  Manpages are most often formatted with 'nroff', which is a part of
  Documenter's Workbench (DWB), which SGI has had to license separately
  from USL and we have to buy separately from SGI.  SGI's DWB is based
  on version 2.1; the current version from USL is 3.3.

  You might be able to format manpages on a non-SGI machine which does
  have DWB/nroff. You might need to specify the generic printer macros
  with '-Tlp', e.g. 'nroff -man -Tlp foo.1 > foo'.

  Public domain alternatives to DWB include 'awf' and 'groff':

  Henry Spencer's awf ("Amazingly Workable Formatter") is written in
  'awk', which we all have, and does a pretty good job, considering. It
  can be FTPed from ftp://ftp.sgi.com/sgi/IRIX5.0/man/, along with a
  version of 'man' which looks for awf if nroff isn't available. It will
  come with releases of IRIX after 5.3.

  'groff' is by the Free Software Foundation and can be had from any GNU
  archive (e.g. ftp://prep.ai.mit.edu/pub/gnu/).  Compilers beware: it
  must be compiled with g++ or SGI's C++. However, there are compiled
  binaries in ftp://cb-iris.stanford.edu/pub/gnu/.  David Hinds
  <dhinds@allegro.stanford.edu>, the man who put them there, gives this
  advice for installing groff so that it can format manpages on the fly
  in IRIX 4.0.x:

  Create a script called 'eqn':

   > #!/bin/sh
   > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
   > geqn $*

  and a script called 'neqn':

   > #!/bin/sh
   > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
   > geqn -Tascii $*

  and do:

   > ln -s gnroff nroff

  and edit the end of the gnroff script to be:

   > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
   > exec groff -Wall -mtty-char $T $opts $rest

  To get PostScript output from 'man -t', you also need to create a
  'psroff' script similar to 'nroff'.  Here are the context diffs:

  *** /usr/local/bin/nroff        Sat Feb 13 15:51:09 1993
  --- /usr/local/bin/psroff       Sat Feb 13 17:45:46 1993
  ***************
  *** 1,8 ****
    #!/bin/sh
  ! # Emulate nroff with groff.

    prog="$0"
  ! T=-Tascii
    opts=

    for i
  --- 1,8 ----
    #!/bin/sh
  ! # Emulate psroff with groff.

    prog="$0"
  ! T=-Tps
    opts=

    for i
  ***************
  *** 25,30 ****
  --- 25,33 ----
          -Tascii|-Tlatin1)
                  T=$1
                  ;;
  +       -t)
  +               # ignore -- default is send to stdout
  +               ;;
          -T*)
                  # ignore other devices
                  ;;
  ***************
  *** 49,53 ****
    rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

    # This shell script is intended for use with man, so warnings are
    # probably not wanted.  Also load nroff-style character definitions.
  ! exec groff -Wall -mtty-char $T $opts $rest
  --- 52,56 ----
    rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

    # This shell script is intended for use with man, so warnings are
  ! # probably not wanted.
  ! exec groff -Wall $T $opts $rest

  The binaries on cb-iris.stanford.edu have these changes already made.

  Paul Walmsley <ccshag@cclabs.missouri.edu> offers the following
  advice for IRIX 5.x, which assumes that you have already followed
  David Hinds' instructions for IRIX 4.0.x:

  1. Remove the link from tbl to gtbl.

  2. Rename gtroff to gtroff-exe or some other suitable name.  Note
     that if you name it something other than gtroff-exe, you must
     change the gtroff script below.

  3. Install the gtroff and tbl scripts included below in place of the
     above two programs, and chmod them appropriately.

  --- cut here for tbl ---
  #!/bin/sh
  # Shoehorn gtbl into IRIX 5.2 - Shag
  # Removes the -TX from gtbl's command line - yes, I know this is a kludge

  rest=`echo ${1+"$@"} | sed -e 's+-TX++'`
  exec gtbl $rest
  --- cut here for gtroff --
  #!/bin/sh
  # Shoehorn gtroff into working with IRIX 5.2 - Shag
  # Translates all references for /usr/lib/tmac to /usr/local/lib/groff/tmac,
  # and disables warnings - from David Hinds' code

  rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
  exec gtroff-exe -Wall -mtty-char $rest
  --- you can stop cutting now ---

  It is also possible to avoid the need for these scripts by setting
  some environment variables, which are only documented in the man(1)
  manpage (q.v.) in IRIX 5.2 and later.

  Finally, under IRIX 5.3, you need to edit the 'eqn' and 'neqn' scripts
  (above) a bit more. Add the following line

      if [ ${1:-""} = - ] ; then shift ; fi

  just before the last "geqn" line.