docs/118332: man page for top does not describe STATE column wait events

[Andrew Hammond]

The following reply was made to PR docs/118332; it has been noted by GNATS.

From: "Andrew Hammond" <andrew.george.hammond at gmail.com>
To: "Giorgos Keramidas" <keramida at freebsd.org>
Cc: freebsd-gnats-submit at 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 <keramida at freebsd.org> wrote:
 
 > On 2007-11-29 18:27, Andrew Hammond <andrew.george.hammond at 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
 Content-Type: text/html; charset=ISO-8859-1
 Content-Transfer-Encoding: 7bit
 Content-Disposition: inline
 
 On Feb 10, 2008 11:51 AM, Giorgos Keramidas <<a href="mailto:keramida at freebsd.org">keramida at freebsd.org</a>> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
 On 2007-11-29 18:27, Andrew Hammond <<a href="mailto:andrew.george.hammond at gmail.com">andrew.george.hammond at gmail.com</a>> wrote:<br>> >Number:         118332<br>> >Category:       docs<br><div class="Ih2E3d">
 > >Synopsis:       man page for top does not describe STATE column wait events<br><br></div>> The manual page for top does not describe or provide a pointer to<br>> descriptions of STATEs such as swread, nanslp, select, piperd, etc.<br>
 <br>The manpage describes `STATE' with the somewhat cryptic text:<br><br>    STATE is the current state (one of "START", "RUN" (shown as "CPUn"<br>    on SMP systems), "SLEEP", "STOP", "ZOMB", "WAIT", "LOCK" or the<br>
     event on which the process waits),<br><br>Any lowercase string is the name of a kernel-related event, and it would<br>be a very daunting task to list them *all* in the manpage.  Do you think<br>we can phrase this particular part of the manpage in a way that is more<br>
 helpful?  If yes, we are open to suggestions.</blockquote><div> </div></div>How about continuing on with something like the following.<br><br>"Here are some common events which can cause a process to wait and what they mean."<br>
 <br>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.<br><br>A<br>
 
 ------=_Part_1733_29124706.1202675882451--