From 2cf0ef0b6cfc9161cf09611f999b7497a911616f Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 30 Dec 2023 04:04:58 +1100 Subject: [PATCH] remove src/docgen files --- src/docgen/punk_cap-0.1.0.tm.man | 140 ------------------ ..._bootsupport_modules_punk_cap-0.1.0.tm.man | 23 --- ...lates_modules_template_module-0.0.1.tm.man | 40 ----- 3 files changed, 203 deletions(-) delete mode 100644 src/docgen/punk_cap-0.1.0.tm.man delete mode 100644 src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man delete mode 100644 src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man diff --git a/src/docgen/punk_cap-0.1.0.tm.man b/src/docgen/punk_cap-0.1.0.tm.man deleted file mode 100644 index 8d2e71bd..00000000 --- a/src/docgen/punk_cap-0.1.0.tm.man +++ /dev/null @@ -1,140 +0,0 @@ -[comment {--- punk::docgen generated from inline doctools comments ---}] -[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}] -[comment {--- punk::docgen overwrites this file ---}] -[manpage_begin punk::cap 0 0.1.0] -[copyright "2023 JMNoble - BSD licensed"] -[titledesc {capability provider and handler plugin system}] -[moddesc {punk capabilities plugin system}] -[require punk::cap] -[description] -[section Overview] -[para]punk::cap provides management of named capabilities and the provider packages and handler packages that implement a pluggable capability. -[subsection Concepts] -[para]A [term capability] may be something like providing a folder of files, or just a data dictionary, and/or an API - -[para][term {capability handler}] - a package/namespace which may provide validation and standardised ways of looking up provider data - registered (or not) using register_capabilityname - -[para][term {capability provider}] - a package which registers as providing one or more capablities. -[para]registered using register_package -the capabilitylist is a list of 2-element lists where the first element is the capabilityname and the second element is a (possibly empty) dict of data relevant to that capability -A capabilityname may appear multiple times. ie a package may register that it provides the capability with multiple datasets. -[section API] -[subsection {Namespace punk::cap::class}] -[para] class definitions -[list_begin itemized] [comment {- punk::cap::class groupings -}] - [item] - [para] [emph {handler_classes}] - [list_begin enumerated] -[enum] [emph {CLASS interface_caphandler.registry}] -[list_begin definitions] -[call class::[class interface_caphandler.registry] [method pkg_register] [arg pkg] [arg capname] [arg capdict] [arg fullcapabilitylist]] -handler may override and return 0 (indicating don't register)e.g if pkg capdict data wasn't valid -overridden handler must be able to handle multiple calls for same pkg - but it may return 1 or 0 as it wishes. -[call class::[class interface_caphandler.registry] [method pkg_unregister] [arg pkg]] -[list_end] -[enum] [emph {CLASS interface_caphandler.sysapi}] -[list_begin definitions] -[list_end] - [list_end] [comment {- end enumeration handler classes -}] - [item] - [para] [emph {provider_classes}] - [list_begin enumerated] - [enum] [emph {CLASS interface_cappprovider.registration}] - Your provider package will need to instantiate this object under a sub-namespace called [namespace capsystem] within your package namespace. - [para]If your package namespace is mypackages::providerpkg then the object command would be at mypackages::providerpkg::capsystem::capprovider.registration - [para]Example code for your provider package to evaluate within its namespace: - [example { -namespace eval capsystem { - if {[info commands capprovider.registration] eq ""} { - punk::cap::class::interface_capprovider.registration create capprovider.registration - oo::objdefine capprovider.registration { - method get_declarations {} { - set decls [list] - lappend decls [list punk.templates {relpath ../templates}] - lappend decls [list another_capability_name {somekey blah key2 etc}] - return $decls - } - } - } -} -}] -[para] The above example declares that your package can be registered as a provider for the capabilities named 'punk.templates' and 'another_capability_name' - [list_begin definitions] -[call class::[class interface_capprovider.registration] [method get_declarations]] -[para] This method must be overridden by your provider using oo::objdefine cappprovider.registration as in the example above. - There must be at least one 2-element list in the result for the provider to be registerable. -[para]The first element of the list is the capabilityname - which can be custom to your provider/handler packages - or a well-known name that other authors may use/implement. -[para]The second element is a dictionary of keys specific to the capability being implemented. It may be empty if the any potential capability handlers for the named capability don't require registration data. - [list_end] - [enum] [emph {CLASS interface_capprovider.provider}] - [para] Your provider package will need to instantiate this directly under it's own namespace with the command name of [emph {provider}] - [example { - namespace eval mypackages::providerpkg { - punk::cap::class::interface_capprovider.provider create provider mypackages::providerpkg - } - }] - [list_begin definitions] -[call class::[class interface_capprovider.provider] [method constructor] [arg providerpkg]] -[comment {- -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---}] -[call class::[class interface_capprovider.provider] [method register] [opt capabilityname_glob]] - -[para]This is the mechanism by which a user of your provider package will register your package as a provider of the capability named. - -[para]A user of your provider may elect to register all your declared capabilities: -[example { - package require mypackages::providerpkg - mypackages::providerpkg::provider register * -}] -[para] Or a specific capability may be registered: -[example { - package require mypackages::providerpkg - mypackages::providerpkg::provider register another_capability_name -}] - -[comment {- -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---}] -[call class::[class interface_capprovider.provider] [method capabilities]] -[para] return a list of capabilities supported by this provider package - [list_end] [comment {- end class definitions -}] - [list_end] [comment {- end enumeration provider_classes }] -[list_end] [comment {- end itemized list punk::cap::class groupings -}] -[subsection {Namespace punk::cap}] -[para] Main punk::cap API for client programs interested in using capability handler packages and associated (registered) provider packages -[list_begin definitions] - [call [fun capability_exists] [arg capname]] - Return a boolean indicating if the named capability exists (0|1) - [call [fun capability_has_handler] [arg capname]] -Return a boolean indicating if the named capability has a handler package installed (0|1) - [call [fun capability_get_handler] [arg capname]] -Return the base namespace of the active handler package for the named capability. -[para] The base namespace for a handler will always be the package name, but prefixed with :: -[list_end] [comment {- end definitions for namespace punk::cap -}] -[subsection {Namespace punk::cap::advanced}] -[para] punk::cap::advanced API. Functions here are generally not the preferred way to interact with punk::cap. -[para] In some cases they may allow interaction in less safe ways or may allow use of features that are unavailable in the base namespace. -[para] Some functions are here because they are only marginally or rarely useful, and they are here to keep the base API simple. -[list_begin definitions] - [call advanced::[fun promote_provider] [arg pkg]] -[para]Move the named provider package to the preferred end of the list (tail). -[para]The active handler may or may not utilise this for preferencing. See documentation for the specific handler package to confirm. -[para] -[para] promote/demote doesn't always make a lot of sense .. should preferably be configurable per capapbility for multicap provider pkgs -[para]The idea is to provide a crude way to preference/depreference packages independently of order the packages were loaded -e.g a caller or cap-handler can ascribe some meaning to the order of the 'providers' key returned from punk::cap::capabilities -[para]The order of providers will be the order the packages were loaded & registered -[para]the naming: "promote vs demote" operates on a latest-package-in-list has higher preference assumption (matching last pkg loaded) -[para]Each capability handler could and should implement specific preferencing methods within its own API if finer control needed. -In some cases the preference/loading order may be inapplicable/irrelevant to a particular capability anyway. -[para]As this is just a basic mechanism, which can't support independent per-cap preferencing for multi-cap packages - - it only allows putting the pkgs to the head or tail of the lists. -[para]Whether particular caps or users of caps do anything with this ordering is dependent on the cap-handler and/or calling code. - [call advanced::[fun demote_provider] [arg pkg]] -[para]Move the named provider package to the preferred end of the list (tail). -[para]The active handler may or may not utilise this for preferencing. See documentation for the specific handler package to confirm. -[list_end] -[section Internal] -[subsection {Namespace punk::cap::capsystem}] -[para] Internal functions used to communicate between punk::cap and capability handlers -[list_begin definitions] -[list_end] -[manpage_end] diff --git a/src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man b/src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man deleted file mode 100644 index e987243b..00000000 --- a/src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man +++ /dev/null @@ -1,23 +0,0 @@ -[comment {--- punk::docgen generated from inline doctools comments ---}] -[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}] -[comment {--- punk::docgen overwrites this file ---}] -[manpage_begin punk::cap 0 0.1.0] -[copyright "2023 JMNoble - BSD licensed"] -[titledesc {Module API}] -[moddesc {punk capabilities plugin system}] -[require punk::cap] -[description] -[list_begin definitions] -[call [class interface_caphandler.registry] [method pkg_register] [arg pkg] [arg capname] [arg capdict] [arg fullcapabilitylist]] -handler may override and return 0 (indicating don't register)e.g if pkg capdict data wasn't valid -overridden handler must be able to handle multiple calls for same pkg - but it may return 1 or 0 as it wishes. -[call [class interface_caphandler.registry] [method pkg_unregister] [arg pkg]] -[call [class interface_capprovider.registration] [method pkg_unregister] [arg pkg]] -[call [class interface_capprovider.provider] [method register] [opt capabilityname_glob]] -[call [class interface_capprovider.provider] [method capabilities]] - [call [fun exists] [arg capname]] - Return a boolean indicating if the named capability exists (0|1) - [call [fun has_handler] [arg capname]] - Return a boolean indicating if the named capability has a handler package installed (0|1) -[list_end] -[manpage_end] diff --git a/src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man b/src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man deleted file mode 100644 index 725f05a9..00000000 --- a/src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man +++ /dev/null @@ -1,40 +0,0 @@ -[comment {--- punk::docgen generated from inline doctools comments ---}] -[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}] -[comment {--- punk::docgen overwrites this file ---}] -[manpage_begin %pkg% 0 999999.0a1.0] -[copyright "%year%"] -[titledesc {Module API}] -[moddesc {-}] -[require %pkg%] -[description] - ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ -[section Overview] -[para] overview of %pkg% -[subsection Concepts] -[para] - -[subsection dependencies] -[para] packages used by %pkg% -[list_begin itemized] -[item] [package Tcl 8.6] -[list_end] -[section API] -[subsection {Namespace %pkg%::class}] -[para] class definitions -[list_begin enumerated] -[enum] [emph {CLASS interface_sample1}] -[list_begin definitions] -[call class::[class interface_sample1] [method test] [arg arg1]] -[para] test method -[list_end] [comment {-- end definitions interface_sample1}] -[list_end] [comment {--- end class enumeration ---}] -[subsection {Namespace %pkg%}] -[para] Core API functions for %pkg% -[list_begin definitions] -[subsection {Namespace %pkg%::lib}] -[para] Secondary functions that are part of the API -[list_begin definitions] -[list_end] [comment {--- end definitions namespace %pkg%::lib ---}] -[section Internal] -[subsection {Namespace %pkg%::system}] -[para] Internal functions that are not part of the API -[manpage_end]