From owner-freebsd-doc@FreeBSD.ORG Sun Feb 10 21:10:03 2008 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 52C4316A417 for ; Sun, 10 Feb 2008 21:10:03 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 5DB2C13C459 for ; Sun, 10 Feb 2008 21:10:03 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.2/8.14.2) with ESMTP id m1ALA3C2044050 for ; Sun, 10 Feb 2008 21:10:03 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.2/8.14.1/Submit) id m1ALA3hg044049; Sun, 10 Feb 2008 21:10:03 GMT (envelope-from gnats) Date: Sun, 10 Feb 2008 21:10:03 GMT Message-Id: <200802102110.m1ALA3hg044049@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: "Andrew Hammond" Cc: Subject: Re: docs/118332: man page for top does not describe STATE column wait events X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Andrew Hammond List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 10 Feb 2008 21:10:03 -0000 The following reply was made to PR docs/118332; it has been noted by GNATS. From: "Andrew Hammond" To: "Giorgos Keramidas" Cc: freebsd-gnats-submit@freebsd.org Subject: Re: docs/118332: man page for top does not describe STATE column wait events Date: Sun, 10 Feb 2008 12:38:02 -0800 ------=_Part_1733_29124706.1202675882451 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline On Feb 10, 2008 11:51 AM, Giorgos Keramidas wrote: > On 2007-11-29 18:27, Andrew Hammond > wrote: > > >Number: 118332 > > >Category: docs > > >Synopsis: man page for top does not describe STATE column wait > events > > > The manual page for top does not describe or provide a pointer to > > descriptions of STATEs such as swread, nanslp, select, piperd, etc. > > The manpage describes `STATE' with the somewhat cryptic text: > > STATE is the current state (one of "START", "RUN" (shown as "CPUn" > on SMP systems), "SLEEP", "STOP", "ZOMB", "WAIT", "LOCK" or the > event on which the process waits), > > Any lowercase string is the name of a kernel-related event, and it would > be a very daunting task to list them *all* in the manpage. Do you think > we can phrase this particular part of the manpage in a way that is more > helpful? If yes, we are open to suggestions. How about continuing on with something like the following. "Here are some common events which can cause a process to wait and what they mean." Then list the ones that a user is most likely to see while dealing with a performance problem along with brief descriptions and finally provide a reference to the canonical documentation. A ------=_Part_1733_29124706.1202675882451 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline On Feb 10, 2008 11:51 AM, Giorgos Keramidas <keramida@freebsd.org> wrote:
On 2007-11-29 18:27, Andrew Hammond <andrew.george.hammond@gmail.com> wrote:
> >Number:         118332
> >Category:       docs
> >Synopsis:       man page for top does not describe STATE column wait events

> The manual page for top does not describe or provide a pointer to
> descriptions of STATEs such as swread, nanslp, select, piperd, etc.

The manpage describes `STATE' with the somewhat cryptic text:

   STATE is the current state (one of "START", "RUN" (shown as "CPUn"
   on SMP systems), "SLEEP", "STOP", "ZOMB", "WAIT", "LOCK" or the
   event on which the process waits),

Any lowercase string is the name of a kernel-related event, and it would
be a very daunting task to list them *all* in the manpage.  Do you think
we can phrase this particular part of the manpage in a way that is more
helpful?  If yes, we are open to suggestions.
 
How about continuing on with something like the following.

"Here are some common events which can cause a process to wait and what they mean."

Then list the ones that a user is most likely to see while dealing with a performance problem along with brief descriptions and finally provide a reference to the canonical documentation.

A
------=_Part_1733_29124706.1202675882451--