FW: lwres problem manpages

Pam Lassen - UNIX Warrior Princess Pamela.Lassen at Compaq.com
Tue May 7 21:08:05 UTC 2002


Hello all,

It has been brought to my attention that there is a problem with some of the
manpages.  I've forwarded the message from our Documentation Engineer below.
I'm making the updates now for our current release, but it would be nice if
these were corrected.  Please let me know if you require more formal patch
info.  I'd be happy to send the diff info after my updates are done.

The problem manpages were found with -
panhead:pal> find . -name '*.[1-9]' -exec grep '^\\f.\.' {} \; -print
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_buffer.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_config.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_context.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_gabn.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_gai_strerror.3
\fR.PP
./dns/bind/lib/lwres/man/lwres_getaddrinfo.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_gethostent.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_getipnode.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_getnameinfo.3
\fR.PP
./dns/bind/lib/lwres/man/lwres_getrrsetbyname.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_gnba.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_hstrerror.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_inetntop.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_noop.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_packet.3
\fR.SH "DESCRIPTION"
./dns/bind/lib/lwres/man/lwres_resutil.3
Other problems would be found with -

panhead:pal> find . -name '*.[1-9]' -exec grep '^\\f.(..\.' {} \; -print
There were none of those.



regards,
-pam

---------------------------------------------------------------------------
The Country Dweller
---------------------------------------------------------------------------


-----Original Message-----
From: Richard Binder Tru64 UNIX Publications [mailto:binder at zk3.dec.com]
Sent: Monday, April 22, 2002 4:33 PM
To: Peter Derr
Cc: mcmullen at zk3.dec.com; Betty Steinfeld; Pam Lassen
Subject: Re: lwres problem manpages


Peter,


  If you're sure the manpage coding is in error we can make the change and
  forward it back to the authors, but I notice that these manpages appear to
  have been generated by some tool from SGML source.

I'm sure.  It really doesn't matter how they were generated, they are still
wrong and should be fixed.  Here is a quotation from _UNIX Text Processing,_
by Dale Dougherty and Tim O'Reilly:

================

                        * The Markup Language *

  The nroff and troff markup commands (often called requests) typically
consist of one or two lowercase letters and stand on their own line,
following a period or apostrophe in column one...


  There are also requests that can be embedded anywhere in the text.  These
requests are commonly called escape sequences.  Escape sequences usually
begin with a backslash(\).


================

Here's the boring explanation, in case you'd like to understand exactly
what's happening and why.

The .SH sequence is a macro, defined by the man macro package and consisting
of requests.  Macros are coded the same as dot-command requests; i.e., with
the dot in column one.  In your files, there is an escape-sequence request,
\fR, before the dot.  It is merely coincidence that nroff processes the \fR
request (specifying a return to the roman font), removes it from
consideration, and then rescans the line to look for macros; it is not
required to behave in this fashion and is actually working contrary to the
spec by so doing.  And the fact that it does so has caused problems in other
pages, such as one that included a construct like this:

\f4.cf_primary\f0 file

What happened in this case is that nroff grabbed the \f4 and interpreted it,
then tripped over what came next because .cf is a valid request to copy an
existing file directly to the output.  There wasn't a file named _primary,
so nroff erred.  The files in question were part of the manpage set for the
Austin group's NonStop product, and their nroff works properly by not
considering that the dot has been moved to column one.

I put specific intelligence into refht to prevent the "Austin" error, and in
your pages it has caught the "opposite" error by ignoring a misplaced
intentional request instead of interpreting something that looks like a
request but isn't.

Your pages really do need to be fixed, if not by you then by the people who
provided them to you.

=dick

--
+---------------------------------------------------------------------+
|  Quaeuis hic quisquiliae notiones meae; noli dominum meum culpare.  |
|         N.a Tel.: Officina 603-884-6211, Facs. 603-884-2257         |
+---------------------------------------------------------------------+






More information about the bind-workers mailing list