docs/134074: [patch] locking.9 man page slight enhancements

[Haven Hash]

>Number:         134074
>Category:       docs
>Synopsis:       [patch] locking.9 man page slight enhancements
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Apr 29 00:20:03 UTC 2009
>Closed-Date:
>Last-Modified:
>Originator:     Haven Hash
>Release:        SVN rev 191642
>Organization:
>Environment:
N/A 
>Description:
While reading the locking (9) man page. I found a few slight things that could be improved so I did an svn checkout and made a few adjustments. 

1. The order of Sleep/wakeup and Giant in the Description list is reversed from the order in which they are presented in the document. With no logic other than the Description list seemed to be a better ordering I reversed their order in the document.

2. The link to the witness manual page at the bottom is in all capital letters and signifies chapter 9 of the manual. The witness manual page it seems is in chapter 4 of the manual and an all caps reference causes links on the www man page viewer to not find it (witness (4) is appropriately referenced earlier in the document).

3. Some slight grammatical additions were made to the explanations in the Usage Table. 

>How-To-Repeat:
man 9 locking on a FreeBSD system >= 7.0 
>Fix:
Apply attached patch if deemed appropriate.

Patch attached with submission follows:

Index: share/man/man9/locking.9
===================================================================
--- share/man/man9/locking.9	(revision 191639)
+++ share/man/man9/locking.9	(working copy)
@@ -220,28 +220,6 @@
 When a thread waits on a condition, the mutex
 is atomically released before the thread is blocked, then reacquired
 before the function call returns.
-.Ss Giant
-Giant is a special instance of a sleep lock.
-It has several special characteristics.
-.Bl -enum
-.It
-It is recursive.
-.It
-Drivers can request that Giant be locked around them, but this is
-going away.
-.It
-You can sleep while it has recursed, but other recursive locks cannot.
-.It
-Giant must be locked first before other locks.
-.It
-There are places in the kernel that drop Giant and pick it back up
-again.
-Sleep locks will do this before sleeping.
-Parts of the Network or VM code may do this as well, depending on the
-setting of a sysctl.
-This means that you cannot count on Giant keeping other code from
-running if your code sleeps, even if you want it to.
-.El
 .Ss Sleep/wakeup
 The functions
 .Fn tsleep ,
@@ -298,6 +276,28 @@
 .Va Giant
 mutex before the function returns.
 .Pp
+.Ss Giant
+Giant is a special instance of a sleep lock.
+It has several special characteristics.
+.Bl -enum
+.It
+It is recursive.
+.It
+Drivers can request that Giant be locked around them, but this is
+going away.
+.It
+You can sleep while it has recursed, but other recursive locks cannot.
+.It
+Giant must be locked first before other locks.
+.It
+There are places in the kernel that drop Giant and pick it back up
+again.
+Sleep locks will do this before sleeping.
+Parts of the Network or VM code may do this as well, depending on the
+setting of a sysctl.
+This means that you cannot count on Giant keeping other code from
+running if your code sleeps, even if you want it to.
+.El
 .Ss lockmanager locks
 Largely deprecated.
 See the
@@ -325,11 +325,11 @@
 Lock order is important.
 .Pp
 .Em *2
-readers can recurse though writers can not.
+Readers can recurse though writers can not.
 Lock order is important.
 .Pp
 .Em *3
-There are calls atomically release this primitive when going to sleep
+There are calls to atomically release this primitive when going to sleep
 and reacquire it on wakeup (e.g.
 .Fn mtx_sleep ,
 .Fn rw_sleep
@@ -340,7 +340,7 @@
 .Em *4
 Though one can sleep holding an sx lock, one can also use
 .Fn sx_sleep
-which atomically release this primitive when going to sleep and
+which will atomically release this primitive when going to sleep and
 reacquire it on wakeup.
 .Ss Context mode table.
 The next table shows what can be used in different contexts.
@@ -363,7 +363,7 @@
 .Xr sleep 9 ,
 .Xr sx 9 ,
 .Xr LOCK_PROFILING 9 ,
-.Xr WITNESS 9
+.Xr witness 4
 .Sh HISTORY
 These
 functions appeared in


>Release-Note:
>Audit-Trail:
>Unformatted: