2
Newly introduced with critcl version 3 is support for TEApot
5
[para] While, from the package developer's perspective, some meta data
6
support was already present in critcl v2, through the command
8
[cmd ::critcl::license], this was only used to generate and place a
9
file [file license.txt] into the built package.
11
[para] Now critcl supports the declaration of arbitrary meta data,
12
which will be placed into a file [file teapot.txt] in a format
13
suitable for use by the
14
[uri {http://docs.activestate.com/activetcl/8.5/tpm/toc.html} {TEApot tools}].
17
[list_begin definitions]
18
[comment ---------------------------------------------------------------------]
19
[call [cmd ::critcl::license] [arg author] [opt [arg text]...]]
21
This command provides information about the author of the package, and
24
[para] If no [arg text] is present the command expects to find a file
25
[file license.terms] in the same directory as the [file .critcl] file
26
and reads the license from that. Otherwise the license is the joined
29
[para] This information, the license, is ignored in mode "compile &
30
run", only mode "generate package" uses it. In that case the
31
information is written to a file [file license.terms], a sibling to
32
the [file pkgIndex.tcl] file in the directory hierarchy of the
35
[para] This information is additionally placed into the meta data file
36
[file teapot.txt], under the keys [term as::author] and [term license].
38
[para] The data specified by this command has priority over any
39
information specified through the generic API [cmd ::critcl::meta].
41
[comment ---------------------------------------------------------------------]
42
[call [cmd ::critcl::summary] [arg text]]
44
Declares a short (one line is recommended) description of the package.
46
[para] This information is ignored in mode "compile & run", only mode
47
"generate package" uses it. In that case the information is placed
48
into the meta data file [file teapot.txt], under the key [term summary].
50
[para] The data specified by this command has priority over any
51
information specified through the generic API [cmd ::critcl::meta].
53
[comment ---------------------------------------------------------------------]
54
[call [cmd ::critcl::description] [arg text]]
56
Declares a longer description of the package.
58
[para] This information is ignored in mode "compile & run", only mode
59
"generate package" uses it. In that case the information is placed
60
into the meta data file [file teapot.txt], under the key [term description].
62
[para] The data specified by this command has priority over any
63
information specified through the generic API [cmd ::critcl::meta].
65
[comment ---------------------------------------------------------------------]
66
[call [cmd ::critcl::subject] [opt [arg key]...]]
68
Declares one or more keywords and key-phrases describing the package,
71
[para] Multiple calls of this command accumulate keywords and phrases.
73
[para] This information is ignored in mode "compile & run", only mode
74
"generate package" uses it. In that case the information is placed
75
into the meta data file [file teapot.txt], under the key [term subject].
77
[para] The data specified by this command has priority over any
78
information specified through the generic API [cmd ::critcl::meta].
80
[comment ---------------------------------------------------------------------]
81
[call [cmd ::critcl::meta] [arg key] [opt [arg word]...]]
83
This command is for the declaration of arbitrary meta data outside of
87
[term as::build::date],
97
Its behaviour is like [cmd ::critcl::subject], in that it treats all
98
keys as list of words, with each call declaring one or more words for
99
the key, and multiple calls extending the data for an existing key, if
102
[para] While it is possible to declare information for one of the
103
reserved keys with this command such data is ignored when the final
104
meta data is assembled and written.
106
[para] Use the commands
107
[cmd ::critcl::license],
108
[cmd ::critcl::summary],
109
[cmd ::critcl::description]
110
[cmd ::critcl::subject],
111
[cmd {package require}], and
112
[cmd {package provide}]
113
to declare data for the reserved keys.
115
[para] The information for the reserved keys
117
[term as::build::date] and
120
is automatically generated by [package critcl] itself.
122
[comment ---------------------------------------------------------------------]
123
[call [cmd ::critcl::meta?] [arg key]]
125
This command enables the retrieval of meta data information from with
126
the code defining a critcl based package. Given the [arg key] the
127
associated value is returned as the result of the command.
129
[para] The envisioned main use is the retrieval of the package's name
130
from within utility packages having to adapt C code templates to their
131
environment. An example of a package using this command for exactly
132
this purpose is [package critcl::class].
134
[comment ---------------------------------------------------------------------]
135
[call [cmd ::critcl::buildrequirement] [arg script]]
137
This command provides control over the capturing of dependencies
138
declared via [cmd {package require}]. It runs the script, and any
139
dependencies declared within are ignored, i.e. not recorded in the
added
removed
doc/include/api_meta.inc
