Index: doc/forward.man.inc
===================================================================
diff -u -re87eb2ded5035dc51ba89af4f68a0925db664024 -r8c16e18f186d305671e9543bf3c5d23fa65dc684
--- doc/forward.man.inc	(.../forward.man.inc)	(revision e87eb2ded5035dc51ba89af4f68a0925db664024)
+++ doc/forward.man.inc	(.../forward.man.inc)	(revision 8c16e18f186d305671e9543bf3c5d23fa65dc684)
@@ -2,46 +2,56 @@
 
 [keywords "value checker"]
 [keywords "forward method"]
+[keywords "debugging level"]
 
-[call [arg [vset CMD]] [opt "public | protected | private"] [const [vset SCOPE]] [method forward] [arg methodName] [opt [option "-default [arg value]"]] [opt [option "-methodprefix [arg prefixName]"]] [opt [option "-frame object"]] [opt [option "-onerror [arg cmdName]"]] [opt [option "-returns [arg valueChecker]"]] [opt [option "-verbose"]] [arg arg] [opt "[arg arg] ..."]]
+[call [arg [vset CMD]] [opt "public | protected | private"] [const [vset SCOPE]] [method forward] [arg methodName] [opt [option "-methodprefix [arg prefixName]"]] [opt [option "-frame object"]] [opt [option "-returns [arg valueChecker]"]] [opt [option "-verbose"]] [arg target] [opt "[arg arg] ..."]]
 
 Define a [term "forward method"] for the given [vset SCOPE]. The
 definition of a [term "forward method"] registers a predefined, but
 changeable list of forwarder arguments under the (forwarder) name [arg methodName]. Upon
-calling the [term "forward method"], the forwarder arguments are
-evaluated as a Tcl command call. That is, the first
-argument [arg arg] is interpreted as a Tcl command (e.g., a Tcl [cmd proc] or
-an object) and the remainder of the forwarder arguments as arguments
-passed into this command. The actual method arguments to the
-invocation of the [term "forward method"] itself are appended to the
-list of forwarder arguments.
+calling the [term "forward method"], the forwarder
+arguments are evaluated as a Tcl command call. That is, [arg target]
+is interpreted as a Tcl command (e.g., a Tcl [cmd proc] or an object)
+and the remainder of the forwarder arguments [arg arg] as arguments passed into
+this command. The actual method arguments to the invocation of the
+[term "forward method"] itself are appended to the list of forwarder
+arguments.
 
 [para] 
 
 As for a regular [method "[vset SCOPE] method"], [option "-returns"] allows
 for setting a [term "value checker"] on the values returned by the
-resulting Tcl command call. When passing [const object] to [option "-frame"], the
+resulting Tcl command call. When passing to [option "-frame"] [const object], the
 resulting Tcl command is evaluated in the context of the object
-receiving the [term "forward method"] call. [option "-onerror"] sets a
-Tcl command [arg cmdName] which is called as the handler for errors
-caught during evaluating the resulting Tcl command.
+receiving the [term "forward method"] call. This way, variable names
+used in the resulting execution of a command become resolved as
+object variables.
 
 [para]
 
 The list of forwarder arguments [arg arg] can contain as its elements
-a mix of literal values and placeholder values. Placeholders are
-prefixed with a percent symbol (%) and substituted for concrete values
-upon calling the [term "forward method"]. These placeholders allow for
-constructing and for manipulating the list of forwarder arguments on
-the fly:
+a mix of literal values and placeholders. Placeholders are prefixed
+with a percent symbol (%) and substituted for concrete values upon
+calling the [term "forward method"]. These placeholders allow for
+constructing and for manipulating the arguments to be passed into the
+resulting command call on the fly:
 
 [list_begin itemized]
 
 [item] [const %method] becomes substituted for the name of the [term "forward method"], i.e. [arg methodName].
 
 [item] [const %self] becomes substituted for the name of the object receiving the call of the [term "forward method"].
 
-[item] [const %1] becomes substituted for the first method argument passed to the call of [term "forward method"].
+[item] [const %1] becomes substituted for the first method argument passed to the call of [term "forward method"]. This requires, in turn, that [emph "at least"] one argument is passed along with the method call.
+[para]
+Alternatively, [const %1] accepts an optional argument [arg defaults]: {[const %1] [arg defaults]}. 
+[arg defaults] must be a valid Tcl list of two elements. For the first
+element, [const %1] is substituted when there is no first method
+argument which can be consumed by [const %1]. The second element is
+inserted upon availability of a first method argument with the
+consumed argument being appended right after the second list
+element. This placeholder is typically used to defined a pair of
+getter/setter methods.
 
 [item] {[const %@][arg index] [arg value]} becomes substituted for the
 specified [arg value] at position [arg index] in the
@@ -54,15 +64,14 @@
 used in ascending order.
 [para]
 Note that [arg value] can be a literal or any of the placeholders
-(e.g., [const %method], [const %self]). An exception are position
-prefixes themselves which are evaluated according to the [const %][arg cmdName]-rule 
-(see below).
+(e.g., [const %method], [const %self]). Position prefixes are
+exempted, they are evaluated as [const %][arg cmdName]-placeholders in this context.
 
 [item] {[const %argclindex] [arg list]} becomes substituted for the
 [emph n]th element of the provided [arg list] , with [emph n]
 corresponding to the number of method arguments passed to the [term "forward method"] call.
 
-[item] [const %%] is substituted for a single literal percent (%) symbol.
+[item] [const %%] is substituted for a single, literal percent symbol (%).
 
 [item] [const %][arg cmdName] is substituted for the value returned
 from executing the Tcl command [arg cmdName]. To pass arguments to [arg cmdName], the placeholder should be wrapped into a Tcl [cmd list]: {[const %][arg cmdName] [opt "[arg arg] ..."]}.
@@ -73,29 +82,18 @@
 
 [list_end]
 
-[para]
-[comment {
-# @parameter	-default	Is used for default method names (only
-# 				in connection with %1)
-# @parameter 	-methodprefix 	Prepends the specified prefix to the second
-# 				argument of the invocation.
-}]
+[para] 
 
-[para]
-To inspect and to debug the substitutions performed by the above
-placeholder values, setting the [term "switch"] [option "-verbose"]
-will have the resulting Tcl command (i.e., after substitution) printed to
-[const stdout] upon calling the [term "forward method"].
+To disambiguate the names of subcommands or methods, which potentially
+become called by a [term "forward method"], a prefix can be set using
+[option "-methodprefix"]. This prefix is prepended automatically to
+the argument following [arg target] (i.e., a second argument), if
+present. If missing, [option "-methodprefix"] has no effect on the
+[term "forward method"] call.
 
-[comment {#
-# @parameter 	method 		The name of the delegating or forwarder method
-# @parameter 	-objframe	Causes the target to be evaluated in
-# 				the scope of the object.
-# @parameter 	-onerror	Register an error handler
-# @parameter 	-returns	Provide an out parameter
-# 				specification, used to check the
-# 				return value of the forward dispatch.
-# @parameter	-verbose 	Print the substituted command string to stderr
-# 				before performing the command
-# 				execution. For debugging purposes.
-}]
+[para]
+To inspect and to debug the conversions performed by the above
+placeholders, setting the [term "switch"] [option "-verbose"]
+will have the command list to be executed (i.e., after substitution)
+printed using [cmd ::nsf::log] ([term "debugging level"]: [const notice]) upon
+calling the [term "forward method"].