Tweaking the documentation

1 files changed, 34 insertions, 36 deletions

diff --git a/doc/define.n b/doc/define.n
index d68e463..b489e5f 100644
--- a/doc/define.n
+++ b/doc/define.n
@@ -82,17 +82,14 @@ by a superclass; subclass exports override superclass visibility, and may in
 turn be overridden by instances.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether
 method call to instances of the class may be called and what the method's
 results are. Each \fImethodName\fR names a single filtering method (which may
 be exposed or not exposed); it is not an error for a non-existent method to be
 named since they may be defined by subclasses.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -133,15 +130,12 @@ below), this command creates private procedure-like methods.
 .RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of additional classes that are to be mixed into
 all the instances of the class being defined. Each \fIclassName\fR argument
 names a single class that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBprivate \fIcmd arg...\fR
 .TP
@@ -151,6 +145,15 @@ By default, this slot works by replacement.
 This evaluates the \fIscript\fR (or the list of command and arguments given by
 \fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
 current class will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting
+\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost
+definition context is just a private definition context. All other definition
+commands have no difference in behavior when used in a private definition
+context.
+.RE
 .VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
@@ -183,21 +186,23 @@ operates identically to
 If no arguments at all are used, this gives the name of the class currently
 being configured.
 .VE TIP470
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), the definitions on the class object will also be made in a private
+definition context.
+.VE TIP500
 .RE
 .TP
 \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 allows the alteration of the superclasses of the class being defined.
 Each \fIclassName\fR argument names one class that is to be a superclass of
 the defined class. Note that objects must not be changed from being classes to
 being non-classes or vice-versa, that an empty parent class is equivalent to
 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
 \fBoo::class\fR may not be modified.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBunexport\fI name \fR?\fIname ...\fR?
 .
@@ -209,7 +214,7 @@ actually defined by a superclass; subclass unexports override superclass
 visibility, and may be overridden by instance unexports.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made
 available in the methods, constructor and destructor declared by the class
@@ -234,7 +239,6 @@ namespace has a unique prefix that makes accidental use from other classes
 extremely unlikely.
 .VE TIP500
 .RE
-.VE
 .SS "CONFIGURING OBJECTS"
 .PP
 The following commands are supported in the \fIdefScript\fR for
@@ -261,18 +265,15 @@ being defined. Note that the methods themselves may be actually defined by a
 class or superclass; object exports override class visibility.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether a
 method call to the object may be called and what the method's results are.
 Each \fImethodName\fR names a single filtering method (which may be exposed or
 not exposed); it is not an error for a non-existent method to be named. Note
 that the actual list of filters also depends on the filters set upon any
 classes that the object is an instance of.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -308,24 +309,28 @@ below), this command creates private procedure-like methods.
 .RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates a per-object list of additional classes that are to be
 mixed into the object. Each argument, \fIclassName\fR, names a single class
 that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBprivate \fIcmd arg...\fR
 .TP
 \fBprivate \fIscript\fR
-.
 .VS TIP500
 This evaluates the \fIscript\fR (or the list of command and arguments given by
 \fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
 current object will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside
+\fBprivate\fR has no cumulative effect; the innermost definition context is
+just a private definition context. All other definition commands have no
+difference in behavior when used in a private definition context.
+.RE
 .VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
@@ -337,7 +342,6 @@ that the object is an instance of. Does not change the export status of the
 method; if it was exported before, it will be afterwards.
 .TP
 \fBself \fR
-.
 .VS TIP470
 This gives the name of the object currently being configured.
 .VE TIP470
@@ -351,7 +355,7 @@ object being defined. Note that the methods themselves may be actually defined
 by a class; instance unexports override class visibility.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made available in the methods declared by the
 object being defined.  Each variable name must not have any namespace
@@ -394,20 +398,17 @@ object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 of values (class names, variable names, etc.) that comprises the contents of
 the slot. The class defines three operations (as methods) that may be done on
 the slot:
-.VE
 .TP
 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
-.VS
+.
 This appends the given \fImember\fR elements to the slot definition.
-.VE
 .TP
 \fIslot\fR \fB\-clear\fR
-.VS
+.
 This sets the slot definition to the empty list.
-.VE
 .TP
 \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
-.VS
+.
 This replaces the slot definition with the given \fImember\fR elements.
 .PP
 A consequence of this is that any use of a slot's default operation where the
@@ -420,17 +421,15 @@ which is forwarded to the default operation of the slot (thus, for the class
 slot, this is forwarded to
 .QW "\fBmy \-append\fR" ),
 and these methods which provide the implementation interface:
-.VE
 .TP
 \fIslot\fR \fBGet\fR
-.VS
+.
 Returns a list that is the current contents of the slot. This method must
 always be called from a stack frame created by a call to \fBoo::define\fR or
 \fBoo::objdefine\fR.
-.VE
 .TP
 \fIslot\fR \fBSet \fIelementList\fR
-.VS
+.
 Sets the contents of the slot to the list \fIelementList\fR and returns the
 empty string. This method must always be called from a stack frame created by
 a call to \fBoo::define\fR or \fBoo::objdefine\fR.
@@ -441,7 +440,6 @@ an unknown method handler to tie all these pieces together, and they hide
 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
 \fIrecommended\fR that any user changes to the slot mechanism be restricted to
 defining new operations whose names start with a hyphen.
-.VE
 .SH EXAMPLES
 This example demonstrates how to use both forms of the \fBoo::define\fR and
 \fBoo::objdefine\fR commands (they work in the same way), as well as