jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

remove src/docgen files

master
Julian Noble 9 months ago
parent
f806cf376a
commit
2cf0ef0b6c
3 changed files with 0 additions and 203 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 140
      src/docgen/punk_cap-0.1.0.tm.man
  2. 23
      src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man
  3. 40
      src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man

140
src/docgen/punk_cap-0.1.0.tm.man
Unescape View File

@ -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]

23
src/docgen/punk_mix_templates_layouts_project_src_bootsupport_modules_punk_cap-0.1.0.tm.man
Unescape View File

@ -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]

40
src/docgen/punk_mix_templates_modules_template_module-0.0.1.tm.man
Unescape View File

@ -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]
Write Preview
Loading…
Cancel
Save