From b156912c4608d637348aeda34503e67a01a05ae1 Mon Sep 17 00:00:00 2001
From: PatR <rankin@nethack.org>
Date: Thu, 18 Jan 2024 23:58:53 -0800
Subject: [PATCH] Guidebook tweaks for "containers" sub-section

---
 doc/Guidebook.mn  | 23 ++++++++++++++++++++++-
 doc/Guidebook.tex | 26 +++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn
index 373df89d9..a30f2f2f2 100644
--- a/doc/Guidebook.mn
+++ b/doc/Guidebook.mn
@@ -46,7 +46,7 @@
 .ds f0 \*(vr
 .ds f1 \" empty
 .\"DO NOT REMOVE NH_DATESUB .ds f2 DATE(%B %-d, %Y)
-.ds f2 January 02, 2024
+.ds f2 January 18, 2024
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -3074,6 +3074,27 @@ Some chests are trapped, causing nasty things to happen when you
 unlock or open them.
 You can check for and try to deactivate traps
 with the \(lq#untrap\(rq extended command.
+.pg
+When the contents of a container are known, that container will be
+described as something like \(lqa sack containing 3 items\(rq.
+In this example, the 3 refers to number of \fIstacks\fP of compatible
+items, not to the total number of individual items.
+So a sack holding 2 blue potions, 7 arrows, and 350 gold pieces would be
+described as having 3 items rather than 10 or 359.
+.pg
+If a chest or large box is described as \(lqbroken\(rq, that means that it
+can't be locked rather than that it no longer functions as a container.
+.pg
+The \fIapply\fP and \fIloot\fP commands allow you to take out and/or
+put in an arbitrary number of items in a single operation.
+If you want to take everything out of a container, you can use the
+\(lq#tip\(rq command to pour the contents onto the floor.
+This may be your only way to get things out if your hands are stuck
+to a cursed two-handed weapon.
+When your hands aren't stuck, you have another option of pouring the
+conteints into another container.
+(As of this writing, the other container must be carried rather than on
+the floor.)
 .hn 2
 Amulets (\(oq"\(cq)
 .pg
diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex
index a8f0a9a84..516739585 100644
--- a/doc/Guidebook.tex
+++ b/doc/Guidebook.tex
@@ -46,7 +46,7 @@
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7.0 by Mike Stephenson and others)}
 %DO NOT REMOVE NH_DATESUB \date{DATE(%B %-d, %Y)}
-\date{January 02, 2024}
+\date{January 18, 2024}
 
 \maketitle
 
@@ -3363,6 +3363,30 @@ Some chests are trapped, causing nasty things to happen when you
 unlock or open them.  You can check for and try to deactivate traps
 with the ``{\tt \#untrap}'' extended command.
 
+%.pg
+When the contents of a container are known, that container will be
+described as something like ``a sack containing 3 items''.
+In this example, the 3 refers to number of {\it stacks\/} of compatible
+items, not to the total number of individual items.
+So a sack holding 2 blue potions, 7 arrows, and 350 gold pieces would be
+described as having 3 items rather than 10 or 359.
+
+%.pg
+If a chest or large box is described as ``broken'', that means that it
+can't be locked rather than that it no longer functions as a container.
+
+%.pg
+The {\it apply\/} and {\it loot\/} commands allow you to take out and/or
+put in an arbitrary number of items in a single operation.
+If you want to take everything out of a container, you can use the
+``\{\tt \#tip}'' command to pour the contents onto the floor.
+This may be your only way to get things out if your hands are stuck
+to a cursed two-handed weapon.
+When your hands aren't stuck, you have another option of pouring the
+conteints into another container.
+(As of this writing, the other container must be carried rather than on
+the floor.)
+
 %.hn 2
 \subsection*{Amulets (`{\tt "}')}