From owner-freebsd-doc Wed May 22 2:10: 8 2002 Delivered-To: freebsd-doc@hub.freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 9D67537B416 for ; Wed, 22 May 2002 02:10:03 -0700 (PDT) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.6/8.11.6) id g4M9A3I77743; Wed, 22 May 2002 02:10:03 -0700 (PDT) (envelope-from gnats) Date: Wed, 22 May 2002 02:10:03 -0700 (PDT) Message-Id: <200205220910.g4M9A3I77743@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org Cc: From: Dmitry Morozovsky Subject: Re: docs/38289: Update to ata(4) manpage (broken ata tags for now) Reply-To: Dmitry Morozovsky Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org The following reply was made to PR docs/38289; it has been noted by GNATS. From: Dmitry Morozovsky To: Giorgos Keramidas Cc: bug-followup@FreeBSD.ORG Subject: Re: docs/38289: Update to ata(4) manpage (broken ata tags for now) Date: Wed, 22 May 2002 13:02:27 +0400 (MSD) On Tue, 21 May 2002, Giorgos Keramidas wrote: [snip] GK> > +.Pp GK> > +XXX THIS FEATURE IS CURRENTLY BROKEN -- Do not try to enable it! XXX GK> > .El GK> > .Sh DESCRIPTION GK> > This driver provides access to disk drives, ATAPI CD-ROM and DVD drives, GK> GK> I don't think "XXX" is a nice thing to have in running text. I tend GK> to view the manpages as text that can be part of a typeset document, GK> printed in PostScript form by a local printer. Moreover, the manpages GK> should not document brokenness that can be fixed, for fear that they GK> will continue to document brokenness long after the bug has been GK> fixed, if the author of the code doesn't know that the manpage states GK> the code is broken. A comment in LINT should be enough to let the GK> users know that this particular feature might be the source of GK> problems, when they're editing their kernel configuration and enabling GK> the option. Well, then I tend to agree ;-) Maybe just comment this section out from the manpage? Adding comment to LINT is not a good idea for me as long as ATA tags are no longer kernel compile-time option. Anyway, I think it should be documented some way. Sincerely, D.Marck [DM5020, DM268-RIPE, DM3-RIPN] ------------------------------------------------------------------------ *** Dmitry Morozovsky --- D.Marck --- Wild Woozle --- marck@rinet.ru *** ------------------------------------------------------------------------ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message