Index: library/lib/nxdoc-core.tcl
===================================================================
diff -u -r6ef6700b363d0fcc6a4ccf78a9b51e27f5598936 -r187fbd20a453ae9d73e9b48f88b8d6a8c79685c2
--- library/lib/nxdoc-core.tcl	(.../nxdoc-core.tcl)	(revision 6ef6700b363d0fcc6a4ccf78a9b51e27f5598936)
+++ library/lib/nxdoc-core.tcl	(.../nxdoc-core.tcl)	(revision 187fbd20a453ae9d73e9b48f88b8d6a8c79685c2)
@@ -1,95 +1,50 @@
 # @package nx::doc
 # 
-# Study for documentation classes for the Next Scripting Langauge
+# The NXDoc infrastructure is built upon a representational model of
+# NSF/NX code units; e.g., packages, commands, objects, and
+# classes. This package declares the essential entities for
+# representing NSF/NX programs, in terms of a special-purpose NSF/NX
+# program. In addition, some utilities for implementing front- and
+# backends for NXDoc are provided.
 # 
-# Compared to the "old" @ docmentation effort, this is a rather
-# light-weight structure based on xotcl 2 (next) language
-# features. The documentation classes build an (extensible) object
-# structure which is used as a basis for some renderers. In general,
-# the classes are defined in a way they can be used for
-#
-#  a) building documentation outside the source code artefacts, or
-#
-#  b) inside code artefacts (value added method definition commands
-#     providing extra arguments for the documentation). The
-#     documentation commands could reuse there names/arguments
-#     etc. directly from the method definition by issuing these
-#     commands inside the method definition methods.
-#
-# One could provide lint-like features to signal, whether the
-# documentation is in sync with actually defined methods (when these
-# are available).
-#
+# @author stefan.sobernig@wu.ac.at
 # @require nx
-# @version 0.1
+# @version 1.0
+# @namespace ::nx::doc
  
 package provide nx::doc 1.0
 namespace eval ::nx::doc {}
 
 package require nx
-package require nx::pp
 
 namespace eval ::nx::doc {
   namespace import -force ::nx::*
   
   # @command ::nx::doc::@
   #
-  # The helper proc "@" is a conveniant way for creating new
-  # documentation objects with less syntactic overhead.
+  # The helper proc "@" is a conveniant mean for creating new
+  # documentation objects with minimal syntactic overhead.
   #
-  # @param class Request an instance of a particular entity class (e.g., ...)
-  # @param name What is the entity name (e.g., nx::doc for a package)
-  # @param args A vector of arbitrary arguments, provided to the
+  # @parameter class Request an instance of a particular entity class (e.g., ...)
+  # @parameter name What is the entity name (e.g., nx::doc for a package)
+  # @parameter args A vector of arbitrary arguments, provided to the
   # entity when being constructed
   # @return The identifier of the newly created entity object
   
-  # @subcommand ::nx::doc::@#foo
-  #
-  # This is the first subcommand foo of "@"
-  # {{{
-  # set do 1;
-  # }}}
-  #
-  # @param -param1 do it
-  # @param param2 do it a second time
-  # @return Gives you a "foo" object
-
-  # @subcommand ::nx::doc::@#bar
-  #
-  # This is the second subcommand bar of "@"
-  #
-  # @param -param1 do it
-  # @param param2 do it a second time
-  # @return Gives you a "bar" object
-
   proc @ {class name args} {$class new -name $name {*}$args}
  
 
   # @command ::nx::doc::sorted
   #
-  # This proc is used to sort instances by values of a specified
-  # attribute. {{{ set 
-  # code 1; puts stderr $code; puts stderr [info script]; set l \{x\}
-  # }}} Und nun gehen wir in eine zweite Zeile ... und fügen einen Link ein (e.g., {{@object ::nx::doc::@object}})
+  # This utility proc is used to sort entities by values of a
+  # specified attribute.
   #
-  # ... um nach einem Zeilenbruch weiterzumachen
-  # {{{
-  #	\# Some comment
-  #	set instances [list [Object new] [Object new]]
-  #	::nx::doc::sorted $instances; set l {{{x}}}; # Some comment
-  # {{{ }}} 
-  #	set instances [list [Object new] [Object new]]
-  #	::nx::doc::sorted $instances
-  # }}}
-  # Here it goes wider ...
-    # {{{
-  #	set instances [list [Object new] [Object new]]
-  #	::nx::doc::sorted $instances
-  # }}}
-  #
-  # @param instances Points to a list of entity instances to sort e.g. {{@object ::nx::doc::@object}}
-  # @param sortedBy Indicates the attribte name whose values the sorting will be based on
-  # @return A list of sorted documentation entity instances {{{instances of @object}}}
+  # @parameter instances 	Points to a list of entity instances
+  # 				to sort e.g. <<@class ::nx::doc::@object>>
+  # @parameter sortedBy 	Indicates the attribte name whose
+  # 				values the sorting will be based on
+  # @return 			A list of sorted documentation entity
+  # 				instances <<@class ::nx::doc::@object>>
   proc sorted {instances sortedBy} {
     set order [list]
     foreach v $instances {lappend order [list $v [$v eval [list set :$sortedBy]]]}
@@ -109,15 +64,15 @@
   }
 
 
-  proc sort_by_value {d} {
+  proc sortByValue {d} {
     set haystack [list]
     dict for {key value} $d {
       lappend haystack [list $key $value]
     }
     return [dict create {*}[concat {*}[lsort -integer -index 1 -decreasing $haystack]]]
   }
     
-  proc find_asset_path {{subdir library/lib/nxdoc-assets}} {
+  proc findAssetPath {{subdir library/lib/nxdoc-assets}} {
       # This helper tries to identify the file system path of the
       # asset ressources.
       #
@@ -131,7 +86,7 @@
     }
 
 
-  Class create MixinLayer {
+  Class create MixinLayer -superclass Class {
     :property {prefix ""}
     :public method init {} {
       set :active_mixins [dict create]
@@ -187,8 +142,7 @@
     namespace eval ::nx::doc::entities {}
 
     :public class method normalise {tagpath names} {
-      # puts stderr "tagpath $tagpath names $names"
-      # 1) verify balancedness of 
+      # 1) verify balancedness of path spec elements
       if {[llength $tagpath] != [llength $names]} {
 	return [list 1 "Imbalanced tag line spec: '$tagpath' vs. '$names'"]
       }
@@ -231,7 +185,7 @@
 	  #
 	  # TODO interp-aliasing objects under different command names
 	  # is currently not transparent to some ::nsf::* helpers,
-	  # such as ::nsf::object::exists. Should this be changed?
+	  # such as ::nsf::object::exists. Do we need to tackle this?
 	  #
 	  if {$cmd ne ""} {
 	    set cmd [namespace origin $cmd]
@@ -253,7 +207,6 @@
 	  if {[$entity info lookup methods -source application @$axis] eq ""} {
 	    return [list 1 "The tag '$axis' is not supported for the entity type '[namespace tail [$entity info class]]'"]
 	  }
-	  #puts stderr "$entity @$axis id $value"
 	  set entity [$entity @$axis id $value]
 	  set last_axis $axis
 	  set last_name $value
@@ -269,7 +222,7 @@
       return [list 0 [expr {$all?$entity_path:$entity}]]
     }
     
-    # @method id 
+    # @class.method {Tag id}
     #
     # A basic generator for the characteristic ideas, based on the
     # root_namespace, the tag label, and the fully qualified name of
@@ -322,12 +275,12 @@
       if {[::nsf::object::exists $id]} {
 	$id configure {*}$args
       } else {
-	:create $id {*}$args
+	set id [:create $id {*}$args]
       }
       return $id
     }
 
-    # @method get_unqualified_name
+    # @class.method {Tag get_unqualified_name}
     #
     # @param qualified_name The fully qualified name (i.e., including the root namespace)
     :public method get_unqualified_name {qualified_name} {
@@ -339,12 +292,47 @@
       #return [string trimleft [string map [list ${:tag} ""] [:get_unqualified_name $qualified_name]]  ":"]
       return [join [lrange [concat {*}[split [:get_unqualified_name $qualified_name] "::"]] 1 end] "::"]
     }
+
+    # / / / / / / / / / / / / / / / / / / / / / / / /
+    # Manage chains of responsible container entities
+    #
+    # TODO: We don't need the stack-like dispensing of containers,
+    # make it a simple one-element store
+
+    :public class property containers:0..*,object,type=::nx::doc::ContainerEntity {
+      set :incremental 1
+    }
+
+    :public method "containers empty" {} -returns boolean {
+      return [[current class] eval {expr {![info exists :containers] || ![llength ${:containers}]}}]
+    }
+
+    :public method "containers peek" {} {
+      if {![:containers empty]} {
+	return [lindex [[current class] containers] end]
+      }
+    }
+
+    :public method "containers push" {container:object,type=::nx::doc::ContainerEntity} {
+      set prev [:containers peek]
+      if {$prev ne ""} {
+	$container previous $prev 
+      }
+      [current class] containers add $container end
+    }
+
+    :public method "containers reset" {{v ""}} {
+      [current class] containers $v
+    }
+
   }
 
   Class create QualifierTag -superclass Tag {
     :method get_fully_qualified_name {name} {
       if {![string match "::*" $name]} {
-	error "You need to provide a fully-qualified (absolute) entity name for '$name'."
+	set container [:containers peek]
+	set ns [$container getAuthoritativeNS]
+	set name ${ns}::$name 
       }
       return $name
     }
@@ -355,12 +343,9 @@
       name
     } {
       if {[info exists partof_name]} {
-	#puts stderr "QUALIFIER=[join [list $partof_name $name] ::]"
-	#next [join [list $partof_name $name] ::]
 	next
       } else {
 	set n [:get_fully_qualified_name $name]
-#	puts stderr FINALNAME=$n
 	next $n
       }
     }
@@ -373,7 +358,6 @@
     } {
       set id_name $name
       if {[info exists partof]} {
-	#set name [join [list [$partof name] $name] ::]
 	set id_name ::[join [list [[$partof info class] get_tail_name $partof] $name] ::]
       } else {
 	set name [:get_fully_qualified_name $name]
@@ -400,7 +384,7 @@
     }
   }
   
-  # @object ::nx::doc::PartAttribute
+  # @class ::nx::doc::PartAttribute
   #
   # This special-purpose Attribute variant realises (1) a cumulative
   # value management and (2) support for distinguishing between
@@ -415,13 +399,20 @@
   # part_class is given, the values will be transformed accordingly
   # before being pushed into the internal storage.
 
-  ::nx::MetaSlot create PartAttribute -superclass ::nx::VariableSlot {
-
-    # @param part_class
+  nx::MetaSlot create PartAttribute -superclass ::nx::VariableSlot {
+    # @.parameter part_class
     # 
     # The property refers to a concrete subclass of Part which
     # describes the parts being managed by the property.
-    :property part_class:optional,class
+    :property part_class:optional,class {
+      :public method assign {domain prop value} {
+	set owningClass [[$domain info parent] info parent]
+	if {"::nx::doc::ContainerEntity" in [concat $owningClass [$owningClass info heritage]]} {
+	  $value class mixin add ::nx::doc::ContainerEntity::Containable
+	}
+	next
+      }
+    }
     :property scope
 
     :property {pretty_name {[string totitle [string trimleft [namespace tail [current]] @]]}}
@@ -506,48 +497,57 @@
     }
   }
 
-  Class create Entity {
+  #
+  # Sketch the entire hierarchy of documentation entities
+  # supported. Entity behaviour is defined further below
+  #
+
+  Class create Entity
+  Class create StructuredEntity -superclass Entity
+  Class create ContainerEntity -superclass StructuredEntity  
+  Class create PartEntity -superclass Entity
+
+  Tag create @glossary -superclass Entity
+  Tag create @project -superclass ContainerEntity
+  Tag create @package -superclass ContainerEntity
+  QualifierTag create @command -superclass StructuredEntity  
+  QualifierTag create @object -superclass StructuredEntity
+  QualifierTag create @class -superclass @object
+
+  PartTag create @method -superclass StructuredEntity
+  PartTag create @param -superclass PartEntity
+
+
+
+  Entity eval {
     #
     # Entity is the base class for the documentation classes
     #
 
-    # @param name
+    # @.parameter name
     #
     # gives you the name (i.e., the Nx object identifier) of the documented entity
     :property name:any,required
 
-    # every Entity must be created with a "@doc" value and can have
-    # an optional initcmd 
-    #:method objectparameter args {
-      #next [list [list @doc:optional __initcmd:initcmd,optional]]
-    #}
-
     :class property current_project:object,type=::nx::doc::@project,0..1
     :public forward current_project [current] %method
 
     :property partof:object,type=::nx::doc::StructuredEntity
     :property part_attribute:object,type=::nx::doc::PartAttribute
- 
+
+
+    :public method get_fqn_command_name {} {
+      return ${:name}
+    }
+
     #
     # TODO: the pdata/pinfo/validate combo only makes sense for
     # entities which reflect Tcl program structures -> refactor into a
     # dedicated PEntity class or the like
     #
-
-     :public method get_fqn_command_name {} {
-	return ${:name}
-      }
-
+    
     :property pdata
-    :public method validate {} {
-      if {[info exists :pdata] && \
-	      [:pinfo get -default complete status] ne "missing"} {
-	if {[[:origin] as_list] eq ""} {
-	  :pinfo propagate status mismatch
-	  :pinfo lappend validation "Provide a short, summarising description!"
-	}
-      }
-    }
+
     :public method "pinfo get" {{-default ?} args} {
       if {![info exists :pdata] || ![dict exists ${:pdata} {*}$args]} {
 	return $default;
@@ -618,7 +618,6 @@
       set :default 0
     }
 
-    # :property @properties -class ::nx::doc::PartAttribute
     :public method @property {props} {
       foreach prop $props {
 	:@$prop
@@ -627,24 +626,9 @@
 
     :property @use {
       :public method assign {domain prop value} {
-	# @command nx
-	#
-	# @use ::nsf::command
-	
-	# or
-
-	# class.method {X foo}
-	#
-	# @use {Class foo}
-	# @use object.method {Object foo}
-
 	lassign $value pathspec pathnames
 	if {$pathnames eq ""} {
 	  set pathnames $pathspec
-	  # puts stderr PATH=[$domain get_upward_path \
-	  # 				    -attribute {[:info class] tag}]
-	  # puts stderr "dict create {*}[$domain get_upward_path \
-	  # 				    -attribute {[:info class] tag}]"
 	  set pathspec [dict create {*}[$domain get_upward_path \
 					    -attribute {[:info class] tag}]]
 	  set pathspec [dict values $pathspec]
@@ -657,22 +641,19 @@
 	}
 	
 	lassign $res pathspec pathnames
-	#puts stderr "PATHSPEC $pathspec PATHNAMES $pathnames"	
 	lassign [::nx::doc::Tag find $pathspec $pathnames] err res
 	if {$err} {
 	  error "Generating an entity handle failed: $res"
 	}
-	# puts stderr "NEXT $domain $prop $res"
 	next [list $domain $prop $res]
       }
       
     }
 
     :public method origin {} {
       if {[info exists :@use]} {
-	# puts stderr ORIGIN(${:@use})=isobj-[::nsf::object::exists ${:@use}]
 	if {![::nsf::object::exists ${:@use}] || ![${:@use} info has type [:info class]]} {
-	  error "Referring to a non-existing doc entity or a doc entity of a different type."
+	  return -code error "Referring to a non-existing doc entity or a doc entity of a different type."
 	}
 	return [${:@use} origin]
       }
@@ -686,7 +667,7 @@
       }
     }
 
-    # @method as_text
+    # @.method as_text
     #
     # text is used to access the content of doc of an Entity, and
     # performs substitution on it.  The substitution is not essential,
@@ -700,16 +681,23 @@
       }
       return [subst [join $doc " "]]
     }
+
+    :public method error {msg} {
+      return -code error "[current].[uplevel 1 [list ::nsf::current method]](): $msg"
+    }
+
   }
 
-  Tag create @glossary -superclass Entity {
+
+  # @class @glossary
+  @glossary eval {
     :property @pretty_name
     :property @pretty_plural
     :property @acronym
   }
 
 
-  Class create StructuredEntity -superclass Entity {
+  StructuredEntity eval {
 
     :public method part_attributes {} {
       set slots [:info lookup slots]
@@ -753,145 +741,87 @@
       }
       return $__owned_parts
     }
-    
-    :public method validate {} {
-      next
-      dict for {s entities} [:owned_parts -where "!\${:@stashed}"] {
-	foreach e $entities {
-	  # TODO: for now, it is sufficient to escape @use chains
-	  # here. review later ...
-	  if {![$e eval {info exists :@use}]} {
-	    $e [current method]
-	  }
-	}
-      } 
-    }
+
   }
 
 
-  Class create ContainerEntity -superclass StructuredEntity {
-    
-    Class create [current]::Resolvable {
-      :class property container:object,type=[:info parent]
-      :method get_fully_qualified_name {name} {
-	set container [[current class] container]
-	if {![string match "::*" $name]} {
-#	  puts -nonewline stderr "--- EXPANDING name $name"
-	  set name [$container @namespace]::$name 
-#	  puts stderr " to name $name"
-	}
-	next $name
-      }
-    }
+  ContainerEntity eval {
 
     Class create [current]::Containable {
-      # TODO: check the interaction of required, per-object property and ::nsf::assertion
-      #:object property container:object,type=[:info parent],required
-      :property container:object,type=[:info parent]
       :method create args {
-	#
-	# Note: preserve the container currently set at this callstack
-	# level.  [next] will cause the container to change if another
-	# container entity is initialised in the following!
-	#
-	if {[[current class] eval {info exists :container}]} {
-	  set container [[current class] container]
-	  set obj [next]
-	  if {![$obj eval {info exists :partof}]} {
-	    $container register $obj
-	  }
-	  return $obj
-	} else {
-	  next
+    	#
+    	# Note: preserve the container currently set at this callstack
+    	# level.  [next] might cause another container to be pushed on
+    	# top.
+    	#
+	set cont [:containers peek] 
+	set obj [next]
+	if {![$obj eval {info exists :partof}] && $cont ne ""} {
+	  $cont register $obj
 	}
+	return $obj
       }
-      :method create args {
-	#
-	# Note: preserve the container currently set at this callstack
-	# level.  [next] will cause the container to change if another
-	# container entity is initialised in the following!
-	#
-	if {[info exists :container]} {
-	  set cont ${:container}
-	  set obj [next]
-	  if {![$obj eval {info exists :partof}]} {
-	    $cont register $obj
-	  }
-	  return $obj
-	} else {
-	  next
-	}
-      }
-
     }
+
     # Note: The default "" corresponds to the top-level namespace "::"!
     :property {@namespace ""}
-
+    
     :property -class ::nx::doc::PartAttribute @class {
       :pretty_name "Class"
       :pretty_plural "Classes"
-      set :part_class ::nx::doc::@class
+      :part_class ::nx::doc::@class
     }
 
     :property -class ::nx::doc::PartAttribute @object {
       :pretty_name "Object"
       :pretty_plural "Objects"
-      set :part_class ::nx::doc::@object
+      :part_class ::nx::doc::@object
     }
    
     :property -class ::nx::doc::PartAttribute @command {
       :pretty_name "Command"
       :pretty_plural "Commands"
-      set :part_class ::nx::doc::@command
+      :part_class ::nx::doc::@command
     }
 
-    # :property @class:object,type=::nx::doc::@class,multivalued {
-    #   set :incremental 1
-    # }
+    :public method register {containable:object,type=::nx::doc::Entity} {
+      set tag [[$containable info class] tag]
+      if {[:info lookup methods -source application "@$tag"] ne ""} {
+	:@$tag $containable
+      } elseif {[info exists :previous]} {
+	${:previous} register $containable
+      }
+    }
 
-    # :property @object:object,type=::nx::doc::@object,multivalued {
-    #   set :incremental 1
-    # }
+    :property previous:object,type=[current]
 
-    # :property @command:object,type=::nx::doc::@command,multivalued {
-    #   set :incremental 1
-    # }
+    :public method announceAsContainer {tag:object,type=::nx::doc::Tag} {
+      $tag containers push [current]
+    }
 
-    # :method init {} {
-    #   next
-
-    #   QualifierTag mixin add [current class]::Resolvable
-    #   [current class]::Resolvable container [current]
-    #   foreach {attr part_class} [:part_attributes] {
-    #   	$part_class class mixin add [current class]::Containable
-    #   	$part_class container [current]
-    #   }
-    # }
-
-    :method destroy {} {
-      foreach {attr part_class} [:part_attributes] {
-	#$part_class class mixin add [current class]::Containable
-	if {[$part_class eval {info exists :container}] && \
-		[$part_class container] eq [current]} {
-	  $part_class eval {unset :container}
-	}
+    :public method getAuthoritativeNS {} {
+      if {${:@namespace} eq "" && [info exists :previous]} {
+	return ${:previous} [current method]
+      } else {
+	return ${:@namespace}; # defaults to top-level/global NS
       }
-      next
     }
 
-    :public method register {containable:object,type=::nx::doc::Entity} {
-      set tag [[$containable info class] tag]
-      if {[:info lookup methods -source application "@$tag"] ne ""} {
-	:@$tag $containable
-      }
+    :protected method init args {
+      next
+      :announceAsContainer [:info class]
     }
+    
   }
 
-  Tag create @project -superclass ContainerEntity {
+  @project eval {
 
-    :property sandbox:object,type=::nx::doc::Sandbox
-    :property sources
+    # / / / / / / / / / / / / / / / / / /
+    # Doc entity interface
+    # / / / / / / / / / / / / / / / / / /
 
+    :public property sandbox:object,type=::nx::doc::Sandbox
+
     :property url
     :property license
     :property creationdate
@@ -901,7 +831,7 @@
     :property depends:0..*,object,type=[current]
     
     :property -class ::nx::doc::PartAttribute @glossary {
-      set :part_class ::nx::doc::@glossary
+      :part_class ::nx::doc::@glossary
       :public method get {domain prop} {
 	set l [next]
 	if {[$domain eval {info exists :depends}]} {
@@ -916,9 +846,167 @@
     :property -class ::nx::doc::PartAttribute @package {
       :pretty_name "Package"
       :pretty_plural "Packages"
-      set :part_class ::nx::doc::@package
+      :part_class ::nx::doc::@package
     }
 
+    # / / / / / / / / / / / / / / / / / /
+    # Frontend interface
+    # / / / / / / / / / / / / / / / / / /
+
+    :private method "frontend unknown" {m args} {
+      :error "The NXDoc frontend '$m' is not available."
+    }
+
+    :public method read {frontend srcs cmds} -returns 0..*,object,type=::nx::doc::Entity {
+      :frontend $frontend $srcs $cmds
+    }
+
+    :public class method newFromSources {
+	{-frontend dc} 
+	{-sandboxed:boolean 1}
+	-include
+	-exclude
+	sources
+	args
+      } {
+
+      #
+      # Action 1)  Object creation
+      #
+      set newPrj [:new {*}$args]
+
+      #
+      # Action 2)  Initialise a sandbox
+      #      
+      set sandbox [$newPrj sandbox [Sandbox new -interp [expr {$sandboxed?[interp create]:""}]]]
+          
+      #
+      # Action 3) Extract documentation sources (1pass)
+      #    
+      $sandbox do [$newPrj get1PassScript $sources]
+      set sourceScripts [$sandbox getDocumentationScripts]
+      
+      #
+      # Action 4) Determine command population through introspection (2pass)
+      #
+      $sandbox do [$newPrj get2PassScript $sourceScripts]
+
+
+      #
+      # Action 5) Applying command filters and obtain the workspace in
+      # terms of commands ...
+      #
+      if {[info exists include] && [info exists exclude]} {
+	$newPrj error "Inclusion and exclusion constraints are mutually exclusive!"
+      }
+
+      set nsFilters [list]
+      if {[info exists include] && $include ne ""} {
+	set nsFilters [list $include]
+      }
+      if {[info exists exclude] && $exclude ne ""} {
+	set nsFilters [list -not $exclude]
+      }
+
+      set commandsFound [$sandbox getCommandsFound {*}$nsFilters]
+
+      #
+      # Action 6) Load the requested frontend extension
+      #
+      package req nx::doc::$frontend
+      
+      #
+      # Action 7) Have the intended documentation entities processed
+      # (documented, and meant to be visible)
+      #
+      # $newPrj readSrcs $frontend $sourceScripts $commandsFound
+      $newPrj read $frontend $sourceScripts $commandsFound
+
+      return $newPrj
+    }
+
+    :public method get1PassScript {sources} {
+      set 1pass "::nx::doc::__trace_pkg\n"
+      dict for {srcType items} $sources {
+	if {![llength $items]} continue;
+	switch -exact -- $srcType {
+	  package {
+	    foreach i $items {
+	      append 1pass "package require $i\n" 
+	    }
+	  }
+	  source {
+	    foreach i $items {
+	      append 1pass "source $i\n" 
+	    }
+	  }
+	  eval {
+	    error "Not implemented!"
+	    # foreach i $items {
+	    #   append 1pass "info script X-EVAL\n"
+	    #   append 1pass "$i\n"
+	    # }
+	    # set srcType source
+	    # set items X-EVAL
+	  }
+	  default {
+	    error "Unsupported documentation source type '$srcType'"
+	  }
+	}
+	${:sandbox} permissive lappend $srcType $items
+      }
+      return $1pass
+    }
+
+    :public method get2PassScript {sourceScripts} {
+      set 2pass "::nx::doc::__init\n"
+      dict for {id info} $sourceScripts {
+	set block "%s"
+	dict with info {
+	  # Available vars:
+	  #
+	  # package
+	  # path
+	  # script
+	  # dependency
+	  #
+	  if {$dependency || ![info exists script]} continue;
+
+	  if {[info exists package]} {
+	    set fragment "
+	      ::nx::doc::__cpackage push $package;
+	      %s 
+	      ::nx::doc::__cpackage pop;
+	    "
+	    set block [format $block $fragment]
+	    unset package
+	  }
+
+	  if {[info exists path]} {
+	    set block [format $block "info script $path;\n%s"]
+	    unset path
+	  }
+	}
+	append 2pass [format $block $script]
+	unset script
+      }
+      return $2pass
+    }
+
+    # / / / / / / / / / / / / / / / / / /
+    # Backend interface
+    # / / / / / / / / / / / / / / / / / /
+
+    :public method write {{-format html} args} {
+      package req nx::doc::$format
+      $format run -project [current] {*}$args
+    }
+
+
+    # / / / / / / / / / / / / / / / / / /
+    # Lifecycling
+    # / / / / / / / / / / / / / / / / / /
+
     :public method destroy {} {
       #
       # TODO: Using the auto-cleanup feature in [Test case ...] does
@@ -936,46 +1024,37 @@
     :method init {} {
       #
       # TODO: the way we provide the project as a context object to
-      # all entities is not easily restricted. Review later ...
-      # 
-      :current_project [current]; # sets a per-class-object variable on Entity!
+      # all entities is not easily restricted. Review later (e.g.,
+      # relocate into the Validator) ...
+      #
+      [current class] containers reset
+      :current_project [current]; # side effect: sets a per-class-object variable on Entity!
       next
     }
+
   }
 
-  #
-  # Now, define some kinds of documentation entities. The toplevel
-  # docEntities are named objects in the ::nx::doc::entities namespace
-  # to ease access to it.
-  #
-  # For now, we define here the following toplevel docEntities:
-  #
-  # - @package 
-  # - @command
-  # - @object
-  # - ...
-  #
-  # These can contain multiple parts.
-  #  - @method
-  #  - @param
-  #  - ...
-  #
+  
+  # TODO: decide how to deal with @package and @project names (don't
+  # need namespace delimiters!)
 
-  Tag create @package -superclass ContainerEntity {
+  @package eval {
     :property -class ::nx::doc::PartAttribute @require
-    :property -class ::nx::doc::PartAttribute @version
+    :property @version
+    :property -class ::nx::doc::PartAttribute @author 
+    
   }
 
-  QualifierTag create @command -superclass StructuredEntity {
+  @command eval {
     :property -class ::nx::doc::PartAttribute @parameter {
-      set :part_class ::nx::doc::@param
+      :part_class ::nx::doc::@param
     }
     :property -class ::nx::doc::PartAttribute @return {
       :method require_part {domain prop value} {
 	set value [expr {![string match ":*" $value] ? "__out__: $value": "__out__$value"}]
 	next [list $domain $prop $value]
       }
-      set :part_class ::nx::doc::@param
+      :part_class ::nx::doc::@param
     }
 
     :public forward @sub-command %self @command
@@ -984,103 +1063,48 @@
       :pretty_name "Subcommand"
       :pretty_plural "Subcommands"
       :public method id {domain prop value} { 
-	# TODO: [${:part_class}] resolves to the property slot
-	# object, not the global @command object. is this intended, in
-	# line with the intended semantics?
 	return [${:part_class} [current method] \
 		    -partof_name [$domain name] \
 		    -scope ${:scope} -- $value]
       }
-      set :part_class ::nx::doc::@command
+      :part_class ::nx::doc::@command
     }
-
-    :public method validate {} {
-      if {[info exists :pdata] && \
-	      [:pinfo get -default complete status] ne "missing"} {
-
-	if {![info exists :@command]} {
-	  set params [list]
-	  set param_names [list]
-	  if {[info exists :@parameter]} {
-	    foreach p [:@parameter] {
-	      set value [$p name]
-	      lappend param_names $value
-	      if {[$p eval {info exists :default}] || $value eq "args" } {
-		set value "?$value?"
-	      }
-	      lappend params $value
-	    }
-	  }
-	  
-	  set ps [:pinfo get -default "" bundle parameter]
-	  dict for {actualparam paraminfo} $ps {
-	    if {$actualparam ni $param_names} {
-	      set p [:@parameter $actualparam]
-	      $p pdata [lappend paraminfo status missing]
-	    }
-	  }
-	} 
-
-	if {![:pinfo exists bundle parametersyntax]} {
-	  :pinfo set bundle parametersyntax $params
-	}
-	
-	# Note: [next] will cause the missing parameter created to
-	# be validated and will have the appropriate status
-	# propagated upstream!
-	next
-      }
-    }
   }
   
-  QualifierTag create @object \
-      -superclass StructuredEntity \
-      -mixin ContainerEntity::Containable {
+  @object eval {
+    
+    :public forward @object %self @child-object
+    
+    :property -class ::nx::doc::PartAttribute @child-object {
+      :part_class ::nx::doc::@object
+      :public method id {domain prop value} {
+	return [${:part_class} id [join [list [$domain name] $value] ::]]
+      }
+      
+    }
+    
+    :public forward @class %self @child-class
+    
+    :property -class ::nx::doc::PartAttribute @child-class {
+      :part_class ::nx::doc::@class
+      :public method id {domain prop value} {
+	return [${:part_class} id [join [list [$domain name] $value] ::]]
+      }
+    }
 
-	:property -class ::nx::doc::PartAttribute @author 
-
-	:public forward @object %self @child-object
-
-	:property -class ::nx::doc::PartAttribute @child-object {
-	  set :part_class ::nx::doc::@object
-	  :public method id {domain prop value} {
-#	    puts stderr "CHILD-OBJECT: [current args]"
-	    # if {![info exists :part_class]} {
-	    #   error "Requested id generation from a simple part property!"
-	    # }
-	    return [${:part_class} id [join [list [$domain name] $value] ::]]
-#	    return [${:part_class} id -partof_name [$domain name] -scope ${:scope} $value]
-	  }
-
-	}
-
-	:public forward @class %self @child-class
-
-	:property -class ::nx::doc::PartAttribute @child-class {
-	  set :part_class ::nx::doc::@class
-	  :public method id {domain prop value} {
-	    #puts stderr "CHILD-CLASS: [current args]"
-	    # if {![info exists :part_class]} {
-	    #   error "Requested id generation from a simple part property!"
-	    # }
-	    return [${:part_class} id [join [list [$domain name] $value] ::]]
-	    #return [${:part_class} id -partof_name [$domain name] -scope ${:scope} $value]
-	  }
-	}
-
 	:public forward @method %self @object-method
 
 	:property -class ::nx::doc::PartAttribute @object-method {
 	  :pretty_name "Object method"
 	  :pretty_plural "Object methods"
-	  set :part_class ::nx::doc::@method
+	  :part_class ::nx::doc::@method
 	}
 
 	:public forward @property %self @object-property
 	#:forward @param %self @object-param
 
 	:property -class ::nx::doc::PartAttribute @object-property {
-	  set :part_class ::nx::doc::@param
+	  :part_class ::nx::doc::@param
 	}
 
 	:method undocumented {} {
@@ -1097,8 +1121,7 @@
 	}
       }
 
-  QualifierTag create @class \
-      -superclass @object {
+  @class eval {
 
 	:property -class ::nx::doc::PartAttribute @superclass
 	
@@ -1107,7 +1130,7 @@
 	:property -class ::nx::doc::PartAttribute @class-property {
 	  :pretty_name "Per-class attribute"
 	  :pretty_plural "Per-class attributes"
-	  set :part_class ::nx::doc::@param
+	  :part_class ::nx::doc::@param
 	}
 	
 	:public forward @class-object-method %self @object-method
@@ -1118,15 +1141,15 @@
 	:property -class ::nx::doc::PartAttribute @class-hook {
 	  :pretty_name "Hook method"
 	  :pretty_plural "Hook methods"
-	  set :part_class ::nx::doc::@method
+	  :part_class ::nx::doc::@method
 	}
 
 	:public forward @method %self @class-method
 
 	:property -class ::nx::doc::PartAttribute @class-method {
 	  :pretty_name "Provided method"
 	  :pretty_plural "Provided methods"
-	  set :part_class ::nx::doc::@method
+	  :part_class ::nx::doc::@method
 	  :method require_part {domain prop value} {
 	    # TODO: verify whether these scoping checks are sufficient
 	    # and/or generalisable: For instance, is the scope
@@ -1142,50 +1165,29 @@
 	    next
 	  }
 	}
-	:public method validate {} {
-	  next
-	  #
-	  # TODO: Certain metadata could also be valid in "missing"
-	  # state, e.g., paramtersyntax? Re-arrange later ...
-	  #
-	  if {[info exists :pdata] &&
-	      [:pinfo get -default complete status] ne "missing"} {
-	    #
-	    # Note: Some metadata on classes cannot be retrieved from
-	    # within the tracers, as they might not be set local to the
-	    # class definition. Hence, we gather them at this point.
-	    #
-	    set prj [:current_project]
-	    set box [$prj sandbox]
-	    set statement [list ::nsf::dispatch ${:name} \
-		::nsf::methods::class::info::objectparameter \
-		parametersyntax]
-	    :pinfo set bundle parametersyntax [$box eval $statement]
-	  }
-	}
       }
   
-  Class create PartEntity -superclass Entity {
+
+  PartEntity eval {
     :property partof:object,type=::nx::doc::StructuredEntity,required
     :property part_attribute:object,type=::nx::doc::PartAttribute,required
   }
  
 
-  # @object ::nx::doc::@method
+  # @class ::nx::doc::@method
   #
   # "@method" is a named entity, which is part of some other
   # docEntity (a class or an object). We might be able to use the
   # "use" parameter for registered aliases to be able to refer to the 
   # documentation of the original method.
   #
-  PartTag create @method \
-      -superclass StructuredEntity {
+  @method eval {
 
 	:property -class ::nx::doc::SwitchAttribute @syshook:boolean {
 	  set :default 0
 	}
 	:property -class ::nx::doc::PartAttribute @parameter {
-	  set :part_class ::nx::doc::@param
+	  :part_class ::nx::doc::@param
 	}
 	:property -class ::nx::doc::PartAttribute @return {
 	  #
@@ -1200,7 +1202,7 @@
 	    set value [expr {![string match ":*" $value] ? "__out__: $value": "__out__$value"}]
 	    next [list $domain $prop $value]
 	  }
-	  set :part_class ::nx::doc::@param
+	  :part_class ::nx::doc::@param
 	}
 
 	:public class method new {	       
@@ -1224,7 +1226,7 @@
 	:public forward @sub-method %self @method
 
 	:property -class ::nx::doc::PartAttribute @method {
-	  set :part_class ::nx::doc::@method
+	  :part_class ::nx::doc::@method
 	  :public method id {domain prop name} {
 	    # TODO: ${:part_class} resolves to the local slot
 	    # [current], rather than ::nx::doc::@method. Why?
@@ -1242,62 +1244,6 @@
 	  return ::nsf::${scope}::[string trimleft [[:partof] name] :]::${:name}
 	}
 
-	# @method->validate()
-	:public method validate {} {
-	  set partof [:get_owning_partof]
-	  if {[info exists :pdata] &&
-	      [:pinfo get -default complete status] ne "missing"} {
-	    #
-	    # Note: Some information on methods cannot be retrieved from
-	    # within the tracers as they might not be set local to the
-	    # method definition. Hence, we gather them at this point. I
-	    # will review whether there is a more appropriate way of
-	    # dealing with this issue ...
-	    #
-	    set prj [:current_project]
-	    set box [$prj sandbox]
-	    set obj [$partof name]
-	   
-	    if {[:pinfo exists bundle handle]} {
-	      set handle [:pinfo get bundle handle]
-	      :pinfo set bundle redefine-protected [$box eval [list ::nsf::method::property $obj $handle redefine-protected]]
-	      :pinfo set bundle call-protected [$box eval [list ::nsf::method::property $obj $handle call-protected]]
-	    }
-	    
-	    set params [list]
-	    set param_names [list]
-	    if {[info exists :@parameter]} {
-	      foreach p [:@parameter] {
-		set value [$p name]
-		lappend param_names $value
-		if {[$p eval {info exists :default}] || $value eq "args" } {
-		  set value "?$value?"
-		}
-		lappend params $value
-	      }
-	    }
-	    
-	    dict for {actualparam paraminfo} [:pinfo get -default "" bundle parameter] {
-	      if {$actualparam ni $param_names} {
-		set p [:@parameter $actualparam]
-		$p pdata [lappend paraminfo status missing]
-	      }
-	    }
-	    
-	    if {![:pinfo exists bundle parametersyntax]} {
-	      :pinfo set bundle parametersyntax $params
-	    }
-	   
-	    # Note: [next] will cause the missing parameter created to
-	    # be validated and will have the appropriate status
-	    # upstream!
-	    next
-	  } else {
-	    # To realise upward status propagation for submethods, use:
-	    # ${:partof} pinfo propagate status mismatch 
-	    $partof pinfo propagate status mismatch
-	  }
-	}
 	
 	:public method get_sub_methods {} {
 	  if {[info exists :@method]} {
@@ -1337,36 +1283,20 @@
 
       }; # @method
   
-  # PartTag create @subcommand -superclass {Part @command}
-  #  PartTag create @subcommand -superclass {Part @command}
-
-  # @object ::nx::doc::@param
+  # @class ::nx::doc::@param
   #
   # The entity type "@param" represents the documentation unit
   # for several parameter types, e.g., object, method, and
   # command parameters.
   #
-  PartTag create @param \
-      -superclass PartEntity {
-
-	#:property spec
+  @param eval {
 	:property -class ::nx::doc::PartAttribute @spec
 	:property default
 
 	:public class method id {partof_name scope name} {
 	  next [list [:get_unqualified_name ${partof_name}] $scope $name]
 	}
-	
-	# :class method id {partof_name name} {
-	#   # The method contains the parameter-specific name production rules.
-	#   #
-	#   # @param partof Refers to the entity object which contains this part 
-	#   # @param name Stores the name of the documented parameter
-
-	#   set partof_fragment [:get_unqualified_name ${partof_name}]
-	#   return [:root_namespace]::${:tag}::${partof_fragment}::${name}
-	# }
-	
+		
 	# @class-object-method new
 	#
 	# The per-object method refinement indirects entity creation
@@ -1403,46 +1333,6 @@
 	    next
 	  }
 	}
-
-	
-	# @param->validate()
-	:public method validate {} {
-	  #
-	  # TODO: For now, we escape from @param validaton on command
-	  # parameters. There is no equivalent to [info parameter]
-	  # available, so we would need to cook a substitute based on
-	  # the parametersyntax. Review later ...
-	  #
-	  if {${:name} eq "__out__" && \
-		  [${:partof} info has type ::nx::doc::@command]} return;
-
-	  #
-	  # Here, we escape from any parameter verification for
-	  # parameters on forwards & alias, as there is no basis for
-	  # comparison!
-	  #
-	  if {[${:partof} info has type ::nx::doc::@method] && \
-		  [${:partof} pinfo get bundle type] in [list forward alias]} {
-	    dict set :pdata status ""
-	    return;
-	  }
-
-	  if {[info exists :pdata] && \
-		  [:pinfo get -default complete status] ne "missing"} {
-	    
-	    # valid for both object and method parameters
-	    set pspec [:pinfo get -default "" bundle spec]
-	    if {[info exists :spec] && \
-		    ${:spec} ne $pspec} {
-	      :pinfo propagate status mismatch 
-	      :pinfo lappend validation "Specification mismatch. Expected: \
-						'${:spec}' Got: '$pspec'."
-	    }
-	    next
-	  } else {
-	    ${:partof} pinfo propagate status mismatch 
-	  }
-	}
       }
 
   #
@@ -1667,7 +1557,6 @@
       return $line
     }
 
-
     :method as_list {} {
 	set preprocessed [list]
 	set is_code_block 0
@@ -1677,11 +1566,8 @@
 	    set is_code_block [expr {!$is_code_block}]
 	    append line \n
 	  } elseif {${is_code_block}} {
-	    # set line [:map $line unescape]
 	    append line \n
 	  } else {
-	    # set line [:map $line sub]
-	    # set line [:map $line unescape]
 	    set line [string trimleft $line]
 	    if {$line eq {}} {
 	      set line "\n\n"
@@ -1696,6 +1582,7 @@
       set preprocessed [join [:as_list] " "]
       set preprocessed [:map $preprocessed]
       set preprocessed [:unescape $preprocessed]
+
       # TODO: For now, we take a passive approach: Some docstrings
       # might fail because they contain substitution characters
       # ($,[]); see nx.tcl. The same goes for legacy xodoc docstrings,
@@ -1704,6 +1591,7 @@
       # escape/unescape evaluation chars; at the same time, we can't
       # distinguish errors on unintended and intended evaluations.
       # ...
+
       if {[catch {set preprocessed [subst $preprocessed]} msg]} {
 	puts stderr SELF=[current]
 	puts stderr MSG=$msg
@@ -1716,6 +1604,7 @@
   }
 
   #
+  # NXDoc backend infrastructure:
   # A Renderer base class ...
   #
   Class create Renderer -superclass MixinLayer {
@@ -1791,7 +1680,7 @@
     }
 				
     :method readAsset {assetName} {
-      set assetDir [find_asset_path]
+      set assetDir [findAssetPath]
       set assetPath [file join $assetDir $assetName]
       return [:read $assetPath]
     }
@@ -1909,9 +1798,6 @@
 	{-theme yuidoc} 
 	args
       } {
-      # TODO: Relocate trigger validation!
-      $project validate
-      # --
       :apply
       :current_theme $theme
       :layout $layout $project $theme {*}$args
@@ -1966,49 +1852,84 @@
       return $value
     }
 
-    :protected property {current_packages "*"}
-    :property {permissive_pkgs:1..* "*"} {
-      set :incremental 1
+    :protected property {current_packages ""}
+
+    :public method "permissive lappend" {type value} {
+      set d [lindex [current methodpath] 0]
+      dict [current method] :$d $type {*}$value
     }
 
+    :public method "permissive get" {type} {
+      if {![info exists :permissive]} {
+	set :permissive [dict create]
+      }
+      dict [current method] ${:permissive} $type
+    }
+
+    :public method getDocumentationScripts {} {
+      if {[info exists :dSources]} {
+	return ${:dSources}
+      }
+    }
+
     #
     # some callbacks invoked from within the sandbox interp
     #
-
     :public method "cpackage pop" {} {
       set :current_packages [lrange ${:current_packages} 0 end-1]
     }
     :public method "cpackage push" {p} {
-      lappend :current_packages [string tolower $p]
+      lappend :current_packages $p
     }
     :public method "cpackage top" {} {
-      return [lindex ${:current_packages} end]
+      if {[info exists :current_packages]} {
+	return [lindex ${:current_packages} end]
+      }
     }
 
-    :public method at_source {filepath} {
+    :public method at_source {filePath} {
       set cpackage [:cpackage top]
-      if {$cpackage in ${:permissive_pkgs}} {
-	lappend :source $cpackage $filepath
+      set fh [open $filePath r]
+      set script [read $fh] 
+      catch {close $fh}
+
+      set info [dict create]
+      set key ""
+      if {$cpackage ne ""} {
+	set key "$cpackage."
+	dict set info package $cpackage
+	dict set info dependency [expr {$cpackage ni [:permissive get package]}]
       } else {
-	dict set :deps $filepath $cpackage
+	# TODO: dict set info dependency [expr {$filePath ni [:permissive get source]}]
+	dict set info dependency 1
       }
+      dict set info path $filePath
+      dict set info script $script
+      
+      dict set :dSources $key$filePath $info
     }
 
     :public method at_load {filepath} {
       set cpackage [:cpackage top]
-      if {$cpackage ne ${:permissive_pkgs}} {
-	dict set :deps $filepath $cpackage
+      set key ""
+      set info [dict create]
+      dict set info path $filepath
+      if {$cpackage ne ""} {
+	set key "$cpackage."
+	dict set info package $cpackage
+	dict set info dependency [expr {$cpackage ni [:permissive get package]}]
+      } else {
+	# TODO: dict set info dependency [expr {$filePath ni [:permissive get source]}]
+	dict set info dependency 1
       }
-    }
+      dict set :dSources $key$filepath $info
+  }
 
 
     :public method at_register_package {pkg_name version} {
       dict set :registered_packages $pkg_name version $version
     }
-#    :public method at_deregister_package {} {
-#      set :current_packages [lrange ${:current_packages} 0 end-1]
-#    }
-    # [list ->status:in,arg=complete|missing|prototype|mismatch,slot=[current] missing]
+
     :public method at_register_command [list \
 	name:fqn,slot=[current] \
 	->cmdtype:in,arg=@object|@class|@command|@method,slot=[current] \
@@ -2018,32 +1939,31 @@
         ->docstring:optional,slot=[current] \
 	->bundle
      ] {
-      # peek the currently processed package (if any)
       set storable_vars [info vars >*]
-      # set cpackage [lindex ${:current_packages} end]
+      foreach svar $storable_vars {
+	dict set :registered_commands $name [string trimleft $svar >] [set $svar]
+      }
+      
+      # peek the currently processed package (if any)
       set cpackage [:cpackage top]
-      if {$cpackage in ${:permissive_pkgs}} {
+      if {$cpackage ne ""} {
 	dict set :registered_commands $name package $cpackage
-	foreach svar $storable_vars {
-	  dict set :registered_commands $name [string trimleft $svar >] [set $svar]
-	}
+	dict set :registered_commands $name dependency \
+	    [expr {$cpackage ni [:permissive get package]}]
+      } else {
+	# FIXME dict set :registered_commands $name dependency \
+	#    [expr {$source ni [:permissive get source]}]
+	dict set :registered_commands $name dependency 1
       }
     }
 
     :public method at_deregister_command [list name:fqn,slot=[current]] {
-      set cpackage [:cpackage top]
-      if {$cpackage in ${:permissive_pkgs}} {
-	dict unset :registered_commands $name
-      }
+      dict unset :registered_commands $name
     }
 
     :public method init args {
       :do {
-
 	#
-	# hide selected built-in Tcl commands and put simple
-	# forwarding proxies in place ...
-	#
 	# TODO: refactor the proxy handling ...
 	#
 	interp hide "" proc
@@ -2054,14 +1974,13 @@
 	interp hide "" auto_import
 
 	interp invokehidden "" proc ::proc args {
-	  #set ns [uplevel [list interp invokehidden "" namespace current]]
 	  uplevel [list interp invokehidden "" proc {*}$args]
 	}
 
 	proc ::namespace args {
-	  #set ns [uplevel [list interp invokehidden "" namespace current]]
-	  #interp invokehidden "" -namespace $ns namespace {*}$args
+	  # set ns [uplevel [list interp invokehidden "" namespace current]]
 	  uplevel [list interp invokehidden "" namespace {*}$args]
+	  # interp invokehidden {} -namespace $ns namespace {*}$args
 	}
 
 	proc ::source args {
@@ -2131,7 +2050,6 @@
 	    
 	    proc list_commands {{parent ""}} {
 	      set ns [dict create]
-	      #set cmds [string trim "[join [info commands ${parent}::*] \" 0 \"] 0" 0]
 	      #
 	      # Note: We trigger a [namespace import] for the
 	      # currently processed namespace before requesting the
@@ -2140,14 +2058,12 @@
 	      # i.e. after having computed the [info
 	      # commands] snapshot!
 	      #
-#	      namespace eval ::nx::doc::__x [list namespace import -force ${parent}::*]
+
 	      set cmds [info commands ${parent}::*]
 
 	      set exported [list]
 	      foreach cmd $cmds {
 		dict set ns ::[string trimleft $parent :] $cmd [is_exported $cmd]
-		    
-#[expr {[info commands ::nx::doc::__x::[namespace tail $cmd]] ne ""}]
 	      }
 
 	      foreach nsp [namespace children ${parent}::] {
@@ -2164,8 +2080,6 @@
 	      # 
 	      # pre-state
 	      #
-	      # set pre_loaded [dict values \
-	      # 			  [dict create {*}[concat {*}[info loaded ""]]]]
 	      set pre_loaded [lreverse [concat {*}[info loaded ""]]]
 	      set pre [::nx::doc::list_commands]
 	      set pre_commands [dict create {*}[concat {*}[dict values $pre]]]
@@ -2176,7 +2090,6 @@
 	      #
 	      # post-state
 	      #
-	      #set post_loaded [dict create {*}[concat {*}[info loaded ""]]]
 	      set post_loaded [lreverse [concat {*}[info loaded ""]]]
 	      set post [::nx::doc::list_commands]
 	      set post_commands [dict create {*}[concat {*}[dict values $post]]]
@@ -2192,10 +2105,6 @@
 	      set delta_pkg [dict remove \
 				 [dict create {*}$post_loaded] \
 				 [dict keys [dict create {*}$pre_loaded]]]
-
-	      #puts stderr "DELTAS pkg $delta_pkg"
-	      #puts stderr "DELTAS namespace $delta_namespaces"
-	      #puts stderr "DELTAS commands $delta_commands"
 	      
 	      lassign $delta_pkg pkg_name filepath
 	      set filepath [file normalize $filepath]
@@ -2207,8 +2116,9 @@
 	      # parametersyntax prints.
 	      if {[info commands ::nsf::objectsystem::create] ne "" && \
 		      [::nsf::configure objectsystem] eq ""} {
-		set rootclass ::nx::doc::_%&obj
-		set rootmclass ::nx::doc::_%&cls
+		namespace eval ::nx::doc::_%& {}
+		set rootclass ::nx::doc::_%&::obj
+		set rootmclass ::nx::doc::_%&::cls
 		::nsf::objectsystem::create $rootclass $rootmclass
 	      } else {
 		lassign {*}[::nsf::configure objectsystem] rootclass rootmclass
@@ -2268,10 +2178,6 @@
 		}
 	      } 
 	      interp invokehidden "" -namespace $ns package $subcmd {*}$args
-	      # uplevel [list interp invokehidden "" package $subcmd {*}$args]
-#	      if {$was_registered} {
-#		::nx::doc::__at_deregister_package
-#	      }
 	    }
 
 	    #
@@ -2303,7 +2209,7 @@
 	      # helper objsys to retrieve command parameter specs and
 	      # parametersyntax prints.
 	      # 
-	      if {$rootclass ne "::nx::doc::_%&obj"} {
+	      if {$rootclass ne "::nx::doc::_%&::obj"} {
 		
 		::nsf::configure keepinitcmd true;
 	      
@@ -2333,7 +2239,6 @@
 	      		{*}[expr {[::nsf::var::exists $obj __initcmd] && [::nsf::var::set $obj __initcmd] ne ""?[list ->docstring [::nsf::var::set $obj __initcmd]]:[list]}]
 	      	    return $obj
 	      	  }
-		# ::nsf::relation $rootmclass class-mixin ${::nx::doc::rootns}::__Tracer
 	      
 	      if {[info commands "::nx::Object"] ne ""} {
 		$rootmclass $sysmeths(-class.create) ${::nx::doc::rootns}::__ObjTracer
@@ -2481,35 +2386,6 @@
 		return $handle
 	      }
 
-	      	# if {[$object info method type ${:name}] eq "forward"} {
-	      	#   set cmd ""
-	      	#   foreach w [lrange [$object info method definition ${:name}] 2 end] {
-	      	#     if {[string match ::* $w]} {
-	      	#       set cmd $w
-	      	#       break
-	      	#     }
-	      	#   }
-		#   if {$cmd ne "" && [string match ::nsf::* $cmd]} {
-		#     # TODO: we assume here, the cmd is a primitive
-	      	#     # command and we intend only to handle cases from
-		#     # predefined or xotcl2. Make sure this is working
-	      	#     # reasonable for other cases, such as forwards to 
-	      	#     # other objects, as well
-	      	#     if {![catch {set actualParams [::nx::Object info method parameter $cmd]}]} {
-	      	#       # drop usual object
-	      	#       set actualParams [lrange $actualParams 1 end]
-	      	#       # drop per object ; TODO: always?
-	        #             if {[lindex $actualParams 0] eq "-per-object"} {
-	      	# 	set actualParams [lrange $actualParams 1 end]
-	      	# 	set syntax [lrange [::nx::Object info method parametersyntax $cmd] 2 end]
-	      	#       } else {
-	      	# 	set syntax [lrange [::nx::Object info method parametersyntax $cmd] 1 end]
-	      	#       }
-	      	#     }
-	      	#   }
-		# }
-	      
-	      
 	      rename ::nsf::method::forward ::nsf::_%&forward 
 	      ::interp invokehidden "" proc ::nsf::method::forward {
 							    args
@@ -2660,28 +2536,6 @@
 
     :public property registered_commands
 
-    :public method getCompanions {identifiers} {
-      set scripts [list]
-      dict for {source pkg} $identifiers {
-	set rootname [file rootname $source]
-	set dir [file dirname $source]
-	set companion $rootname.nxd
-	set srcs [dict create {*}"[join [list $source $rootname.nxd [file join $dir $pkg].nxd] " _ "] _"]
-	foreach src [dict keys $srcs] {
-	  if {![file isfile $src] || ![file readable $src]} continue;
-	  if {[file extension $src] eq [info sharedlibextension]} continue;
-	  set fh [open $src r]
-	  if {[catch {lappend scripts [read $fh]} msg]} {
-	    catch {close $fh}
-	    :log "error reading the file '$thing', i.e.: '$msg'"
-	  }
-	  catch {close $fh}
-	}
-      }
-      return $scripts
-
-    }
-
     :public method get_companions {} {
       set companions [dict create]
       dict for {cmd props} ${:registered_commands} {
@@ -2693,8 +2547,9 @@
       return [:getCompanions $companions]
     }
 
-    :public method get_registered_commands {
-	-exported:switch
+    :public method getCommandsFound {
+	-exported:boolean
+        -imported:switch
 	-types
 	-not:switch
 	nspatterns:optional
@@ -2709,31 +2564,26 @@
       dict filter ${:registered_commands} script {cmd props} {
 	dict with props {
 	  expr {[expr {[info exists nspatterns]?[expr {[regexp -- $nspatterns $cmd _] != $not}]:1}] && \
-		    [expr {$exported?[expr {$nsexported == $exported}]:1}] && \
-		    [expr {[info exists types]?[expr {$cmdtype in $types}]:1}]}
+		    [expr {[info exists exported]?[expr {$nsexported == $exported}]:1}] && \
+		    [expr {$nsimported == $imported}] && \
+			   [expr {[info exists types]?[expr {$cmdtype in $types}]:1}]}
 	}
       }
-      #lsearch -inline -all -regexp $additions {^::nsf::[^\:]+$}]
   }
 
-
-#    :forward do ::interp %1 {% set :interp}
     :public method do {script} {
       ::interp eval ${:interp} $script
     } 
 
     :public method destroy {} {
-      #
-      # TODO: Why am I called twice in doc.test? Because of the test
-      # enviroment (the auto-cleanup feature?)
-      #
-      # puts stderr "SELF [current object] interp ${:interp}"
-      # ::nsf::__db_show_stack
       if {${:interp} ne ""} {
 	if {[interp exists ${:interp}]} {
 	  interp delete ${:interp}
 	}
       } else {
+	#
+	# TODO: complete the coverage of the cleanup ...
+	#
 	:do {
 	  if {[info commands ::nsf::configure] ne ""} {
 	    ::nsf::configure keepinitcmd false;
@@ -2777,362 +2627,82 @@
 }
 
 
-namespace eval ::nx::doc::xodoc {
 
-  namespace import -force ::nx::*
-  namespace import -force ::nx::doc::*
 
-  # xodoc		->	nxdoc
-  # - - - - - - - - - - - - - - - -
-  # MetadataToken	Entity
-  # FileToken		@package 
-  # PackageToken	@package
-  # ConstraintToken	n/a
-  # MethodToken		n/a
-  # ProcToken		@method (scope = object)
-  # InstprocToken	@method (scope = class)
-  # ObjToken		@object
-  # ClassToken		@class
-  # MetaClassToken	n/a
-
-  Class create MetadataToken {
-    :class property analyzer
-    :public forward analyzer [current] %method
-    :method as {partof:object,type=::nx::doc::StructuredEntity} \
-        -returns object,type=::nx::doc::Entity {
-          error "Subclass responsibility"
-        } 
-    :public method emit {partof:object,type=::nx::doc::StructuredEntity} \
-        -returns object,type=::nx::doc::Entity {
-          set entity [:as $partof]
-          set props [:get_properties]
-          if {[dict exists $props description]} {
-            $entity @doc [dict get $props description]
-          }
-          return $entity
-        }
-    :method get_properties {} {
-      if {[info exists :properties]} {
-	set props [dict create]
-	foreach p ${:properties} {
-	  if {[info exists :$p]} {
-	    dict set props [string tolower $p] \
-		[:format [set :$p]]
-	  }
-	}
-	return $props
-      }
-    }
-    :method format {value} {
-      #
-      # 1. replace @-prefixed tags etc.
-      #
-      set value [[:analyzer] replaceFormatTags $value]
-      
-      #
-      # 2. escape Tcl evaluation chars in code listings
-      #     
-      set value [string map {
-	"\\" "\\\\" 
-	"{" "\\{" 
-	"}" "\\}" 
-	"\"" "\\\"" 
-	"[" "\\[" 
-	"]" "\\]" 
-	"$" "\\$"
-      } $value]
- 
-      #
-      # 3. box the prop value in a list (this avoids unwanted
-      # interactions with the line-by-line as_text post-processor)
-      #
-      return [list $value]
-    }
-  }
+#
+# Validator
+#
+namespace eval ::nx::doc {
   
-  Class create PackageToken -superclass MetadataToken
-  Class create FileToken -superclass MetadataToken {
-    :method as {partof:object,type=::nx::doc::StructuredEntity} \
-        -returns object,type=::nx::doc::Entity {
-          #
-          # TODO: Where to retrieve the package name from?
-          #
-          return [@package new -name XOTcl]
-        } 
-    :public method emit {partof:object,type=::nx::doc::StructuredEntity} \
-        -returns object,type=::nx::doc::Entity {
-          set entity [next]
-          set props [dict remove [:get_properties] description]
-          dict for {prop value} $props {
-            $entity @doc add "<h1>$prop</h1>[join $value]" end
-          }
-          $entity @namespace [[$entity current_project] @namespace]
-          return $entity
-        }
-  }
-  
-  #
-  # Note: For whatever reason, InstprocToken is provided but never
-  # used, at least in XOTcl-langRef. while most probably due to a lack
-  # of attention or a silent revocation of a design decision in xodoc,
-  # it forces us into code replication for differentiating the
-  # per-class and per-object scopes ... in xodoc, these scopes are
-  # double-encoded, both in proper token subclassifications as well as
-  # aggregation properties: procList, instprocList ... well, I will
-  # have to live with it.
-  #
+  MixinLayer create @project::Validator -prefix ::nx::doc {
 
-  Class create MethodToken -superclass MetadataToken
-  
-  Class create ProcToken -superclass MethodToken {
-    :method as {scope partof:object,type=::nx::doc::StructuredEntity} \
-        -returns object,type=::nx::doc::Entity {
-      return [$partof @${scope}-method [:name]]
-    } 
-    :public method emit {scope partof:object,type=::nx::doc::StructuredEntity} {
-      set entity [:as $scope $partof]      
-      set props [:get_properties]
-      if {[dict exists $props description]} {
-        $entity @doc [dict get $props description]
-      }
-      if {[dict exists $props return]} {
-	$entity @return [dict get $props return]
-      }
-      return $entity
+    namespace eval [[current] info parent] {
+          namespace import -force ::nx::doc::*
     }
-  }
-  
-  Class create InstprocToken -superclass MethodToken
-  
-  Class create ObjToken -superclass MetadataToken {
-    :method as {partof:object,type=::nx::doc::ContainerEntity} \
-        -returns object,type=::nx::doc::Entity {
-      return [@object new -name [:name]]
-    } 
-    :public method emit {entity:object,type=::nx::doc::Entity} \
-        -returns object,type=::nx::doc::Entity {
-          set entity [next]
-          foreach p [:procList] {
-            $p emit object $entity
-          }
-          return $entity
-        }
-  }
-  
-  Class create ClassToken -superclass ObjToken {
-    :method as {partof:object,type=::nx::doc::ContainerEntity} \
-        -returns object,type=::nx::doc::Entity {
-      return [@class new -name [:name]]
-    }
-    :public method emit {entity:object,type=::nx::doc::Entity} \
-        -returns object,type=::nx::doc::Entity {
-          set entity [next]
-          foreach iproc [:instprocList] {
-            $iproc emit class $entity
-          }
-          return $entity
-        }
-  }
-  
-  Class create MetaClassToken -superclass ClassToken
-  
-  namespace export MetadataToken FileToken MethodToken ProcToken \
-      InstprocToken ObjToken ClassToken MetaClassToken
-}
 
-
-#
-# post processor for initcmds and method bodies
-#
-namespace eval ::nx {
-  
-  namespace import -force ::nx::doc::*
-  
-  MixinLayer create processor -prefix ::nx::doc {
-    namespace eval ::nx::doc {
-      namespace eval ::nx::doc::MixinLayer {
+    namespace eval ::nx::doc::MixinLayer {
 	namespace export Mixin
-      }
-      namespace import -force ::nx::doc::MixinLayer::*
-      namespace export Mixin
-    }
+      }    
     
-    namespace import -force ::nx::doc::*
-    
-    Mixin create [current]::Entity {
-      :public method init args {
-	next
-	set prj [:current_project]
-	if {$prj ne ""} {
-	  set box [$prj sandbox]	  
-	  set cmdname [:get_fqn_command_name]
-	  if {[$box eval {info exists :registered_commands}] && \
-		  [$box eval [concat dict exists \${:registered_commands} $cmdname]]} {
-	    :pdata [$box eval [concat dict get \${:registered_commands} $cmdname]]
-	  }
-	}
-	[[current class] info parent] at_processed [current]
-      }
-    }
+    namespace import -force ::nx::doc::MixinLayer::*
 
-    Mixin create [current]::ContainerEntity {
-      :method init {} {
-	next
-	::nx::doc::QualifierTag mixin add ::nx::doc::ContainerEntity::Resolvable
-	::nx::doc::ContainerEntity::Resolvable container [current]
-	foreach {attr part_class} [:part_attributes] {
-	  $part_class class mixin add ::nx::doc::ContainerEntity::Containable
-	  $part_class container [current]
-	}
-      }
-    }    
+    :public method read {frontend srcs cmds} {
+      set box ${:sandbox}
+      [current class] apply
+      set provided_entities [next]
 
-    Mixin create [current]::@package {
-      :public method init args {
-	next
-	set prj [:current_project]
-	if {$prj ne ""} {
-	  set box [$prj sandbox]
-	  if {[$box eval [concat dict exists \${:registered_packages} ${:name}]]} {
-	    :pdata [$box eval [concat dict get \${:registered_packages} ${:name}]]
-	  }
-	}
-      }
-    }
+      #
+      # trigger the validation (top-down)
+      #
+      :validate
+      # --
 
-    Mixin create [current]::@method -superclass [current]::Entity {
-      :method init args {
-	next
-	set scope [expr {[${:part_attribute} scope] eq "class"?"class":"object"}]
-	set obj [:get_owning_object]
-	set method_name [:get_combined name]
-	set prj [:current_project]
-	if {$prj ne ""} {
-	  set box [$prj sandbox]	  
-	  set script "if {\[::nsf::object::exists $obj\]} {array set \"\" \[$obj eval {:__resolve_method_path \"$method_name\"}\]; ::nsf::dispatch \$(object) ::nsf::methods::${scope}::info::method handle \$(methodName)}"
-	  set cmdname [$box do $script]
-	  if {$cmdname ne "" && [$box eval [concat dict exists \${:registered_commands} $cmdname]]} {
-	    :pdata [$box eval [concat dict get \${:registered_commands} $cmdname]]
-	  }
+      [current class] revoke
+      [:info class] containers reset [current]
+      #
+      # TODO: is_validated to later to become a derived/computed
+      # property ... for now, we just need to escape from setting
+      # validation-related info in non-validated projects!
+      #
+      :is_validated 1; # is_validated = 1
+      
+      set present_entities [::nx::doc::filtered $provided_entities {[[:origin] eval {info exists :pdata}]}]
+      
+      # / / / / / / / / / / / / / / / / / / / / / 
+      # Handling "missing" documentation entities
+      #
+      # 1) Add support for "generated" packages and their validation.
+      #
+      
+      set pkgMap [dict create]
+      if {[$box eval {info exists :registered_packages}] && [$box permissive get package] ne ""} {
+	set generatedPackages [$box eval {set :registered_packages}]
+	set providedPackages [@package info instances]
+	set presentPackages [::nx::doc::filtered $providedPackages {[[:origin] eval {info exists :pdata}]}]
+	foreach presPkgName $presentPackages {
+	  set generatedPackages [dict remove $generatedPackages [$presPkgName name]]
+	  dict set pkgMap [$presPkgName name] $presPkgName
 	}
-	
-      }
-    }
-
-    Mixin create [current]::@param -superclass [current]::Entity {
-      :public method init args {
-	next
-	if {${:name} eq "__out__"} {
-	  if {[${:partof} pinfo exists bundle returns]} {
-	    :pdata [list bundle [list spec [${:partof} pinfo get bundle returns]]]
+	  set permissivePkgs [$box permissive get package]
+	  dict for {genPkgName info} $generatedPackages {
+	    if {$genPkgName in $permissivePkgs} {
+	      dict with info {
+		set pkgObj [@package new -name $genPkgName -@version $version]
+		$pkgObj pdata [list status missing]
+	      }
+	      dict set pkgMap $genPkgName $pkgObj
+	    }
 	  }
-	} elseif {[${:partof} pinfo exists bundle parameter ${:name}]} {
-	  lassign [${:partof} pinfo get bundle parameter ${:name}] spec default
-	  :pdata [list bundle [list spec $spec default $default]]
 	}
-      }
-    }
-
-        
-    #
-    # mixin layer interface
-    #
-
-    :method apply {} {
-      unset -nocomplain :processed_entities
-      next
-    }
-
-    :method revoke {} {
-      next
-      if {[info exists :processed_entities]} {
-	return [dict keys ${:processed_entities}]
-      }
-    }
-    
-    :public method at_processed {entity} {
-      dict set :processed_entities $entity _
-    }
-
-    #
-    # processor interface
-    #
-
-    :method log {msg} {
-      puts stderr "[current]->[uplevel 1 [list ::nsf::current method]]: $msg"
-    }
-
-    :public method process {
-	-sandboxed:switch 
-	-validate:switch
-	{-type project}
-	-include
-	-exclude
-	thing
-      } {
-      if {$type ne "project"} {
-	# TODO: Fix the naming requirements ...
-	set project [@project new -name "_%@"]
-	$project sources [list $type $thing]
-      } else {
-	set project $thing
-      }
-
-      set box [$project sandbox [Sandbox new \
-				     -interp [expr {$sandboxed?[interp create]:""}]]]
-      set sources [dict create]
-      foreach {type name} [$project sources] {
-	dict lappend sources $type $name
-      }
-
-
-      set nsFilters [list]
-      if {[info exists include] && $include ne ""} {
-	set nsFilters [list $include]
-      }
-      if {[info exists exclude] && $exclude ne ""} {
-	set nsFilters [list -not $exclude]
-      }
-
-
-      set provided_entities [list]
-      dict for {type instances} $sources {
-	lappend provided_entities {*}[:[current method]=$type $project $instances {*}$nsFilters]
-      }
-
-      if {$validate} {
-	#
-	# TODO: is_validated to later to become a derived/computed
-	# property ... for now, we just need to escape from setting
-	# validation-related info in non-validated projects!
-	#
-	$project is_validated $validate; # is_validated = 1
-
-	set present_entities [::nx::doc::filtered $provided_entities {[[:origin] eval {info exists :pdata}]}]
-	# TODO: the nspatterns should be consumed from the source
-	# specification and should not be hardcoded here ... review
-	# later ...
-	#puts stderr "NSF: [join [dict keys [$box get_registered_commands -exported -types @command]] \n]"
-	# ISSUE: -exported turns out to be a weak filter criterion, it
-	# excludes slot objects from being processed!
-	
-	#
-	# TODO: Add support for "generated" packages and their
-	# validation later on, i.e. a @package.validate() method.
-	#
-	
-	set generated_commands [dict merge \
-				    [$box get_registered_commands -types {
-				      @object 
-				      @class 
-				      @command
-				    }] \
-				    [$box get_registered_commands -types {
-				      @method
-				    }]]
-
-	#puts stderr generated_commands=$generated_commands
-	#puts stderr present_entities=$present_entities
+      set generated_commands  [dict filter $cmds script {k v} { 
+	dict with v { expr {$cmdtype in {@object @class @command} && !$dependency } } 
+      }]
+      
+      set generated_commands [dict merge $generated_commands [dict filter $cmds script {k v} { 
+	dict with v { expr {$cmdtype eq "@method" && !$dependency} } 
+      }]]
+      
+      
 	set map [dict create]
 	foreach pe $present_entities {
 	  if {[$pe pinfo exists bundle handle]} {
@@ -3143,11 +2713,19 @@
 	  dict unset generated_commands $fqn
 	  dict set map $fqn $pe
 	}
-	
-	# 2. generated entities (doc[no]->program[yes])
-	dict for {cmd info} $generated_commands {
-	  dict with info {
-	    if {$cmdtype ni [list @command @object @class @method]} continue;
+
+      #
+      # 2.) Generate entities for undocumented ("missing") program entities
+      #
+      dict for {cmd info} $generated_commands {
+	dict with info {
+	  if {$cmdtype ni [list @command @object @class @method]} continue;
+	  if {[info exists package] && [dict exists $pkgMap $package]} {
+	    set pkgObj [dict get $pkgMap $package]
+	    [:info class] containers push $pkgObj
+	    unset package
+	  }
+	  
 	    if {$cmdtype eq "@object" && [string match *::slot::* $cmd]} {
 	      if {[dict exists $info bundle objtype] && [dict get $info bundle objtype] eq "ensemble"} continue;
 	      set name [namespace tail $cmd]
@@ -3188,889 +2766,316 @@
 	      set entity [@ $cmdtype $cmd]
 	    }
 	    
-	    #puts stderr "SETTING missing PDATA $entity $cmd"
 	    $entity pdata [lappend info status missing]
 	    dict set map [$entity get_fqn_command_name] $entity
 	  }
-	}
       }
-      return $project
     }
+    
+    #
+    # The actual Validator mixin layer. The mixins trace the creation
+    # process of provided entities (and assign corresponding pdata, if
+    # present) and provide validation hooks for the various entity
+    # types.
+    #
 
-    :protected method process=@package {project pkgs} {
-      set box [$project sandbox]
-      $box permissive_pkgs [string tolower $pkgs]
-      set 1pass ""
-      foreach pkg $pkgs {
-	if {[catch {namespace eval :: [list package req $pkg]} _]} {
-	  error "Tcl package '$pkg' cannot be found."
+    Mixin create [current]::Entity {
+      :public method init args {
+	next
+	set prj [:current_project]
+	if {$prj ne ""} {
+	  set box [$prj sandbox]	  
+	  set cmdname [:get_fqn_command_name]
+	  if {[$box eval {info exists :registered_commands}] && \
+		  [$box eval [concat dict exists \${:registered_commands} $cmdname]]} {
+	    :pdata [$box eval [concat dict get \${:registered_commands} $cmdname]]
+	  }
 	}
-	append 1pass "package req $pkg\n"
+	[[current class] info parent] at_processed [current]
       }
 
-      #
-      # a) 1-pass: requiring the packages first will provide
-      # all dependencies (also those not to be documented).
-      #
-      $box do "::nx::doc::__trace_pkg; $1pass"
-
-      #
-      # b) 2-pass: [source] will re-evaluate the package scripts
-      # (note, [load]-based extension packages are not covered by this!)
-      #"
-      if {[$box eval {info exists :source}]} {
+      :public method validate {} {
 	#
-	# Note: Expects the XOTcl2 utilities to be in place and
-	# accessible by the [package req] mechanism, use e.g.:
-	# export TCLLIBPATH=". ./library/xotcl/library/lib"
+	# TODO: At some validate() spots, we still assume that the
+	# missing entities are processed by the validator (e.g., to
+	# mark container entities as a mismatch if a child entity is
+	# missing etc.) ... This needs to be relocated ...
 	#
-	package req xotcl::xodoc
-	namespace eval :: {namespace import -force ::xotcl::@}
-	
-	set docdb [XODoc new]
-	::@ set analyzerObj $docdb
-	foreach {pkg src} [$box eval {set :source}] {
-	  $docdb analyzeFile $src
-	}
-	
-	foreach m [namespace eval ::nx::doc::xodoc {namespace export}] {
-	  if {[::xotcl::Class info instances -closure ::xotcl::metadataAnalyzer::$m] ne ""} {
-	    ::xotcl::metadataAnalyzer::$m instmixin add ::nx::doc::xodoc::$m
+	if {[info exists :pdata] && \
+		[:pinfo get -default complete status] ne "missing"} {
+	  if {[[:origin] as_list] eq ""} {
+	    :pinfo propagate status mismatch
+	    :pinfo lappend validation "Provide a short, summarising description!"
 	  }
 	}
-	
-	::nx::doc::xodoc::MetadataToken eval [list set :analyzer $docdb]
-	set provided_entites [list]
-        #
-        # as we analyze file by file, there is only one FileToken to
-        # be molded into an @package
-        # 
-        set ft [::xotcl::metadataAnalyzer::FileToken allinstances]
-        if {[llength $ft] > 1} {
-          error "Too many xodoc file tokens processed. Expecting just one!"
-        }
-
-	$project @namespace "::xotcl"
-	::nx::doc::QualifierTag mixin add ::nx::doc::ContainerEntity::Resolvable
-	::nx::doc::ContainerEntity::Resolvable container $project
-
-	foreach {attr part_class} [$project part_attributes] {
-	  $part_class class mixin add ::nx::doc::ContainerEntity::Containable
-	  $part_class container $project
-	}
-
-        set partof $project
-        if {$ft ne ""} {
-          set pkg [$ft emit $project]
-          lappend provided_entities $pkg
-          set partof $pkg
-        }
-
-	foreach token [::xotcl::metadataAnalyzer::ObjToken allinstances] {
-	  lappend provided_entities [$token emit $partof]
-	}
-
-        return $provided_entities
+	next
       }
-    }
-      
-    :protected method process=package {project pkgs nsFilters:optional} {
-      set box [$project sandbox]
-      $box permissive_pkgs $pkgs
-      set 1pass ""
-      foreach pkg $pkgs {
-	if {[catch {package req $pkg} _]} {
-	  error "Tcl package '$pkg' cannot be found."
-	}
-	append 1pass "package req $pkg\n"
-      }
 
-      #
-      # a) 1-pass: requiring the packages first will provide
-      # all dependencies (also those not to be documented).
-      #
-      $box do "::nx::doc::__trace_pkg; $1pass"
-
-      #
-      # b) 2-pass: [source] will re-evaluate the package scripts
-      # (note, [load]-based extension packages are not covered by this!)
-      #"
-      if {[$box eval {info exists :source}]} {
-	foreach {pkg src} [$box eval {set :source}] {
-	  #
-	  # TODO: 2-pass [source]s should not trigger transitive [source]s. we
-	  # have flattened the relevant [source] hierarchy in the
-	  # 1-pass.
-	  #
-	  append 2pass \
-	      "::nx::doc::__cpackage push $pkg;\n" \
-	      "source $src;\n" \
-	      "::nx::doc::__cpackage pop;\n"
-	}
-	$box do "::nx::doc::__init; $2pass" 
-      }
-
-      #
-      # filter registered commands for includes/excludes 
-      #
-      if {[info exists nsFilters]} {
-	$box registered_commands [$box get_registered_commands $nsFilters]
-      }
-
-      # puts stderr REGISTERED_COMMANDS=[dict keys [$box registered_commands]]
-
-      
-      foreach {attr part_class} [$project part_attributes] {
-	$part_class class mixin add ::nx::doc::ContainerEntity::Containable
-	$part_class container $project
-      }
-
-      set deps_entities [list]
-      foreach dep [$box getCompanions [$box eval {set :deps}]] {
-	lappend deps_entities {*}[:readin $dep]
-      }
-      foreach de $deps_entities {
-	$de @stashed
-      }
-
-      set scripts [$box get_companions]
-      set provided_entities [list]
-
-      foreach script $scripts {
-	lappend provided_entities {*}[:readin $script] 
-      }
-      return $provided_entities
     }
 
-    :protected method process=source {project filepath} {;}
-
-    :protected method process=eval {project scripts} {
-      set box [$project sandbox]
-      #
-      # 1a) 1pass ... TODO: should tracing be enabled in this scenario? ...
-      #
-      foreach script $scripts {
-	$box do $script
-      }
-
-      #
-      # 2) 2pass ... 
-      # 
-      $box do [list ::nx::doc::__init]
-
-      foreach script $scripts {
-	$box do $script
-      }
-      #
-      # 3) documentation processing
-      #
-
-      # 3a) top-level processing
-      foreach script $scripts {
-	:readin $script
-      }
-
-      # 3b) initcmds, proc bodies ...
-
-      dict for {cmd info} [$box get_registered_commands] {
-	dict with info {
-	  #
-	  # TODO: for now, we assume objects beyond this point
-	  # ... relax later!
-	  #
-	  if {$cmdtype ni [list @object @class]} continue;
-	  if {[info exists docstring]} {
-	    lassign [:readin \
-			    -docstring \
-			    -tag $cmdtype \
-			    -name $cmd \
-			    -parsing_level 1 \
-			    $docstring] entity processed_entities
-	    unset docstring
-	  } else {
-	    set entity [@ $cmdtype $cmd]
+    Mixin create [current]::StructuredEntity -superclass [current]::Entity {
+      :public method validate {} {
+	next
+	dict for {s entities} [:owned_parts -where "!\${:@stashed}"] {
+	  foreach e $entities {
+	    if {![$e eval {info exists :@use}]} {
+	      $e [current method]
+	    }
 	  }
-	  :process=$cmdtype $project $entity
-	}
+	} 
       }
     }
-        
-    :public method readin {
-	-docstring:switch 
-	-tag
-	-name
-	-partof_entity:object,type=::nx::doc::StructuredEntity
-	{-parsing_level:integer 0}
-	script
-      } {
 
-      set blocks [:comment_blocks $script]
-      set first_block 1
-      set processed_entities [list]
-      foreach {line_offset block} $blocks {
-	array set arguments [list -initial_section context \
-				 -parsing_level $parsing_level]
 
-	if {$docstring} {
-	  if {[info exists partof_entity]} {
-	    set arguments(-partof_entity) $partof_entity
-	  }
-	  if {![info exists tag] || ![info exists name]} {
-	    error "In docstring mode, provide the tag and the name of
-	      a docstring-owning documentation entity object."
-	  }
-	  if {$first_block} {
-	    #
-	    # TODO: Note that the two "creation procedures" are not
-	    # idempotent; the relative one overwrites description
-	    # blocks of pre-exisiting entities, the freestanding @
-	    # does not ... fix later when reviewing these parts of the
-	    # program ...
-	    # 
-	    set docentity [expr {[info exists partof_entity]?\
-				     [$partof_entity $tag $name]:[@ $tag $name]}]
-	    set arguments(-partof_entity) $docentity
-	    if {$line_offset <= 1} {
-	      set arguments(-initial_section) description
-	      set arguments(-entity) $docentity
+    Mixin create [current]::@command -superclass [current]::StructuredEntity {
+      :public method validate {} {
+	if {[info exists :pdata] && \
+		[:pinfo get -default complete status] ne "missing"} {
+	  
+	  if {![info exists :@command]} {
+	    set params [list]
+	    set param_names [list]
+	    if {[info exists :@parameter]} {
+	      foreach p [:@parameter] {
+		set value [$p name]
+		lappend param_names $value
+		if {[$p eval {info exists :default}] || $value eq "args" } {
+		  set value "?$value?"
+		}
+		lappend params $value
+	      }
 	    }
+	    
+	    set ps [:pinfo get -default "" bundle parameter]
+	    dict for {actualparam paraminfo} $ps {
+	      if {$actualparam ni $param_names} {
+		set p [:@parameter $actualparam]
+		$p pdata [lappend paraminfo status missing]
+	      }
+	    }
+	  } 
+
+	  if {![:pinfo exists bundle parametersyntax]} {
+	    :pinfo set bundle parametersyntax $params
 	  }
+	  
+	  # TODO (Review!): [next] will cause the missing parameter
+	  # created to be validated and will have the appropriate
+	  # status propagated upstream!b
+	  next
 	}
-	
-	set args [array get arguments]
-	lappend args $block
-	# puts stderr "::nx::doc::CommentBlockParser process {*}$args"
-	#::nx::doc::Entity mixin add [current]::Entity
-	:apply
-	::nx::doc::CommentBlockParser process {*}$args
-	lappend processed_entities {*}[:revoke]
-	set first_block 0
       }
-      if {$docstring && [info exists arguments(-partof_entity)]} {
-	return [list $arguments(-partof_entity) $processed_entities]
-      } else {
-	return $processed_entities
-      }
     }
 
-    :public method analyze_line {line} {
-      set regex {^[\s#]*#+(.*)$}
-      if {[regexp -- $regex $line --> comment]} {
-	return [list 1 [string trimright $comment]]
-      } else {
-	return [list 0 $line]
-      }
-    }
+    Mixin create [current]::@object -superclass [current]::StructuredEntity
     
-    :public method comment_blocks {script} {
-      set lines [split $script \n]
-      set comment_blocks [list]
-      set was_comment 0
-      
-      set spec {
-	0,1	{
-	  set line_offset $line_counter; 
-	  set comment_block [list]; 
-	  lappend comment_block $text}
-	1,0	{
-	  lappend comment_blocks $line_offset $comment_block; 
-	  unset comment_block
-	}
-	1,1	{lappend comment_block $text}
-	0,0	{}
-      }
-      array set do $spec 
-      set line_counter -1
-      foreach line $lines {
-	incr line_counter
-	# foreach {is_comment text} [:analyze_line $line] break;
-	lassign [:analyze_line $line] is_comment text;
-	eval $do($was_comment,$is_comment)
-	set was_comment $is_comment
-      }
-      if {[info exists comment_block]} {
-	lappend comment_blocks $line_offset $comment_block
-      }
-      return $comment_blocks
-    }
-    
-    # TODO: how can I obtain some reuse here when later @class is
-    # distinguished from @object (dispatch along the inheritance
-    # hierarchy?)
-
-    :public method process=@command {project entity} {;}
-
-    :public method process=@class {project entity} {
-      set name [$entity name]
-      set box [$project sandbox]
-      # attributes
-      foreach slot [$box do [list $name info slot objects]] {
-	if {[$box do [list $slot eval {info exists :__initcmd}]]} {
+    Mixin create [current]::@class -superclass [current]::@object {
+      :public method validate {} {
+	next
+	#
+	# TODO: Certain metadata could also be valid in "missing"
+	# state, e.g., paramtersyntax? Re-arrange later ...
+	#
+	if {[info exists :pdata] &&
+	    [:pinfo get -default complete status] ne "missing"} {
 	  #
-	  # TODO: Here, we eagerly create doc entities, is this an issue?
-	  # Should we mark them for removal if not further processed?
-	  # This might be contradicting to the requirement of
-	  # identifying documented/undocumented program structures.
+	  # Note: Some metadata on classes cannot be retrieved from
+	  # within the tracers, as they might not be set local to the
+	  # class definition. Hence, we gather them at this point.
 	  #
-	  # There are two alternatives:
-	  # -> use a freestanding identity generator (preferred!)
-	  # -> mark the entity for deletion
-	  #
-	  # set id [$entity @${scope}-attribute [$box do [list $slot name]]]
-	 
-	  set scope [expr {[$box do [list $slot per-object]]?"class-object":"class"}]
-	  :readin \
-	      -partof_entity $entity \
-	      -docstring \
-	      -tag @${scope}-property \
-	      -name [$box do [list $slot name]] \
-	      -parsing_level 2 \
-	      [$box do [list $slot eval {set :__initcmd}]]
-
+	  set prj [:current_project]
+	  set box [$prj sandbox]
+	  set statement [list ::nsf::dispatch ${:name} \
+			     ::nsf::methods::class::info::objectparameter \
+			     parametersyntax]
+	  :pinfo set bundle parametersyntax [$box eval $statement]
 	}
       }
-
-      foreach methodName [$box do [list $name info methods \
-				       -methodtype scripted \
-				       -callprotection public]] {
-	:readin \
-	    -partof_entity $entity \
-	    -docstring \
-	    -tag @class-method \
-	    -name $methodName \
-	    -parsing_level 2  \
-	    [$box do [list ${name} info method body $methodName]]
-      }
-      
-      :process=@object $project $entity class
-      
     }
-    
-    #
-    # TODO: how to resolve to the current project's context. For now,
-    # we pass a parameter value, revisit this decision once we decide
-    # on a location for this behaviour.
-    #
-    :public method process=@object {project entity {scope ""}} {
-      set name [$entity name]
-      set box [$project sandbox]
-      # methods
 
-      foreach methodName [$box do [list ${name} {*}$scope info methods\
-				       -methodtype scripted \
-				       -callprotection public]] {
-	
-	set tag [join [list {*}[expr {$scope eq "class"?"class-object":""}] method] -]
-	# set id [$entity @$tag $methodName]
-	:readin \
-	    -partof_entity $entity \
-	    -docstring \
-	    -tag @$tag \
-	    -name $methodName \
-	    -parsing_level 2  \
-	    [$box do [list ${name} {*}$scope info method body $methodName]]
-      }
-    }
+    Mixin create [current]::ContainerEntity -superclass [current]::StructuredEntity
     
-  }
-}
-	  
-
-#
-# toplevel interface
-#   ::nx::doc::make all
-#   ::nx::doc::make doc
-#
-namespace eval ::nx::doc {
-
-  Object create make  {
-    
-    :method all {{-verbose:switch} {-class ::nx::Class}} {
-      foreach c [$class info instances -closure] {
-	if {$verbose} {puts "postprocess $c"}
-	::nx::doc::postprocessor process $c
+    Mixin create [current]::@package -superclass [current]::ContainerEntity {
+      :public method init args {
+	next
+	set prj [:current_project]
+	if {$prj ne ""} {
+	  set box [$prj sandbox]
+	  if {[$box eval [concat dict exists \${:registered_packages} ${:name}]]} {
+	    :pdata [$box eval [concat dict get \${:registered_packages} ${:name}]]
+	  }
+	}
       }
-    }
-       
-    :method write {content path} {
-      set fh [open $path w]
-      puts $fh $content
-      catch {close $fh}
-    }
 
-    :public method doc {
-      {-format html}
-      project:object,type=::nx::doc::@project
-      args
-    } {
-      package req nx::doc::$format
-      $format run -project $project {*}$args
-    }
-  }
-  
-  #
-  # This is a mixin class which adds comment block parsing
-  # capabilities to documentation entities (Entity, ...), once
-  # identified.
-  #
-  # It acts as the event source external to the modal parser (i.e.,
-  # the parsed entity). Expressing a modal behavioural design itself
-  # (around the line queue of a comment block), it produces certain
-  # events which are then signalled to the parsed entity.
-  #
-  Class create CommentBlockParser {
-
-    :property {parsing_level:integer 0}
-
-    :property {message ""}
-    :property {status:in "COMPLETED"} {
-
-      set :incremental 1
-      
-      set :statuscodes {
-	COMPLETED
-	INVALIDTAG
-	MISSINGPARTOF
-	STYLEVIOLATION
-	LEVELMISMATCH
-      }
-      
-      :public method type=in {name value} {
-	if {$value ni ${:statuscodes}} {
-	  error "Invalid statuscode '$code'."
+      :public method validate {} {
+	if {[info exists :pdata] && \
+		[:pinfo get -default complete status] ne "missing"} {
+	  set orig [:origin]
+	  if {[$orig eval {info exists :@version}]} {
+	    set docVersion [$orig @version]
+	    set actualVersion [:pinfo get version]
+	    if {$docVersion ne $actualVersion} {
+	      :pinfo propagate status mismatch
+	      :pinfo lappend validation "Package version mismatch: $docVersion vs. $actualVersion"
+	    }
+	  }
+	  next
 	}
-	return $value
       }
-      
-      :public method ? [list obj var value:in,slot=[current object]] {
-	return [expr {[:get $obj $var] eq $value}]
-      }
-
-      :public method is {obj var value} {
-	return [expr {$value in ${:statuscodes}}]
-      }
     }
 
-    :property processed_section  {
-      set :incremental 1
-      :public method assign {domain prop value} {
-	set current_entity [$domain current_entity]
-	set scope [expr {[$current_entity info is class]?"class mixin":"mixin"}]
-	#	puts stderr "Switching: [$current_entity {*}$scope] --> target $value"
-	if {[$domain eval [list info exists :$prop]] && [:get $domain $prop] in [$current_entity {*}$scope]} {
-	  $current_entity {*}$scope delete [:get $domain $prop]
+    Mixin create [current]::@method -superclass [current]::Entity {
+      :method init args {
+	next
+	set scope [expr {[${:part_attribute} scope] eq "class"?"class":"object"}]
+	set obj [:get_owning_object]
+	set method_name [:get_combined name]
+	set prj [:current_project]
+	if {$prj ne ""} {
+	  set box [$prj sandbox]	  
+	  set script "if {\[::nsf::object::exists $obj\]} {array set \"\" \[$obj eval {:__resolve_method_path \"$method_name\"}\]; ::nsf::dispatch \$(object) ::nsf::methods::${scope}::info::method handle \$(methodName)}"
+	  set cmdname [$box do $script]
+	  if {$cmdname ne "" && [$box eval [concat dict exists \${:registered_commands} $cmdname]]} {
+	    :pdata [$box eval [concat dict get \${:registered_commands} $cmdname]]
+	  }
 	}
-	$current_entity {*}$scope add [next [list $domain $prop $value]]
-      }
-    }
-    :property current_entity:object
-    
-    :public class method process {
-			      {-partof_entity ""}
-			      {-initial_section context}
-			      {-parsing_level 0}
-			      -entity
-			      block
-			    } {
 	
-	if {![info exists entity]} {
-	  set entity [Entity]
-	}
-      
-	set parser_obj [:new -current_entity $entity -parsing_level $parsing_level]
-	$parser_obj [current proc] \
-	    -partof_entity $partof_entity \
-	    -initial_section $initial_section \
-	    $block
-	return $parser_obj
       }
-    
-    :public forward has_next expr {${:idx} < [llength ${:comment_block}]}
-    :public method dequeue {} {
-      set r [lindex ${:comment_block} ${:idx}]
-      incr :idx
-      return $r
-    }
-    :public forward rewind incr :idx -1
-    :public forward fastforward set :idx {% llength ${:comment_block}}
 
-    :public method cancel {statuscode {msg ""}} {
-      :fastforward
-      :status $statuscode
-      :message $msg
-      uplevel 1 [list ::return -code error $statuscode]
-    }
-    #
-    # everything below assumes that the current class is an active mixin
-    # on an instance of an Entity subclass!
-    #
-
-    :public method process {
-      {-partof_entity ""}
-      {-initial_section context}
-      block
-    } {
-
-      set :comment_block $block
-      set :idx 0
-
-      :processed_section [$initial_section]
-
-      # TODO: currently, default values are not initialised for
-      # property slots defined in mixin classes; so do it manually
-      # for the time being.
-      ${:current_entity} current_comment_line_type ""
-
-      ${:current_entity} block_parser [current]      
-      ${:current_entity} eval [list set :partof_entity $partof_entity]
-      
-      set is_first_iteration 1
-#      set failure ""
-      
-      #
-      # Note: Within the while-loop, two object variables constantly
-      # change (as "wanted" side-effects): processed_section: reflects
-      # the currently processed comment section; see event=next()
-      # current_entity: reflects the currently documentation entity
-      # (once resolved); see context->event=parse@tag()
-      #
-      while {[:has_next]} {
-	set line [:dequeue]	
-	if {$is_first_iteration} {
-	  ${:current_entity} on_enter $line
-	  set is_first_iteration 0
-	}
-
-	if {[catch {
-	 # puts stderr "PROCESS ${:current_entity} event=process $line"
-	  ${:current_entity} event=process $line
-	} failure]} {
-	  if {![:status is $failure]} {
-	    ::return -code error -errorinfo $::errorInfo
+      :public method validate {} {
+	set partof [:get_owning_partof]
+	if {[info exists :pdata] &&
+	    [:pinfo get -default complete status] ne "missing"} {
+	  #
+	  # Note: Some information on methods cannot be retrieved from
+	  # within the tracers as they might not be set local to the
+	  # method definition. Hence, we gather them at this point. I
+	  # will review whether there is a more appropriate way of
+	  # dealing with this issue ...
+	  #
+	  set prj [:current_project]
+	  set box [$prj sandbox]
+	  set obj [$partof name]
+	  
+	  if {[:pinfo exists bundle handle]} {
+	    set handle [:pinfo get bundle handle]
+	    :pinfo set bundle redefine-protected [$box eval [list ::nsf::method::property $obj $handle redefine-protected]]
+	    :pinfo set bundle call-protected [$box eval [list ::nsf::method::property $obj $handle call-protected]]
 	  }
-	} 
+	  
+	  set params [list]
+	  set param_names [list]
+	  if {[info exists :@parameter]} {
+	    foreach p [:@parameter] {
+	      set value [$p name]
+	      lappend param_names $value
+	      if {[$p eval {info exists :default}] || $value eq "args" } {
+		set value "?$value?"
+	      }
+	      lappend params $value
+	    }
+	  }
+	  
+	  dict for {actualparam paraminfo} [:pinfo get -default "" bundle parameter] {
+	    if {$actualparam ni $param_names} {
+	      set p [:@parameter $actualparam]
+	      $p pdata [lappend paraminfo status missing]
+	    }
+	  }
+	  
+	  if {![:pinfo exists bundle parametersyntax]} {
+	    :pinfo set bundle parametersyntax $params
+	  }
+	  
+	  # Note: [next] will cause the missing parameter created to
+	  # be validated and will have the appropriate status
+	  # upstream!
+	  next
+	} else {
+	  $partof pinfo propagate status mismatch
+	}
       }
-      if {!$is_first_iteration} {
-	${:current_entity} on_exit $line
-      }
-
-      # ISSUE: In case of some sub-method definitions (namely "info
-      # mixin"), the sub-method entity object for "mixin" replaces the
-      # forward handlers of the mixin relation slot. So, any slot-like
-      # interactions such as delete() won't work anymore. We need to
-      # bypass it by using ::nsf::relation, for the time being. This
-      # is a clear con of the explicit naming of entity objects (or at
-      # least the current scheme)!
-
-      # if {[${:processed_section} info mixinof -scope object ${:current_entity}] ne ""} {
-      # 	${:current_entity} {*}$scope mixin delete ${:processed_section}
-      # }
-
-      set scope [expr {[${:current_entity} info is class]?"class":""}]
-      set mixins [${:current_entity} {*}$scope info mixin classes]
-      if {${:processed_section} in $mixins} {
-	set idx [lsearch -exact $mixins ${:processed_section}]
-	set mixins [lreplace $mixins $idx $idx]
-	::nsf::relation ${:current_entity} object-mixin $mixins
-      }
-                  
-    }; # CommentBlockParser->process()
-    
-  }
-  
-  Class create CommentBlockParsingState -superclass Class {
-    
-    :property next_comment_section
-    :property comment_line_transitions:required
-    
-  }
-  
-  Class create CommentSection {
-
-    :property block_parser:object,type=::nx::doc::CommentBlockParser
-    :property {current_comment_line_type ""}
-
-    set :line_types {
-      tag {regexp -- {^\s*@[^[:space:]@]+} $line}
-      text {regexp -- {^\s*([^[:space:]@]+|@[[:space:]@]+)} $line}
-      space {expr {$line eq {}}}
     }
 
-    :method get_transition {src_line_type tgt_line} {
-      set section [${:block_parser} processed_section]
-      array set transitions [$section comment_line_transitions]
-      # expected outcome
-      # 1. new state -> becomes current_comment_line
-      # 2. actions to be triggered from the transition
-      
-      foreach {line_type expression} [[current class] eval {set :line_types}] {
-	set line $tgt_line
-	if {[eval $expression]} {
-	  set tgt_line_type $line_type
-	  break
+    Mixin create [current]::@param -superclass [current]::Entity {
+      :public method init args {
+	next
+	if {${:name} eq "__out__"} {
+	  if {[${:partof} pinfo exists bundle returns]} {
+	    :pdata [list bundle [list spec [${:partof} pinfo get bundle returns]]]
+	  }
+	} elseif {[${:partof} pinfo exists bundle parameter ${:name}]} {
+	  lassign [${:partof} pinfo get bundle parameter ${:name}] spec default
+	  :pdata [list bundle [list spec $spec default $default]]
 	}
       }
 
-      if {![info exists tgt_line_type]} {
-	error "Could not resolve the type of line '$line'"
-      }
+      :public method validate {} {
+	#
+	# TODO: For now, we escape from @param validaton on command
+	# parameters. There is no equivalent to [info parameter]
+	# available, so we would need to cook a substitute based on
+	# the parametersyntax. Review later ...
+	#
+	if {${:name} eq "__out__" && \
+		[${:partof} info has type ::nx::doc::@command]} return;
 
-      if {![info exists transitions(${src_line_type}->${tgt_line_type})]} {
-	set msg "Style violation in a [namespace tail [:info class]] section:\n"
-	if {$src_line_type eq ""} {
-	  append msg "Invalid first line ('${tgt_line_type}')"
+	#
+	# Here, we escape from any parameter verification for
+	# parameters on forwards & alias, as there is no basis for
+	# comparison!
+	#
+	if {[${:partof} info has type ::nx::doc::@method] && \
+		[${:partof} pinfo get bundle type] in [list forward alias]} {
+	  dict set :pdata status ""
+	  return;
+	}
+
+	if {[info exists :pdata] && \
+		[:pinfo get -default complete status] ne "missing"} {
+	  
+	  # valid for both object and method parameters
+	  set pspec [:pinfo get -default "" bundle spec]
+	  if {[info exists :spec] && \
+		  ${:spec} ne $pspec} {
+	    :pinfo propagate status mismatch 
+	    :pinfo lappend validation "Specification mismatch. Expected: \
+						'${:spec}' Got: '$pspec'."
+	  }
+	  next
 	} else {
-	  append msg "A ${src_line_type} line is followed by a ${tgt_line_type} line"
+	  ${:partof} pinfo propagate status mismatch 
 	}
-	${:block_parser} cancel STYLEVIOLATION $msg
-	# [StyleViolation new -message $msg] throw
       }
-      return [list $tgt_line_type $transitions(${src_line_type}->${tgt_line_type})]
     }
 
-    # the actual events to be signalled to and sensed within the
-    # super-states and sub-states
+    #
+    # mixin layer interface
+    #
 
-    :public method event=process {line} {
-      lassign [:get_transition ${:current_comment_line_type} $line] \
-	  :current_comment_line_type actions
-      foreach action $actions {
-	:event=$action $line
-      }
+    :public class method apply {} {
+      unset -nocomplain :processed_entities
+      next
     }
 
-    :public forward event=parse %self {% subst {parse@${:current_comment_line_type}}} 
-    :method event=next {line} {
-      set next_section [[${:block_parser} processed_section] next_comment_section]
-      :on_exit $line
-      
-      ${:block_parser} rewind
-      :current_comment_line_type ""
-    
-      ${:block_parser} processed_section [$next_section]
-      :on_enter $line
-    }
-
-   
-    # realise the sub-state (a variant of METHOD-FOR-STATES) and their
-    # specific event handling
-    # set :lineproc {{tag args} {return [concat {*}$args]}}
-    # set :lineproc {{tag args} {puts stderr LINE=[list $tag {*}$args]; return [list $tag {*}$args]}}
-    set :lineproc {{tag args} {return [list $tag [expr {$args eq ""?$args:[list $args]}]]}}
-    :method parse@tag {line} {
-      lassign [apply [[current class] eval {set :lineproc}] {*}$line] tag line
-      #set line [lassign [apply [[current class] eval {set :lineproc}] {*}$line] tag]
-      if {[:info lookup methods -source application $tag] eq ""} {
-	set msg "The tag '$tag' is not supported for the entity type '[namespace tail [:info class]]"
-	${:block_parser} cancel INVALIDTAG $msg
+    :public class method revoke {} {
+      #
+      # TODO: reset current_project here?
+      #
+      next
+      if {[info exists :processed_entities]} {
+	return [dict keys ${:processed_entities}]
       }
-      #:$tag [lrange $line 1 end]
-      #:$tag {*}[expr {$line eq ""?$line:[list $line]}]
-      #:$tag $line
-      :$tag {*}$line
     }
-
-    :method parse@text {line} {
-      #puts stderr "ADDLINE([current]) :@doc add $line end"
-      :@doc add $line end
-    }
-    :method parse@space {line} {;}
     
-    #
-    # so far, we only need enter and exit handlers at the level of the
-    # superstates: context, description, part
-    #
-    :public method on_enter {line} {;}
-    :public method on_exit {line} {;}
+    :public class method at_processed {entity} {
+      dict set :processed_entities $entity _
+    }
   }
-
-  # NOTE: add these transitions for supporting multiple text lines for
-  # the context element
-  #	tag->text	parse
-  #	text->text	parse
-  #	text->space	""
-  
-  
-  CommentBlockParsingState create context -superclass CommentSection \
-      -next_comment_section description \
-      -comment_line_transitions {
-	->tag		parse
-	tag->space	""
-	space->space	""
-	space->text	next
-	space->tag	next
-      } {
-	
-	:method resolve_partof_entity {tag name} {
-	  # a) unqualified: attr1
-	  # b) qualified: Bar#attr1
-	  if {[regexp -- {([^\s#]*)#([^\s#]*)} $name _ qualifier nq_name]} {
-	    # TODO: Currently, I only foresee @object and @command as
-	    # possible qualifiers; however, this should be fixed asap, as
-	    # soon as the variety of entities has been decided upon!
-	    foreach entity_type {@class @command @object} {
-	      set partof_entity [$entity_type id $qualifier]
-	      # TODO: Also, we expect the qualifier to resolve against an
-	      # already existing entity object? Is this intended?
-	      if {[::nsf::is object $partof_entity]} {
-		return [list $nq_name $partof_entity]
-	      }
-	    }
-	    return [list $nq_name ${:partof_entity}]
-	  } else {      
-	    return [list $name ${:partof_entity}]
-	  }
-	}
-
-	set :lineproc {{tag name args} {return [list $tag $name $args]}}
-	:method parse@tag {line} {
-	  lassign [apply [[current class] eval {set :lineproc}] {*}$line] axes names args
-	  set entity ${:partof_entity}
-	  set axes [split [string trimleft $axes @] .]
-
-	  # 1) get the parsing level from the comment block parser
-	  set start_idx [lindex [lsearch -all -not -exact $axes ""] 0]
+}
 	  
-	  set pl [${:block_parser} parsing_level]
-	  if {$pl != $start_idx} {
-	    ${:block_parser} cancel LEVELMISMATCH "Parsing level mismatch: Tag is meant for level '$start_idx', we are at '$pl'."
-	  }
-	  
-	  # 2) stash away a number of empty axes according to the parsing level 
-	  set axes [lrange $axes $pl end]
-	  
-	  lassign [::nx::doc::Tag normalise $axes $names] err res
-	  if {$err} {
-	     ${:block_parser} cancel STYLEVIOLATION $res
-	  }
+namespace eval ::nx::doc {
 
-	  lassign $res tagpath names
-	  
-	  set leaf(axis) [lindex $tagpath end]
-	  set tagpath [lrange $tagpath 0 end-1]
-	  set leaf(name) [lindex $names end]
-	  set names [lrange $names 0 end-1]
-	  
-	  lassign [::nx::doc::Tag find -strict $tagpath $names $entity] err res
-	  if {$err} {
-	    ${:block_parser} cancel INVALIDTAG $res
-	  }
-	  
-	  set entity $res
-	  
-	  if {$entity eq ""} {
-	    set cmd [info commands @$leaf(axis)]
-	   
-	    # TODO interp-aliasing objects under different command names
-	    # is currently not transparent to some ::nsf::* helpers,
-	    # such as ::nsf::object::exists. Should this be changed?
-	    #
-	    if {$cmd ne ""} {
-	      set cmd [namespace origin $cmd]
-	      set target [interp alias {} $cmd]
-	      if {$target ne ""} {
-		set cmd $target
-	      }
-	    }
-	    
-	    if {$cmd eq "" || ![::nsf::object::exists $cmd] || \
-		    ![$cmd info has type Tag]} {
-	      
-	      ${:block_parser} cancel INVALIDTAG "The entity type '@$leaf(axis)' is not available."
-	    }
-
-	    # VERIFY! Still an issue? TODO: @object-method raises some
-	    # issues (at least when processed without a resolved
-	    # context = its partof entity).  It is not an entity type,
-	    # because it merely is a "scoped" @method. It won't
-	    # resolve then as a proper instance of Tag, hence we
-	    # observe an InvalidTag exception. For now, we just ignore
-	    # and bypass this issue by allowing InvalidTag exceptions
-	    # in analyze()
-
-	    set entity [@$leaf(axis) new -name $leaf(name) {*}$args]
-	  } else {
-	    if {[$entity info lookup methods -source application @$leaf(axis)] eq ""} {
-	      ${:block_parser} cancel INVALIDTAG \
-		  "The tag '$leaf(axis)' is not supported for the entity type '[namespace tail [$entity info class]]'"
-	    }
-	    set entity [$entity @$leaf(axis) [list $leaf(name) {*}$args]]
-	  }
-	  
-	  ${:block_parser} current_entity $entity
-	  ${:block_parser} processed_section [current class]
-	  $entity current_comment_line_type ${:current_comment_line_type}
-	  $entity block_parser ${:block_parser}
-	}
-	
-	# :method parse@text {line} { next }
-	# :method parse@space {line} { next }
-	
-      }
-  
-  CommentBlockParsingState create description -superclass CommentSection \
-      -next_comment_section part \
-      -comment_line_transitions {
-	->text		parse
-	->tag		next
-	text->text	parse
-	text->space	parse
-	space->text	parse
-	space->space	parse
-	space->tag	next
-    } {
-      
-      :public method on_enter {line} {
-	unset -nocomplain :@doc
-	next
-      }
-
-      # tag lines are not allowed in description blocks!
-      # :method parse@tag {line} {;}
-      :method parse@space {line} {
-	:@doc add "" end
-	next
-      }
-      
-    }
-
-  CommentBlockParsingState create part -superclass CommentSection  \
-      -next_comment_section part \
-      -comment_line_transitions {
-	->tag		parse
-	tag->text	parse
-	text->text	parse
-	text->tag	next
-	text->space	""
-	space->space	""
-	tag->space	""
-	space->tag	next
-	tag->tag	next
-      } {
-	# realise the parse events specific to the substates of description
-	:public method on_enter {line} {
-#	  puts stderr "ENTERING part $line, current section [${:block_parser} processed_section]"
-	  unset -nocomplain :current_part
-	  next
-	}
-	:method parse@tag {line} {
-	  set r [next]
-#	  puts stderr GOT=$r
-	  if {[::nsf::object::exists $r] && [$r info has type ::nx::doc::Entity]} {
-	    set :current_part $r
-	  }
-	  return $r
-	}
-	:method parse@text {line} {
-	  if {[info exists :current_part]} {
-	    ${:current_part} @doc add $line end
-	  } else {
-	    :event=next $line
-	  }
-	}
-	# :method parse@space {line} {;}
-      }
-
   ::nsf::proc mkIndex {{-documentAll:switch 0} {-indexfiles:0..* ""} {-outdir "[pwd]"} args} {
 
     if {![llength $args]} {
@@ -4122,6 +3127,4 @@
     puts -nonewline $fid $index
     close $fid
   }  
-}
-
-# puts stderr "Doc Tools loaded: [info command ::nx::doc::*]"
\ No newline at end of file
+}
\ No newline at end of file