cmdr
Check-in [172951e9a3]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

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

Overview
Comment:Continued documentation work, first fillings for the dev-guide, more figures.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 172951e9a3ea1bbc72b9c3a4e20d17225889049f
User & Date: andreask 2013-11-26 00:32:32
Context
2013-11-26
05:17
Continued work on the dev guide. Complete architecture and package dependency information. Regenerated figures and embedded documentation. check-in: e33e0f5b2d user: aku tags: trunk
00:32
Continued documentation work, first fillings for the dev-guide, more figures. check-in: 172951e9a3 user: andreask tags: trunk
2013-11-22
20:52
Modified officers. Auto-create an 'exit'-command, if not in conflict with user commands. Method as backend for private. Usable by others as well. Bumped version to 0.14. check-in: 8d7fcadf53 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_howto_development.man.

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
[list_end]

first, if that was not done already. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[comment {
    @ EDIT Please edit the remainder of the document to suit.

    Information to consider putting into this documentat are


    - Physical directory structure
    - Logical structure (file- and package dependencies, for example)
    - Development Tools required, beyond the tools for building and installation.

    - System architecture, beyond what a simple user is given (in the introduction).
    -- Data structures, for example.

    - Deeper assumptions how pieces work together (Sequence diagrams?)
}]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Development Tools}]


[vset PTITLE] (currently) does not require tools beyond those needed for
build and installation.







[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Demonstration/Example Applications}]

[vset PTITLE] (currently) does not have demonstrations, nor examples.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Directory structure}]

Explain the physical layout (directory structure).

[comment { @EDIT Explain physical layout (directory structure)
    Kettle: Consider providing standard text blocks explaining

            doc/
            doc/figures/

            embedded/
}]

















[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Architecture & Concepts}]



[list_begin enumerated]
[enum] Explain the internal architecture.
[enum] Explain file dependencies, if any.
[enum] Explain package dependencies, if any.
[enum] Explain the internal data structures, if any.
[enum] Explain entity relationships (UML ERD), if any.
[enum] Explain important operation sequences (UML SD), if any.
[list_end]











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







|
<
>
|
>

<
|
<
>
|
<
>
|
|

|
<

>
|
|
>
>
>
>
>
>











|
<
>
|
<
>
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




>
>

|
<
<
|
<
|


>
>
>
>
>
>
>
>
>
>



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
[list_end]

first, if that was not done already. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Development Tools}]


[vset PTITLE] requires the following tools going beyond those needed
for build and installation.


[list_begin definitions]


[def [syscmd dia]]


Processor for [package diagram]-based figures.
See package [package tklib].

[def [syscmd dtplite]]


Processor for [package doctools]-based documentation files, i.e. the
[file .man] files under [file doc/].
See package [package tcllib].

[para] This requirement is optional. If a Tcllib providing the package
[package dtplite] is installed then [syscmd kettle] will use the
package in favor of the external application.

[list_end]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Demonstration/Example Applications}]

[vset PTITLE] (currently) does not have demonstrations, nor examples.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Directory structure}]

Explain the physical layout (directory structure).

[list_begin definitions]


[include parts/layout_standard.inc]


[def [file actor.tcl]]     == Package [package cmdr::actor].
[def [file cmdr.tcl]]      == Package [package cmdr].
[def [file config.tcl]]    == Package [package cmdr::config].
[def [file help.tcl]]      == Package [package cmdr::help].
[def [file help_json.tcl]] == Package [package cmdr::help::json].
[def [file help_sql.tcl]]  == Package [package cmdr::help::sql].
[def [file officer.tcl]]   == Package [package cmdr::officer].
[def [file parameter.tcl]] == Package [package cmdr::parameter].
[def [file private.tcl]]   == Package [package cmdr::private].
[def [file util.tcl]]      == Package [package cmdr::util].
[def [file validate.tcl]]  == Package [package cmdr::validate].
[def [file vcommon.tcl]]   == Package [package cmdr::validate::common].

[list_end]

[section {Extended Build Actions}]

[include parts/build-dev.inc]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Architecture & Concepts}]

The following sections explain

[list_begin enumerated]
[enum] the internal architecture and package dependencies.


[enum] the internal data structures.

[enum] important operation sequences (UML SD).
[list_end]

[subsection {System Architecture}]
[include parts/architecture.inc]
[comment { @EDIT Package dependencies (diagram) }]

[subsection {Data structures}]
[comment { @EDIT Explain data structures }]

[subsection {Operation Sequences}]
[comment { @EDIT Explain operation sequences }]

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

Changes to doc/cmdr_introduction.man.

18
19
20
21
22
23
24
25
26
27
28
29
30
31
command parameters, and validating them.

Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion.

[section {System Architecture}]

[comment { -- @EDIT Please edit to suit -- }]

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







|
<





18
19
20
21
22
23
24
25

26
27
28
29
30
command parameters, and validating them.

Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion.

[section {System Architecture}]
[include parts/architecture.inc]


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

Added doc/figures/architecture.dia.




























































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0
# Parser Tools Architecture Diagram

set counter 0
if {![info exists mark]} { set mark -1 }

proc xbox {args} {
    variable mark
    variable counter

    if {$mark == $counter} {
	lappend args color red stroke 2
    }
    incr counter
    return [uplevel 1 [list box {*}$args]]
}

proc public {args} {
    {*}$args color blue stroke 2
}

proc partial {args} {
    {*}$args dashed
}

proc area {label args} {
    set E [xbox fillcolor lightyellow {*}$args]
    group {
	text text $label with nw at [last box nw]
    }
    return $E
}

down
set boxwidth [100 mm]
set movelength [5 mm]

set M [area "Main"             height [20 mm]] ; move
set E [area "Entities"         height [30 mm]] ; move
set S [area "Support Packages" height [38 mm]]

block {
    set fillcolor white
    set boxheight [10 mm]
    set boxwidth  [20 mm]

    public xbox "cmdr"
} at $M

block {
    east
    set fillcolor white
    set boxheight [10 mm]
    set boxwidth  [20 mm]

    xbox "util" ; move
    xbox "validate" ; move
    public xbox "validate::common" width [40 mm]
    down ; move ; move ; west

    public xbox "help::sql" ; move
    public xbox "help::json" ; move
    xbox "help"
} at $S

block {
    set fillcolor white
    set boxheight [10 mm]
    set boxwidth  [20 mm]
    east

    xbox "actor" ; down ; move
    xbox "private" 
    group { west ; move ; xbox "officer" }
    east ; move
    partial public xbox "config" ; move
    partial public xbox "parameter"
} at $E

Added doc/figures/architecture.txt.














>
>
>
>
>
>
>
1
2
3
4
5
6
7
+--------------------------------------------+
|                    cmdr                    |
+--------------------------------------------+
| actor, officer, private, config, parameter |
+--------------------------------------------+
|           help*, util, validate*           |
+--------------------------------------------+

Added doc/parts/architecture.inc.






















































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
[para] All packages in the framework belong to one of three layers,
as shown below:

[image architecture].

[list_begin itemized]

[item] The topmost layer contains only a single package,
[package cmdr], which is a trivial entry point to the system.

[item] The bottom layer contains the mainly internal utility packages.
The exception is [package cmdr::validate::common], for use in bespoke
validation types. See the document about [term [vset TITLE_DEV_VT]]
for details.

[item] The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:

[image erd]
[list_end]

[para] Packages marked with a dashed blue border are public in parts,
and private in parts.

[para] Packages marked with an unbroken blue border are fully public.

Added doc/parts/build-dev.inc.
































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
Our build-system is based on [syscmd kettle], as already explained in
the [term [vset TITLE_INSTALL]]. Beyond the targets useful for
installation it also provides targets aiding developers and
maintainers. These are:

[list_begin definitions]

[def {Validation of the documentation}]

[example_begin]
% /path/to/[vset PROJECT]/build.tcl validate-doc
[example_end]


[def {Regeneration of the embedded documentation}]

[example_begin]
% /path/to/[vset PROJECT]/build.tcl doc
[example_end]

[def {Regeneration of the figures for the documentation}]

[example_begin]
% /path/to/[vset PROJECT]/build.tcl figures
[example_end]


[def {Execution of the test-suite}]

The most basic execution of the test-suite is done with

[example_begin]
% /path/to/[vset PROJECT]/build.tcl test
[example_end]

[para] When the test-suite reports issues with the framework use of
the more extended form below is indicated, with a [const <stem>] of
your choice. This will generate a number of files whose name starts
with the prefix [file <stem>.]. These will contain extended test logs,
details about errors and failures, etc.

[example_begin]
% /path/to/[vset PROJECT]/build.tcl test --log <stem>
[example_end]


[list_end]

Changes to doc/parts/build.inc.

1
2
3
4
5
6
7
8
9
10
[comment {
    @EDIT Please edit to suit - Kettle based build and installation.
}]

[vset PTITLE] uses the Kettle application and package to handle building
and installation. It is assumed to be installed and working. Please see
section [sectref Kettle] in [sectref Requisites] for more information.

[para] Note that all access to Kettle is mediated by the [file build.tcl]
script, found in the top-level directory of the project.
<
<
<









1
2
3
4
5
6
7



[vset PTITLE] uses the Kettle application and package to handle building
and installation. It is assumed to be installed and working. Please see
section [sectref Kettle] in [sectref Requisites] for more information.

[para] Note that all access to Kettle is mediated by the [file build.tcl]
script, found in the top-level directory of the project.

Added doc/parts/layout_standard.inc.








































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
[def [file build.tcl]]
The main file of the [syscmd kettle]-based build-system.

[def [file doc/]]
Main directory for all documentation.

[para] Based on the [package doctools] package and tools provided by
[package Tcllib].

[def [file doc/figures/]]
Main directory for all diagrams and figures used by the documentation.

[para] Based on the [package diagram] package and tools provided by
[package Tklib].


[def [file embedded/]]
Compiled documentation (manpages and HTML).

Part of the repository for

[list_begin enumerated]
[enum] easy access from the repository's web interface
([uri http://fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki {embedded documentation}]),
and
[enum] quicker installation (no need to compile during the
installation process itself).
[list_end]


[def [file tests/]]
Main directory for the test-suite.

[para] Based on the [package tcltest] package distributed with the Tcl
core.