remove src/docgen files

11 months ago · 2cf0ef0b6c
3 changed files with 0 additions and 203 deletions
--- a/src/docgen/punk_cap-0.1.0.tm.man
+++ b/src/docgen/punk_cap-0.1.0.tm.man
@ -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 <capname> <capnamespace>
 [para][term {capability provider}] - a package which registers as providing one or more capablities.
 [para]registered using register_package <pkg> <capabilitylist>
 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 <capname>
 [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]
--- 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
@ -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]
--- 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
@ -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]