man pages screwed

[Jim Knoble]

Circa 2001-Apr-16 09:02:52 -0500 dixit Mark D. Roth:

: On Mon Apr 16 02:44 2001 -0400, Jim Knoble wrote:
: > Hmm ... wouldn't it be better to actually detect whether the -mdoc
: > macros were available rather than defaulting to -man for non-BSD
: > systems?  Most releases of GNU groff have pretty good -mdoc macros and
: 
: I thought of this as well, but I wasn't sure how portable it was to
: some of the more esoteric systems which I don't have access to.
: There's also the problem of avoiding mis-detection; even if groff is
: installed, the man command on many systems will only invoke the vendor
: version.

True; see below.

: In general, I do prefer manual testing to hard-coded assumptions when
: it comes to autoconf.  However, the OpenSSH configure.in already has a
: lot of hard-coded assumptions for many platforms, so that battle has
: already been lost.  Also, I wasn't too worried about the wrong choice
: being made, since the --with-mantype option allows the user to
: manually force the desired behavior.

True; but it doesn't make sense to me to translate -mdoc to -man by
default on systems where there's a perfectly good tmac.mdoc.

: Anyway, if you'd like to take a stab at this nroff test, please feel
: free to do so.  If it can be done in a reliable way, I'm all for it.

Okay, here's what i've found from the range of systems i have access to:

  platform              man formatter   -mdoc works (status works)[*]
  --------              -------------   ------------------------------
  sparc-sun-solaris2.5: /usr/bin/nroff  no  (yes)
  parisc-hp-hpux10.20:  /usr/bin/nroff  no  (yes)
  mips-sgi-irix6.2:     /usr/bin/awf[+] no  (yes)
  rs6000-ibm-aix4.1.x:  /usr/bin/nroff  no  (yes)
  mips-dec-ultrix4.5:   /usr/bin/nroff  no  (yes)
  alpha-dec-osf3.2:     /usr/bin/nroff  no  (yes)
  i386-redhat-linux:    /usr/bin/nroff  yes (yes)
  ________
  [*] I.e., nroff returns non-zero if -mdoc doesn't work.
  [+] Yes, really.

Bearing in mind that i haven't looked at the *really* weird (SunOS-4.x,
NeXTStep/OpenStep, SCO BrokenServer or UnixWare) or esoteric (DG/UX,
CrayOS, Reliant, LynxOS, Darwin) platforms yet, nor have i checked
Cygwin, it looks as if the following is a good first cut:

  # Allow user to set NROFF if desired.
  if [ -z "${NROFF}" ]; then
    for i in nroff awf; do
      if [ -x /usr/bin/${i} ]; then
        NROFF=/usr/bin/${i}
        break
      fi
    done
  fi
  if [ -z "${NROFF}" ]; then
    MANTYPE=cat
  elif ${NROFF} -mdoc ssh.1 >/dev/null 2>&1; then
    MANTYPE=doc
  elif ${NROFF} -man ssh.1 >/dev/null 2>&1; then
    MANTYPE=man
  else
    MANTYPE=cat
  fi

This isn't much different from what i proposed earlier, except that the
system nroff (or, in the case of IRIX, awf) is used instead of the
first nroff on the PATH, and the user can set NROFF in the environment
if desired.

Ben, could you check whether this would work on {NeXT,Open}Step?

Corinna, what should Cygwin do regarding this (probably just ignore it)?

Anyone who has access to a non-listed platform (or a significantly
later version of one that is listed), please let us know whether this
would work there as well.

-- 
jim knoble | jmknoble at jmknoble.cx | http://www.jmknoble.cx/
(GnuPG fingerprint: 31C4:8AAC:F24E:A70C:4000::BBF4:289F:EAA8:1381:1491)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 249 bytes
Desc: not available
Url : http://lists.mindrot.org/pipermail/openssh-unix-dev/attachments/20010416/1ab42ff1/attachment.bin