nsf.nxd

Accomplishments: - Completed a first version of the sandboxed (partial) evaluation of Tcl source artifacts (packages, script files, C extensions) based on a dedicated child/slave interp environment: see ::nx::doc::Sandbox; the test suite and the test documentation builts run on it. - Based on this infrastructure, we can now generate a snapshot of a program's structure to be documented (and contrast it to the explicitly documented structure). - Added simplistic css sprites for visualising the doc entity status (extra, missing, mismatch, complete); see also library/lib/doc-assets/status.svg and library/lib/doc-assets/status.png - The entity status is printed optionally along with the print name of an entity - Added switch-like parts to represent properties of doc entities: @deprecated, @stashed, @c-implemented, @syshook. The implementation and use of ::nx::doc::SwitchAttribute should be reviewed after having figured out how to proceed using "switching" objparams. - I provide a multi-property dispatcher as doc-syntactic sugar and for mere convenience: @property

Various:

- Corrected some div-boxing mess in the templates

- Added a filtered helper to process entity collections

- Made the mixin layer infrastructure more symmetric (a revoke operation).

- Added tracers for ::nsf::method and ::nsf::alias (remains to be completed)

- Renamed ::nx::doc to ::nx::processor and turned it into another

mixin layer to trace the doc entity creation in e.g. readin()

- Companion (*.nxd) files: Revised the handling of companion

files. Temporarily moved generic/nsf.nxd in the top-level

directory. We need to find a permanent place as its location is

currently derived from the location of the shared extension. A

candidate is doc/ but this is not linked to the shared extension

location at all.

- processor.readin() now returns a collection of entities created

during its execution.

- Improved robustedness and orthogonality: destroy hooks; the

tag-dispatcher can now handle empty comment lines; when placing NSF

object tracer, we now use the freshly added introspection of an

object system's method aliases.

- Switch to print_name() for rendering entity names for the search box - Fixed the @parameter generation in method.html.tmpl - @glossary: Support for referencing glossary entries with certain formatting annotations: @gls (minor letters only), @Gls (title), @glspl (plural), @Glspl (title plural), ... Added explicit acronym rendering (long and short forms): @acrfirst, @acr; fixing an id-generation issue for @glossary entities - Completed the first round of amending nx.nxd with @glossary entries and references. - I got rid of curly braces ("{", "}") as marker symbols ("{{...}}", "{{{ ... }}}") for formatting fragments of comment blocks. They proofed sufficiently hairy due to their heavily loaded meaning for the Tcl parser (the unclosed brace issue in Tcl comment blocks, the list-like processing in our comment block parser, ...). Instead, I introduced <<...>> for link-like elements (anchors, glossary references) and MediaWiki-like '''...''' blockmarkers for code listings. Thanks to Victor Guerra for reviewing and discussing this concrete-syntactic design decision. - Increased the robustness of line-by-line parsing for comment blocks. Within the comment block parser, we operate on comment lines as Tcl lists (lindex, lassign, ...). While convenient from a processing perspective, this risks limiting the degrees of freedom when writing comments (e.g., using tabs and spaces to indent inline, grouping words to form lists of lists, ...). By leveraging "args" argument processing through [apply] for line preprocessing, we balance the two requirements. - Verified that @use works between objects and methods. - Some cleanup in the mixin layer code - Resolve interp-alias chains to entity class objects explicitly - Adjusting the Container/Containable mechanism to apply only to part classes relevant to particular container entities. - Fixing support for package rendering as top-level entities (e.g., in the leftbar menu) - Providing the project object to all entities subject to template processing. - Declaring some forwarders public explicitly (to reflect recent changes in the reach of default call protection)

- Minor revision of template files (to unify the naming of markup labels) - Removed occurrences of old [:let] - Use href() helper method to generate fragments of per-document ("local") anchor names - Introduced more pretty_name and pretty_plurals for part attributes - Make filename generation aware of the property of being a part or partof entity! - Revised the documentation of [::nsf::current] slightly - Adding setter ([:!let]) and getter ([:!get]) to the templating language, both being aware of @use chains. - Refactored the resolution behaviour for part levels, relative to a given entity, into a helper StructuredEntity->owned_parts(). Based on this helper, the navigation structures can be rendered on common grounds (e.g., drop-down search box, menus in th eleft bar) - Adding the attributes "pretty_name" and "pretty_plural" to part attribute slots (used for rendering section names in the nav menu etc.). - Adding a helper method href() to render the href attribute values of entity anchors (links, menu items, ...) - Unified the rendering of the selection data used by the drop-down box for the various entity_types, again, using the owned_parts() helper - Refactored the generation of navigation menu in the left bar into a proper template: leftbar.html.tmpl - Reflect recent naming changes (e.g., predefined.tcl -> nsf.tcl) - Adding support for documentation inheritance; first, fixed @command support for it - Refactored the upward resolution of partof entities into a central and shared facility (Entity->get_upward_path()) - Adjusting for changes in introspection interface (info.callable() -> info.lookup()) - Adding a first aliasing (@use) mechanism. Remains to be tested properly, though it works sufficiently for the known use cases. - Adding some safety checks to Tag->find() - Refactoring context->parse@tag to use the Tag->find() helper (now shared between tag creation and link resolution) - Tag path normalisation (expanding shortcuts, balanced list check, ...) went into Tag->normalise(). - Changed the [:link ...] mechansism ({{@someTag ...}}) to operate on the new tag notation. Added support for sub-method and sub-command link rendering (looks sufficient for the moment). - Changed the existing *.nxd companions to match these notational modifications.

- renamed/removed remaining ::nsf::commands with capitalized names: parametersFromSlots ==> parametersFromSlots unsetUnknownArgs ==> __unset_unknown_args infoError removed - renamed predefined.tcl into nsf.tcl - remaining cmds in nsf (except __*) containing "_": ::nsf::provide_method, ::nsf::require_method