cmdr
Check-in [f30dbe0098]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Extended information about help formats and how to write them. Documented the DSL "section" command.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:f30dbe0098ef2c5902fd95007057e9a95be9f675
User & Date: andreask 2013-11-27 19:23:33
Context
2013-11-28
04:16
Fixed help docs. Completed sequence figures, command-completion docs. check-in: 3359a9b2c8 user: aku tags: trunk
2013-11-27
19:23
Extended information about help formats and how to write them. Documented the DSL "section" command. check-in: f30dbe0098 user: andreask tags: trunk
18:25
Added back-references from packages to the devguide for command-line completion. check-in: f7695638e8 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_help.man.

4
5
6
7
8
9
10





11

12
13
14
15
16
17
18
19
20
21
22
23
24
..
35
36
37
38
39
40
41









42
43
[include parts/module.inc]
[require cmdr::help]
[titledesc [vset TITLE_HELP]]
[description]
[include parts/welcome.inc]

This internal package implements the four standard help formats





[const full], [const short], [const list], and [const by-category].


[para] It provides a single utility command used by the other parts of
the framework to add a [syscmd help] command to any
[package cmdr::actor] requiring such.



[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::help] [method auto] [arg actor]]

When invoked this command extends the [arg actor] with a [const help]
................................................................................
terminal.

[list_begin arguments]
[arg_def [package cmdr::actor] actor]
The [package cmdr::actor] instance to be extended with [syscmd help].
[list_end]
[list_end]









[include parts/feedback.inc]
[manpage_end]







>
>
>
>
>
|
>




<
<







 







>
>
>
>
>
>
>
>
>


4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21


22
23
24
25
26
27
28
..
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
[include parts/module.inc]
[require cmdr::help]
[titledesc [vset TITLE_HELP]]
[description]
[include parts/welcome.inc]

This internal package implements the four standard help formats

[list_begin enumerated]
[enum] [const full],
[enum] [const short],
[enum] [const list], and
[enum] [const by-category].
[list_end]

[para] It provides a single utility command used by the other parts of
the framework to add a [syscmd help] command to any
[package cmdr::actor] requiring such.



[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::help] [method auto] [arg actor]]

When invoked this command extends the [arg actor] with a [const help]
................................................................................
terminal.

[list_begin arguments]
[arg_def [package cmdr::actor] actor]
The [package cmdr::actor] instance to be extended with [syscmd help].
[list_end]
[list_end]

[section {Format Notes}]

The format [const by-category] looks for and uses the block
[const *category-order*] for when the user wishes to override the
natural order of used for the toplevel sections.

[para] This block has to be defined in the root of the command hierarchy.

[include parts/feedback.inc]
[manpage_end]

Added doc/cmdr_helpformats.man.







































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_helpformats [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::help]
[titledesc [vset TITLE_DEV_HF]]
[description]
[include parts/welcome.inc]

This document describes the API expected of [term {help formats}]
to make them usable within the [vset PTITLE] framework, and how to
write a custom help format.

[para] Readers interested in the standard help formats of the
framework should read [term [vset TITLE_HELP]].

[section Background]

Help formats are [vset PTITLE]'s way of converting in-memory
information about a command hierarchy into something usable for human
consumption and obviating the need for writing separate documentation,
which may easily get out of sync with the specification.

[para] The system was made extensible for while the standard formats
listed in [term [vset TITLE_HELP]] should cover the common cases, and
the json format of [term [vset TITLE_HELP_JSON]] is a general export,
it is always possible to run into unprediced non-standard situations
not covered as is.

[section API]

For the framework to automatically pick up a new help format
[const foo] the package implementing it has to specify a single
command [cmd ::cmdr::help::format::<[var foo]>], and this package has
to be loaded before the command hierarchy you want to use it for is
specified.

[para] In more detail:

[list_begin definitions]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::help::format::<foo>] [arg root] [arg width] [arg help]]

This command, having access to the root actor of a command hierarchy,
the number of columns to format the help towards, and a help data
structure itself, has to return a string, the formatted help generated
from the arguments.

[list_begin arguments]
[arg_def cmdr::officer root]
The root officer of the command hierarchy.

With the exception of [const by-category] the standard formats do not
use this argument. By providing it the format has access to the
toplevel common blocks, allowing for the transfer of custom
information from the specifiction to the format.

[para] [const by-category] for example looks for and uses the block
[const *category-order*] for when the user wishes to override the
natural order of used for the toplevel sections.

[arg_def integer width]
The number of columns to format the help towards.

[arg_def dictionary help]
A dictonary holding the help information to format. For more details
see section [sectref {Help Dictionary}].

[list_end]

[comment {- - -- --- ----- -------- -------------}]
[list_end]

[section {Help Dictionary}]
[include parts/help_structure.inc]

[section Example]

As an example the implementation of the standard help format
[const list] is shown here.

[example {
# Entrypoint
proc ::cmdr::help::format::list {root width help} {
    set result {}
    dict for {cmd desc} $help {
	lappend result [List $width $cmd $desc]
    }
    return [join $result \n]
}

# Main work procedure for commands
proc ::cmdr::help::format::List {width name command} {
    dict with command {} ; # -> desc, options, arguments, parameters

    # Short line.
    lappend lines \
	[string trimright \
	     "    [join $name] [HasOptions $options][Arguments $arguments $parameters]"]
    return [join $lines \n]
}

# Support procedures
proc ::cmdr::help::format::HasOptions {options} {
    if {[dict size $options]} {
	return "\[OPTIONS\] "
    } else {
	return {}
    }
}

proc ::cmdr::help::format::Arguments {arguments parameters} {
    set result {}
    foreach a $arguments {
	set v [dict get $parameters $a]
	dict with v {} ; # -> code, desc, label
	switch -exact -- $code {
	    +  { set text "<$label>" }
	    ?  { set text "\[<${label}>\]" }
	    +* { set text "<${label}>..." }
	    ?* { set text "\[<${label}>...\]" }
	}
	lappend result $text
    }
    return [join $result]
}
}]

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_howto_development.man.

95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
in [term [vset TITLE_VALIDATE]]) as well.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Help Formats}]

Everything said in the public document [term [vset TITLE_DEV_HF]]
applies to the standard help formats of the framework (as listed in
[term [vset TITLE_HELP_STD]]) as well.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Command Line Completion}]

The document [term [vset TITLE_DEV_COMPLETE]] describes the inner
workings of the command line completion provided by the framework.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[include parts/related.inc]
[include parts/feedback.inc]
[manpage_end]







|











95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
in [term [vset TITLE_VALIDATE]]) as well.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Help Formats}]

Everything said in the public document [term [vset TITLE_DEV_HF]]
applies to the standard help formats of the framework (as listed in
[term [vset TITLE_HELP]]) as well.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Command Line Completion}]

The document [term [vset TITLE_DEV_COMPLETE]] describes the inner
workings of the command line completion provided by the framework.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[include parts/related.inc]
[include parts/feedback.inc]
[manpage_end]

Changes to doc/parts/definitions.inc.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
[vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
[vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
[vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
[vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
[vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
[vset TITLE_HELP_JSON     "[vset PTITLE] - Formatting help as JSON object"]
[vset TITLE_HELP_STD      "[vset PTITLE] - Standard help formats of the framework"]
[vset TITLE_HELP_SQL      "[vset PTITLE] - Formatting help as series of SQL commands"]
[vset TITLE_OFFICER       "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."]
[vset TITLE_PARAMETER     "[vset PTITLE] - (Partially internal) Command parameters"]
[vset TITLE_PRIVATE       "[vset PTITLE] - (Internal) Single command handling, options, and arguments"]
[vset TITLE_UTIL          "[vset PTITLE] - (Internal) General Utilities"]
[vset TITLE_VALIDATE      "[vset PTITLE] - Standard validation types for parameters"]
[vset TITLE_VCOMMON       "[vset PTITLE] - Utilities for Validation Types"]

[comment {- Miscellanea ............. - - -- --- ----- --------}]







<









15
16
17
18
19
20
21

22
23
24
25
26
27
28
29
30
[vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
[vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
[vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
[vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
[vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
[vset TITLE_HELP_JSON     "[vset PTITLE] - Formatting help as JSON object"]

[vset TITLE_HELP_SQL      "[vset PTITLE] - Formatting help as series of SQL commands"]
[vset TITLE_OFFICER       "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."]
[vset TITLE_PARAMETER     "[vset PTITLE] - (Partially internal) Command parameters"]
[vset TITLE_PRIVATE       "[vset PTITLE] - (Internal) Single command handling, options, and arguments"]
[vset TITLE_UTIL          "[vset PTITLE] - (Internal) General Utilities"]
[vset TITLE_VALIDATE      "[vset PTITLE] - Standard validation types for parameters"]
[vset TITLE_VCOMMON       "[vset PTITLE] - Utilities for Validation Types"]

[comment {- Miscellanea ............. - - -- --- ----- --------}]

Changes to doc/parts/dsl_officer.inc.

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
(See [term [vset TITLE_DSL_PRIVATE]]), and a command prefix to invoke
when it is chosen.

[para] This command prefix is called with a single argument, the
[package cmdr::config] instance holding the [term parameter]s of the
private.

--TODO--(ref:backend-example-code)--

[comment {- - -- --- ----- -------- -------------}]
[call [cmd undocumented]]

This command excludes the [term officer] (and its subordinates) from
the generated help.

Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.

[list_end]







|











146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
(See [term [vset TITLE_DSL_PRIVATE]]), and a command prefix to invoke
when it is chosen.

[para] This command prefix is called with a single argument, the
[package cmdr::config] instance holding the [term parameter]s of the
private.

@EDIT --TODO--(ref:backend-example-code)--

[comment {- - -- --- ----- -------- -------------}]
[call [cmd undocumented]]

This command excludes the [term officer] (and its subordinates) from
the generated help.

Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.

[list_end]

Changes to doc/parts/dsl_private.inc.

36
37
38
39
40
41
42















43
44
45
46
47
48
49
[call [cmd option] [arg name] [arg help] [arg script]]

This command adds an [term option] (i.e. named) [term parameter] to
the [term private], with description [arg help] and its specification
[arg script] of parameter commands as described in
[term [vset TITLE_DSL_PARAMETER]].
















[comment {- - -- --- ----- -------- -------------}]
[call [cmd state] [arg name] [arg help] [arg script]]

This command adds a [term state] (i.e. hidden) [term parameter] to the
[term private], with description [arg help] and its specification
[arg script] of parameter commands as described in
[term [vset TITLE_DSL_PARAMETER]].







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
[call [cmd option] [arg name] [arg help] [arg script]]

This command adds an [term option] (i.e. named) [term parameter] to
the [term private], with description [arg help] and its specification
[arg script] of parameter commands as described in
[term [vset TITLE_DSL_PARAMETER]].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd section] [arg word]...]

This command places the [term private] into a help section/category,
for use by the standard help format [term by-category]
(See [term [vset TITLE_HELP]]).

[para] The section/category is specified as a list of words, each
denoting part of the path to the section. This means that the last
word is the section of the private, with the preceding words the
sections it is nested in.

[para] Multiple calls are possible and accumulate. In other words,
the private can be placed in more than one section/category.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd state] [arg name] [arg help] [arg script]]

This command adds a [term state] (i.e. hidden) [term parameter] to the
[term private], with description [arg help] and its specification
[arg script] of parameter commands as described in
[term [vset TITLE_DSL_PARAMETER]].