Check-in [ff12632219]

Not logged in

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

Overview
Comment:Rejoin inadvertent split head.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:ff126322196c12ac98d6dee4515a28d7ce9dce9b
User & Date: andreask 2014-05-30 20:59:32
Context
2015-04-17
21:50
Goals added which show the content (packages, apps) found in the build. Packages are listed with version info. check-in: 940893cb88 user: andreask tags: trunk
2014-05-30
20:59
Rejoin inadvertent split head. check-in: ff12632219 user: andreask tags: trunk
20:58
kettle/path/revision.git: Handle possibility of "git describe" failing (not due missing git, but due missing tags the describe wants). This needs more work to separate out a missing git command and report that as usual. This is a quick patch. check-in: 0a12475c4e user: andreask tags: trunk
2014-03-28
19:25
Regenerated embedded docs. check-in: aad14ede89 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to embedded/man/files/kettle.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
...
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
...
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
...
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
...
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
...
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
...
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
...
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
...
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
...
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
...
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
...
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
...
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
....
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
....
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
....
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
....
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
....
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
....
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
....
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle \- Kettle - Core
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
\fBkettle tcl\fR
.sp
\fBkettle tclapp\fR \fIpath\fR
.sp
\fBkettle critcl3\fR
.sp
\fBkettle depends-on\fR \fIpath\fR...
.sp
\fBkettle doc-destination\fR \fIpath\fR
.sp
\fBkettle doc\fR ?\fIdocroot\fR?
.sp
\fBkettle figures\fR ?\fIfigroot\fR?
.sp
................................................................................
.sp
\fBkettle ovalidate\fR \fBboolean\fR
.sp
\fBkettle ovalidate\fR \fBlistsimple\fR
.sp
\fBkettle ovalidate\fR \fBdirectory\fR
.sp
\fBkettle ovalidate\fR \fBreadable.file\fR
.sp
\fBkettle ovalidate\fR \fBpath\fR
.sp
\fBkettle path\fR \fBbench-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBbindir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBcat\fR \fIpath\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBcathead\fR \fIpath\fR \fIn\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBcopy-file\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBcopy-files\fR \fIdstdir\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBcritcl3-package-file\fR \fIfile\fR
.sp
\fBkettle path\fR \fBdiagram-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBdoctools-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBdry-barrier\fR ?\fIdryscript\fR?
.sp
\fBkettle path\fR \fBexec\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBfixhashbang\fR \fIfile\fR \fIshell\fR
.sp
\fBkettle path\fR \fBforeach-file\fR \fIpath\fR \fIpv\fR \fIscript\fR
.sp
\fBkettle path\fR \fBgrep\fR \fIpattern\fR \fIdata\fR
.sp
................................................................................
.sp
\fBkettle path\fR \fBin\fR \fIpath\fR \fIscript\fR
.sp
\fBkettle path\fR \fBincdir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBinstall-application\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBinstall-file-group\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBinstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBinstall-script\fR \fIsrc\fR \fIdstdir\fR \fIshell\fR
.sp
\fBkettle path\fR \fBkettle-build-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBlibdir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBmandir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBnorm\fR \fIpath\fR
.sp
\fBkettle path\fR \fBpipe\fR \fIlv\fR \fIscript\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBrelative\fR \fIbase\fR \fIdst\fR
.sp
\fBkettle path\fR \fBrelativecwd\fR \fIdst\fR
.sp
\fBkettle path\fR \fBrelativesrc\fR \fIdst\fR
.sp
\fBkettle path\fR \fBremove-path\fR \fIbase\fR \fIpath\fR
.sp
\fBkettle path\fR \fBremove-paths\fR \fIbase\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBrgrep\fR \fIpattern\fR \fIdata\fR
.sp
\fBkettle path\fR \fBscan\fR \fIlabel\fR \fIroot\fR \fIpredicate\fR
.sp
\fBkettle path\fR \fBscript\fR
.sp
................................................................................
.sp
\fBkettle path\fR \fBtmpfile\fR ?\fIprefix\fR?
.sp
\fBkettle path\fR \fBuninstall-application\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBuninstall-file-group\fR \fIlabel\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBuninstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.sp
\fBkettle path\fR \fBwrite\fR \fIpath\fR \fIcontents\fR \fIarg\fR...
.sp
\fBkettle recipe\fR \fBdefine\fR
.sp
\fBkettle recipe\fR \fBparent\fR
.sp
\fBkettle recipe\fR \fBexists\fR
.sp
................................................................................
.sp
\fBkettle io\fR \fBsetwidget\fR \fIw\fR
.sp
\fBkettle io\fR \fBfor-gui\fR \fIscript\fR
.sp
\fBkettle io\fR \fBfor-terminal\fR \fIscript\fR
.sp
\fBkettle io\fR \fBputs\fR \fIarg\fR...
.sp
\fBkettle io\fR \fBtrace\fR \fItext\fR
.sp
\fBkettle io\fR \fBtrace-on\fR
.sp
\fBkettle io\fR \fBanimation begin\fR
.sp
................................................................................
.sp
\fBkettle io\fR \fBanimation last\fR \fItext\fR
.sp
\fBkettle io\fR \fItag\fR \fIscript\fR
.sp
\fBkettle io\fR m\fItag\fR \fItext\fR
.sp
\fBlambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...?
.sp
\fBlambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...?
.sp
\fBtry\fR \fIarg\fR...
.sp
\fBkettle strutil\fR \fBindent\fR \fItext\fR \fIprefix\fR
.sp
\fBkettle strutil\fR \fBpadl\fR \fIlist\fR
.sp
\fBkettle strutil\fR \fBpadr\fR \fIlist\fR
.sp
................................................................................
\fBkettle strutil\fR \fBundent\fR \fItext\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
This document is the reference to all commands provided by the kettle
package, from the user-visible declarations to the lowest utilities.
.PP
It is intended for both power-users wishing to write their own
high-level commands linking into the existing foundations and
developers and maintainers of kettle itself.
.PP
A basic user should read
\fIKettle - Application - Build Interpreter\fR
and \fIKettle - Build Declarations\fR instead.
.SH OVERVIEW
The high-level architecture is shown in the image below:
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
This document is concerned with the lowest level shown, the core
kettle package itself. The inner boxes of that architectural box show
the parts which are user-visible, i.e. providing the DSL commands
explained in \fIKettle - Build Declarations\fR.
For the details we have
.PP
.PS
.nf

*critcl    <- doc, testsuite, recipes, tool, options, path, io, try
*tcl       <- doc, testsuite, recipes, path, try
................................................................................
try
lambda

.fi
.PE
.PP
In this image we now see all the components found inside of the kettle
package, their organization into layers and their dependencies. The
latter is actually a bit simplified, showing only the dependencies
between adjacent layers and leaving out the dependencies crossing
layers. Adding them would make the image quite a bit more crowded.
.PP
The green boxes are again the user-visible parts, either for
the build declarations. The rest is internal. Note how and that the
components found in the blue box are all dependent on each other,
i.e. these are in circular dependencies.
.PP
The names in the boxes directly refer to the file names
containing the code of the component, without the extension,
"\fI.tcl\fR".
The only file not mentioned is "\fIkettle.tcl\fR" which is the
entrypoint to the package and sources all the others.
Each component C is generally served by a single ensemble command,
"\fBkettle\fR \fBC\fR". The exceptions are the components exporting
the user-visible declaration commands. Their commands, while still
named "\fBkettle\fR \fBC\fR", are not ensembles, but the one
command in that component.
.PP
The following sections go through the components from the top
down to the bottom, starting with the user visible commands described
in \fIKettle - Build Declarations\fR, covering all the green boxes.
For the remainder:
.TP
gui
\fBGraphical Interface Support\fR
.TP
tool
\fBTool handling\fR
................................................................................
try
\fBError handling\fR
.TP
strutil
\fBString processing\fR
.PP
.PP
Not convered in the above is "\fIstandard.tcl\fR". This file
does not export any commands to document. It unconditionally defines
the standard recipes instead. These are the recipes which are always
available, in contrast to the recipes dynamically created by the
declarations commands in response to their scanning of a package
source directory.
.SH "BUILD DECLARATIONS"
.TP
\fBkettle tcl\fR
This command declares the presence of one or more Tcl packages in the
package source directory.
.sp
The package source directory is scanned to locate
them. Packages are detected by finding a marker (Tcl command) of the
form
.CS


    package provide NAME VERSION

.CE
.IP
in a file, where both \fBNAME\fR and \fBVERSION\fR must be literal
strings, not commands, nor variable references. It is best recognized
when found alone on its line.
Note that files containing an \fIanti-marker\fR of the form
.CS


    package require critcl

.CE
.IP
are rejected as Tcl packages. Use the command \fBkettle critcl3\fR
to detect such packages, mixing Tcl and C.
In each accepted package file the command further looks for and
recognizes embedded pragmas of the form
.CS

# @owns: PATH
.CE
.IP
which provides kettle with information about files belonging to the
same package without directly providing it. This can be data files, or
other Tcl files sourced by the main package file.
.sp
For each detected package \fBP\fR two recipes are defined, to
install and uninstall this package, namely:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-tcl-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry.
.sp
Tcl packages are installed into the directory specified by
option \fB--lib-dir\fR despite technically not being binary files.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR".
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively).
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle tcl\fR,
with the proper paths.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself.
.TP
\fBkettle tclapp\fR \fIpath\fR
This command declares the presence of a Tcl script application found
at the \fIpath\fR under the package source directory.
.sp
If the specified application is found the command will define
two recipes to install and uninstall this application, namely:
.RS
.TP
\fBinstall-app-\fIpath\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-applications
     -> uninstall-tcl-applications
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific application up to all and sundry.
.sp
Script applications are installed into the directory specified
by option \fB--bin-dir\fR despite technically not being binary
files.
.RS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR".
.RE
.TP
\fBkettle critcl3\fR
This command declares the presence of one or more critcl-based Tcl
packages in the package source directory, mixing C and Tcl.
.sp
The package source directory is scanned to locate
them. Packages are detected by finding two markers (Tcl commands) in
the file. These markers are of the form
.CS


    package provide NAME VERSION

.CE
.IP
................................................................................


    package require critcl

.CE
.IP
Both \fBNAME\fR and \fBVERSION\fR must be literal strings, not
commands, nor variable references. They are best recognized when found
alone on their respective lines.
.sp
For each detected package \fBP\fR three recipes are defined, to
install and uninstall this package. Installation comes in two
variants, regular and debug:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
\fBdebug-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-binary-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry.
.sp
Critcl-based packages are installed into the directory
specified by option \fB--lib-dir\fR.
Critcl's choice of the target configuration to build for can be
overrriden via option \fB--target\fR.
Kettle's choice of which critcl application to use cane overriden by
option \fB--with-critcl3\fR, except if kettle found a
\fBcritcl\fR package and runs everything itself instead of
invoking critcl child processes.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR".
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3.kit\fR",
.IP [3]
"\fIcritcl3.tcl\fR",
.IP [4]
"\fIcritcl3.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl.kit\fR",
.IP [7]
"\fIcritcl.tcl\fR", and
.IP [8]
"\fIcritcl.exe\fR"
.RE
.IP
found on the \fBPATH\fR. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application. In that case kettle will run everything in itself,
without invoking critcl child processes.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively).
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle critcl3\fR,
with the proper paths.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself.
.TP
\fBkettle depends-on\fR \fIpath\fR...
This command declares that the current sources depend on the packages
in the specified directories. These are best specified as relative
directories and most useful in package bundles where multiple
dependent packages are managed in a single source repository.
.sp
The arguments can be paths to files too. In that case the files
are assumed to be the build declaration files of the required packages
in question. In case of a directory path kettle will search for the
build declaration file it needs.
This information is currently only used by the package-specific
"install" and "debug" recipes generated by the kettle commands
\fBkettle tcl\fR and \fBkettle critcl\fR.
.TP
\fBkettle doc-destination\fR \fIpath\fR
The "doc" recipe generated by the \fBkettle doc\fR command (see
below) saves the conversion results into the sub-directory specified
by option \fB--with-doc-destination\fR.
.sp
This command declares that the results should be put into the
specified non-standard \fIpath\fR instead of the default of
"\fIembedded\fR".
To take effect it has to be run \fIbefore\fR \fBkettle doc\fR is
run.
\fINote\fR that the user is still able to override with by setting
\fB--with-doc-destination\fR on the command line.
.RS
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from.
.sp
This should be a relative path, which will interpreted relative
to the package source directory.
.sp
The default value is "\fIembedded\fR".
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command.
.RE
.TP
\fBkettle doc\fR ?\fIdocroot\fR?
This command declares the presence of \fBdoctools\fR-based
documentation files under the directory \fIdocroot\fR, which is a path
relative to the source directory.
.sp
If not specified \fIdocroot\fR defaults to "\fIdoc\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The commands \fBkettle tcl\fR, \fBkettle critcl3\fR, and
\fBkettle gh-pages\fR run this command implicitly, with the default
paths.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before them, with the proper path.
.sp
The package documentation directory is scanned to locate the
documentation files. They are recognized by containing any of the
marker strings
.RS
.IP \(bu
"\fB[manpage_begin\fR"
.IP \(bu
"\fB--- doctools ---\fR"
.IP \(bu
"\fBtcl.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters. Possible documentation files are
rejected should they contain any of the anti-markers
.RS
.IP \(bu
"\fB--- !doctools ---\fR"
.IP \(bu
"\fB!tcl.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters. This last is necessary as doctools
include file feature allows the actual document content to start in an
include file which cannot operate without being includes from a master
file configuring it.
.sp
When documentation files are found the command will define
recipes to convert the documentation into manpages and HTML files,
plus recipes install the conversion results. The conversion results
themselves are stored as specified by \fBkettle doc-destination\fR
(see above) and associated options.
.RS
.TP
\fBdoc\fR
.TP
\fBinstall-doc-html\fR
.TP
\fBinstall-doc-manpages\fR
................................................................................
  uninstall
  -> uninstall-doc
     -> uninstall-doc-html
     -> uninstall-doc-manpages

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific type of documentation up to all and sundry.
.sp
HTML documentation is stored under the directory specified by
option \fB--html-dir\fR.
Manpages are stored under the directory specified by
option \fB--man-dir\fR.
The "doc" recipe uses the \fBdtplite\fR application to perform the
various conversions.
.RS
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/html\fR".
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/man\fR".
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite.kit\fR",
"\fIdtplite.tcl\fR", and
"\fIdtplite.exe\fR"
found on the \fBPATH\fR.
.RE
.sp
To simplify usage the command heuristically detects
tklib/diagram based figures by means of internally calling the command
\fBkettle figures\fR with default path arguments
("\fI\fBdoc-sources\fR/figures}\fR".
.sp
If the figures are placed in a non-standard location this
command has to be run before \fBkettle doc\fR, with the proper
paths.
.TP
\fBkettle figures\fR ?\fIfigroot\fR?
This command declares the presence of \fBdiagram\fR-based figures
under the directory \fIfigroot\fR, which is a path relative to the
source directory.
.sp
If not specified \fIfigroot\fR defaults to "\fIdoc/figures\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The command \fBkettle doc\fR (and indirectly \fBkettle tcl\fR and
\fBkettle critcl3\fR) runs this command implicitly, with the default
paths.
This means that if diagrams are stored in a non-standard location
\fBkettle figures\fR must be run explicitly before them, with the
proper path.
.sp
The package diagram directory is scanned to locate the diagram
files. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl.tk//DSL diagram//EN//\fR"
.RE
.IP
in their first 1024 characters.
.sp
When diagram files are found the command will define recipes to
convert the diagrams into PNG raster images (saved as siblings to
their source files), and to render the diagrams on a Tk canvas.
.RS
.TP
\fBfigures\fR
.TP
\fBshow-figures\fR
.RE
.sp
The recipes use the \fBdia\fR application (of \fBtklib\fR)
to perform the conversions, and GUI rendering.
.RS
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia.kit\fR",
"\fIdia.tcl\fR", and
"\fIdia.exe\fR"
found on the \fBPATH\fR.
.RE
.TP
\fBkettle gh-pages\fR
This command declares the presence of a \fIgh-pages\fR branch in the
repository, as is used by, for example, \fIhttp://github.com\fR, to
manage the web-site for a project in the rpeository of the project.
.sp
The command confirms the presence of documentation and that the
local repository is \fBgit\fR-based. If neither is true nothing
done.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
It runs the command \fBkettle doc\fR command implicitly, with the
default paths, to ensure that its own check for documentation work
properly.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before this command, with
the proper path.
.sp
When the above tests pass the command will define a recipe
named \fBgh-pages\fR, which performs all the automatable steps to
copy the embedded documentation of the project into its
\fIgh-pages\fR branch. Afterward the checkout is left at the
\fIgh-pages\fR branch, for the user to review and commit. While the
last step could be automated the review cannot, making the point moot.
.TP
\fBkettle testsuite\fR ?\fItestroot\fR?
This command declares the presence of a \fBtcltest\fR-based
testsuite under the directory \fItestroot\fR, which is a path relative
to the source directory.
.sp
If not specified \fItestroot\fR defaults to "\fItests\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The commands \fBkettle tcl\fR and \fBkettle critcl3\fR) run this
command implicitly, with the default paths.
This means that if a testsuite is stored in a non-standard location
\fBkettle testsuite\fR must be run explicitly before them, with the
proper path.
.sp
The package testsuite directory is scanned to locate the test
files. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl.tk//DSL tcltest//EN//\fR"
.RE
.IP
in their first 1024 characters.
.sp
When testsuites are found the command will define a recipe to
run them. This recipe will recursively invoke the recipes "debug" (or
"install" if the former does not exist, or fails) before performing
the tests, installing the package under test (and its dependencies) in
a local directory for use by the testsuites. The supporting commands
provided by kettle (see \fIKettle - Testsuite Support\fR) know how
to use this.
.RS
.TP
\fBtest\fR
.RE
.sp
The verbosity of testsuite output to the terminal is specified
by the option \fB--log-mode\fR.
The ability to save testsuite output to a series of files is specified
by the option \fB--log\fR.
The tclsh shell used for running the testsuites is specified by option
\fB--with-shell\fR.
.RS
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined. Its value determines the
verbosity of test suite information printed to the terminal or log window.
.sp
The default is \fBcompact\fR.
.TP
\fB--log\fR path
An option for recipe 'test', if defined. Its value is the path "stem"
for a series of files testsuite information is saved into. The actual
files use the specified stem and add their specifc file extension to
it.
.sp
The default is the empty string, disabling the saving of
testsuite information.
.TP
\fB--with-shell\fR path
.RE
.PP
.SH "GRAPHICAL INTERFACE SUPPORT"
This layer contains the command for the creation of the standard
graphical interface to the system.
.TP
\fBkettle gui\fR \fBmake\fR
This high-level command creates a standard graphical interface
providing access to all options and defined recipes, through two tabs
in a notebook.
.sp
Options are handled by type specific fields, the details of
which are created by the option type definitions found under
\fBkettle ovalidate\fR, as specified in section
\fBOption Types and Validation\fR.
.sp
Recipes are acessible through one button per recipe.
.sp
Output is written to a text widget acting as a log window, in
the same tab which contains the action buttons.
.PP
.SH "TOOL HANDLING"
This layer contains commands to manage the declaration of a dependency
on external comands, and their use.
.TP
\fBkettle tool\fR \fBdeclare\fR \fInames\fR ?\fIvalidator\fR?
This command declares the need for an external tool which can have any
of the listed \fInames\fR.
The first element of that list is the name the tool will be known
under within kettle, also called the \fIprimary name\fR of the
tool.
This is the name to hand to \fBkettle tool get\fR below to retrieve
the tool's location.
.sp
Similarly the primary name is used to define an option named
--with-\fBname\fR, used to hold the path found by searching for the
tool on the \fBPATH\fR under its various names, and to allow the user
to override kettle's choice.
.sp
If \fIvalidator\fR is specified it will be treated as the body
of an anonymous procedure with a single argument \fIcmd\fR, the path
of the tool found on \fBPATH\fR and returning a boolean value telling
the caller if this path is acceptable (result == \fBtrue\fR), or
not. In case of the latter the system will continue searching with the
next name in \fInames\fR.
.TP
\fBkettle tool\fR \fBget\fR \fIname\fR
This command returns the path to the \fIname\fRd tool, assuming that
it was \fBdeclare\fRd before.
If no such tool is specified the command prints an error message and
aborts the execution of the current recipe and its callers.
.PP
.SH "RECURSIVE INVOKATIONS"
The commands of this layer enable recipes to recursively invoke other
recipes, for the current and in other packages.
.TP
\fBkettle\fR \fBinvoke\fR
.PP
.SH "OPTION DATABASE"
This layer manages the option database, which both holds the
configuration options, their definitions and values, as also named
shared global state.
.TP
\fBkettle option\fR \fBdefine\fR
.TP
\fBkettle option\fR \fBonchange\fR
.TP
\fBkettle option\fR \fBno-work-key\fR
.TP
................................................................................
\fBkettle option\fR \fBsave\fR
.TP
\fBkettle option\fR \fBload\fR
.TP
\fBkettle option\fR \fBconfig\fR
.PP
.SH "OPTION TYPES AND VALIDATION"
This layer defines the validation types usable by the options.
.TP
\fBkettle ovalidate\fR \fBenum\fR
.TP
\fBkettle ovalidate\fR \fBany\fR
.TP
\fBkettle ovalidate\fR \fBstring\fR
.TP
\fBkettle ovalidate\fR \fBboolean\fR
.TP
\fBkettle ovalidate\fR \fBlistsimple\fR
.TP
\fBkettle ovalidate\fR \fBdirectory\fR
.TP
\fBkettle ovalidate\fR \fBreadable.file\fR
.TP
\fBkettle ovalidate\fR \fBpath\fR
.PP
.SH "PATH UTILITIES"
This layer contains the commands ...
.TP
\fBkettle path\fR \fBbench-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBbindir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBcat\fR \fIpath\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBcathead\fR \fIpath\fR \fIn\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBcopy-file\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBcopy-files\fR \fIdstdir\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBcritcl3-package-file\fR \fIfile\fR
.TP
\fBkettle path\fR \fBdiagram-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBdoctools-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBdry-barrier\fR ?\fIdryscript\fR?
.TP
\fBkettle path\fR \fBexec\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBfixhashbang\fR \fIfile\fR \fIshell\fR
.TP
\fBkettle path\fR \fBforeach-file\fR \fIpath\fR \fIpv\fR \fIscript\fR
.TP
\fBkettle path\fR \fBgrep\fR \fIpattern\fR \fIdata\fR
.TP
................................................................................
.TP
\fBkettle path\fR \fBin\fR \fIpath\fR \fIscript\fR
.TP
\fBkettle path\fR \fBincdir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBinstall-application\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBinstall-file-group\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBinstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBinstall-script\fR \fIsrc\fR \fIdstdir\fR \fIshell\fR
.TP
\fBkettle path\fR \fBkettle-build-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBlibdir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBmandir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBnorm\fR \fIpath\fR
.TP
\fBkettle path\fR \fBpipe\fR \fIlv\fR \fIscript\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBrelative\fR \fIbase\fR \fIdst\fR
.TP
\fBkettle path\fR \fBrelativecwd\fR \fIdst\fR
.TP
\fBkettle path\fR \fBrelativesrc\fR \fIdst\fR
.TP
\fBkettle path\fR \fBremove-path\fR \fIbase\fR \fIpath\fR
.TP
\fBkettle path\fR \fBremove-paths\fR \fIbase\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBrgrep\fR \fIpattern\fR \fIdata\fR
.TP
\fBkettle path\fR \fBscan\fR \fIlabel\fR \fIroot\fR \fIpredicate\fR
.TP
\fBkettle path\fR \fBscript\fR
.TP
................................................................................
.TP
\fBkettle path\fR \fBtmpfile\fR ?\fIprefix\fR?
.TP
\fBkettle path\fR \fBuninstall-application\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBuninstall-file-group\fR \fIlabel\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBuninstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR...
.TP
\fBkettle path\fR \fBwrite\fR \fIpath\fR \fIcontents\fR \fIarg\fR...
.PP
.SH "RECIPE DATABASE"
This layer contains the commands managing the database of all known
recipes, ready for execution.
.TP
\fBkettle recipe\fR \fBdefine\fR
.TP
\fBkettle recipe\fR \fBparent\fR
.TP
\fBkettle recipe\fR \fBexists\fR
.TP
................................................................................
\fBkettle recipe\fR \fBhelp\fR
.TP
\fBkettle recipe\fR \fBrun\fR
.PP
.SH "STATUS MANAGEMENT"
The command of this layer manage the status of the currently executing
recipe and the database holding the knowledge about all executed
recipes, keyed by their name, location and relevant configuration.
This database is shared among instances of kettle during recursive
invokation.
.TP
\fBkettle status\fR \fBbegin\fR
.TP
\fBkettle status\fR \fBfail\fR
.TP
\fBkettle status\fR \fBok\fR
.TP
................................................................................
\fBkettle status\fR \fBload\fR
.TP
\fBkettle status\fR \fBclear\fR
.PP
.SH "IO VIRTUALIZATION"
This section describes the IO virtualization layer used to decouple
the higher layer's output from the actual destination, terminal or gui
log window.
.TP
\fBkettle io\fR \fBsetwidget\fR \fIw\fR
This command sets the text widget to use for output, redirecting all
output made through \fBkettle io puts\fR and \fBkettle io trace\fR
from the terminal to this widget.
.TP
\fBkettle io\fR \fBfor-gui\fR \fIscript\fR
.TP
\fBkettle io\fR \fBfor-terminal\fR \fIscript\fR
These two commands execute the script in their calling context if the
IO system is using text widget or terminal for output, respectively.
.TP
\fBkettle io\fR \fBputs\fR \fIarg\fR...
This command is an emulation of Tcl's builtin \fBputs\fR which writes
to either a terminal (default), or a text widget. The latter happens
only if such a widget was set with \fBkettle io set-widget\fR.
.sp
The full syntax of the builtin \fBputs\fR is implemented.
.sp
This redirection affects only the standard channels however,
all other channels given to the command will go to their proper files,
sockets, etc.
.TP
\fBkettle io\fR \fBtrace\fR \fItext\fR
This command is the tracing of kettle internals. It will not produce
output until \fBkettle io trace-on\fR is invoked.
The specified \fItext\fR is run through a round of substitution (in
the callers context), resolving variables and commands embedded into
it. This allows the use of brace-quoting, preventing the execution of
such embedded commands while tracing is disabled.
.TP
\fBkettle io\fR \fBtrace-on\fR
This command activates the tracing of internals, enabling
\fBkettle io trace\fR to produce output.
.TP
\fBkettle io\fR \fBanimation begin\fR
This command is the first in a group of four implementing the
foundations for text-based progress bars and the like.
.sp
When invoked it initializes the internal state for writing on
the last line of the terminal without moving into the next line. This
sets the maximum column used to \fB0\fR, and the current prefix to
the empty string.
.TP
\fBkettle io\fR \fBanimation write\fR \fItext\fR
This command writes the concatenation of the current prefix and input
\fItext\fR to the current line, clearing and then overwriting the
previous content of the same line. By writing different texts an
animation effect can be generated, with only the prefix staying
constant. The command takes care to track the largest column
characters have been written to and to clear them even if the current
string does not cover them.
.TP
\fBkettle io\fR \fBanimation indent\fR \fItext\fR
This command extends the current prefix with \fItext\fR. Nothing else
happens.
.TP
\fBkettle io\fR \fBanimation last\fR \fItext\fR
This command is the last in the group of four handling animation
effects. It first \fBwrite\fRs the \fItext\fR as usual and then
moves the terminal to the next line, making \fItext\fR the last
shown string of the animation and that which is kept shown.
.TP
\fBkettle io\fR \fItag\fR \fIscript\fR
This command activates the color named by \fItag\fR, then executes the
\fIscript\fR and lastly resets the output to the standard colors.
.sp
This means that output generated by IO commands in the script
have the activated color. Note that the command does \fInot\fR
support the nesting of color activations.
.sp
The allowed color tags are:
.RS
.TP
\fBok\fR
.TP
\fBwarn\fR
................................................................................
.TP
\fBwhite\fR
.RE
.TP
\fBkettle io\fR m\fItag\fR \fItext\fR
This command is similar to the previous, except that all color tags
are prefixed with \fBm\fR (for markup) and the argument is a string,
not a script. The string is extended with color control commands
activating and deactivating the chosen color at beginning and end, and
then returned as the result of the command.
.PP
.SH "GENERAL UTILITIES"
This, the lowest layer of the system contains general utility commands
for string processing, anonymous procedures and error handling.
.SS "ANONYMOUS PROCEDURES"
.TP
\fBlambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...?
.TP
\fBlambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...?
These commands are wrappers around Tcl 8.5's builtin \fBapply\fR
command, making the creation of anonymous procedures a bit
easier. Apply uses nested lists, the API here flattens that, matching
the API of \fBproc\fR.
.sp
The command arguments are like for \fBproc\fR, with three
exceptions.
.RS
.IP [1]
There is no procedure name. Obviously.
.IP [2]
After the procedure body we can pre-specify some or all
of the procedure arguments, i.e. perform currying.
.IP [3]
The @-variant takes the name of the \fInamespace\fR the body
will be executed in.
.RE
.PP
.SS "ERROR HANDLING"
.TP
\fBtry\fR \fIarg\fR...
This command is an implementation of Tcl 8.6's try/trap/finally
command in pure Tcl, providing forward-compatibility with 8.6 in this
respect. (Iit is just too useful when it comes to erro handling,
especially cleanup of transient things like temp files).
.sp
Syntax and semantics fully match the Tcl 8.6 command. The code
was written by Donal Fellows, it is the initial implementation of the
builtin, before it got re-implemented in C and byte-coded.
.PP
.SS "STRING PROCESSING"
.TP
\fBkettle strutil\fR \fBindent\fR \fItext\fR \fIprefix\fR
This command splits the input \fItext\fR into lines, indents each line
using the \fIprefix\fR and then returns the re-joined text.
.sp
Note that the prefix is not applied to empty lines (containing
only whitespace). Any whitespace in empty lines is actually completely
eliminated.
.TP
\fBkettle strutil\fR \fBpadl\fR \fIlist\fR
.TP
\fBkettle strutil\fR \fBpadr\fR \fIlist\fR
These two commands take a list of strings, compute the maximum length
and then pads all shorter strings to this length (using spaces),
returning the modified list. The order of the strings in the result is
not changed. The commands differ in where the padding is
applied.
.sp
\fBpadr\fR adds the spaces at the end of the string (to the
right) yielding a left-aligned result.  Whereas \fBpadl\fR adds the
spaces at the beginning of the string (to the left) yielding a
right-aligned result.
.sp
Regardless of the differences, the result is a list of strings
of the same length. Useful when having to print a table. Provide a
column of the table as input, and the result is properly aligned for
printing.
.TP
\fBkettle strutil\fR \fBreflow\fR \fItext\fR ?\fIprefix\fR?
This command strips empty header and footer lines from the input
\fItext\fR, undents it and then re-indents using the \fIprefix\fR. If
the latter is not specified it will default to 4 spaces.
.sp
The result of all the modifications is then returned as the
result of the command.
.TP
\fBkettle strutil\fR \fBundent\fR \fItext\fR
This command splits the input \fItext\fR into lines, computes longest
common prefix of whitespace over all lines, removes that prefix and
then returns the re-joined text.
.sp
The effect is an un-indenting of the lines in the \fItext\fR
which preserves the general shape of the left margin.
.sp
Note that empty lines (containing only whitespace) do not take
part in the prefix calculation. Any whitespace in empty lines is
actually completely eliminated.
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|







|







 







|







|

|



|









|







 







|

|











|









|







 







|

|







 







|







 







|

|

|







 







|


|


|



|



|






|







 







|
|
|







 







|


|


|

|



|
|
|

|
|

|



|







 







|
|
|


|




|


|









|
|








|
|








|
|







 







|


|


|




|


|


|





|



|




|



|







 







|


|



|




|


|


|




|


|
|







 







|
|


|







 







|


|


|

|



|




|


|


|



|


|




|






|

|

|



|

|

|


|


|
|





|



|




|

|

|

|

|

|
|


|




|



|

|

|





|


|

|


|





|

|


|
|


|

|


|







|


|





|


|


|



|

|







 







|


|


|

|

|




|

|



|

|



|



|
|
|
|





|



|




|

|


|
|


|


|


|


|


|



|








|




|



|
|
|
|




|
|


|
|


|
|


|


|




|
|
|




|

|


|
|

|


|


|


|


|


|


|

|






|

|

|



|
|

|


|
|

|


|






|




|




|

|


|



|



|


|

|




|





|
|



|

|



|






|







 







|













|




|





|

|



|









|







 







|

|











|









|







 







|

|



|







 







|

|







 







|




|





|

|

|
|

|



|


|
|


|
|



|



|


|

|




|

|

|


|
|



|

|



|


|
|







 







|

|



|


|

|
|

|
|


|


|


|


|




|
|
|
|
|

|

|





|


|
|






|
|
|


|

|


|

|



|
|


|




|


|


|
|


|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
...
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
...
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
...
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
...
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
...
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
...
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
...
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
...
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
...
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
...
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
...
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
...
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
...
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
....
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
....
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
....
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
....
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
....
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
....
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
....
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
'\"
'\" Generated from file 'kettle\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle \- Kettle - Core
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
\fBkettle tcl\fR
.sp
\fBkettle tclapp\fR \fIpath\fR
.sp
\fBkettle critcl3\fR
.sp
\fBkettle depends-on\fR \fIpath\fR\&.\&.\&.
.sp
\fBkettle doc-destination\fR \fIpath\fR
.sp
\fBkettle doc\fR ?\fIdocroot\fR?
.sp
\fBkettle figures\fR ?\fIfigroot\fR?
.sp
................................................................................
.sp
\fBkettle ovalidate\fR \fBboolean\fR
.sp
\fBkettle ovalidate\fR \fBlistsimple\fR
.sp
\fBkettle ovalidate\fR \fBdirectory\fR
.sp
\fBkettle ovalidate\fR \fBreadable\&.file\fR
.sp
\fBkettle ovalidate\fR \fBpath\fR
.sp
\fBkettle path\fR \fBbench-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBbindir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBcat\fR \fIpath\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBcathead\fR \fIpath\fR \fIn\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBcopy-file\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBcopy-files\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBcritcl3-package-file\fR \fIfile\fR
.sp
\fBkettle path\fR \fBdiagram-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBdoctools-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBdry-barrier\fR ?\fIdryscript\fR?
.sp
\fBkettle path\fR \fBexec\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBfixhashbang\fR \fIfile\fR \fIshell\fR
.sp
\fBkettle path\fR \fBforeach-file\fR \fIpath\fR \fIpv\fR \fIscript\fR
.sp
\fBkettle path\fR \fBgrep\fR \fIpattern\fR \fIdata\fR
.sp
................................................................................
.sp
\fBkettle path\fR \fBin\fR \fIpath\fR \fIscript\fR
.sp
\fBkettle path\fR \fBincdir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBinstall-application\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBinstall-file-group\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBinstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBinstall-script\fR \fIsrc\fR \fIdstdir\fR \fIshell\fR
.sp
\fBkettle path\fR \fBkettle-build-file\fR \fIpath\fR
.sp
\fBkettle path\fR \fBlibdir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBmandir\fR ?\fIpath\fR?
.sp
\fBkettle path\fR \fBnorm\fR \fIpath\fR
.sp
\fBkettle path\fR \fBpipe\fR \fIlv\fR \fIscript\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBrelative\fR \fIbase\fR \fIdst\fR
.sp
\fBkettle path\fR \fBrelativecwd\fR \fIdst\fR
.sp
\fBkettle path\fR \fBrelativesrc\fR \fIdst\fR
.sp
\fBkettle path\fR \fBremove-path\fR \fIbase\fR \fIpath\fR
.sp
\fBkettle path\fR \fBremove-paths\fR \fIbase\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBrgrep\fR \fIpattern\fR \fIdata\fR
.sp
\fBkettle path\fR \fBscan\fR \fIlabel\fR \fIroot\fR \fIpredicate\fR
.sp
\fBkettle path\fR \fBscript\fR
.sp
................................................................................
.sp
\fBkettle path\fR \fBtmpfile\fR ?\fIprefix\fR?
.sp
\fBkettle path\fR \fBuninstall-application\fR \fIsrc\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBuninstall-file-group\fR \fIlabel\fR \fIdstdir\fR
.sp
\fBkettle path\fR \fBuninstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle path\fR \fBwrite\fR \fIpath\fR \fIcontents\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle recipe\fR \fBdefine\fR
.sp
\fBkettle recipe\fR \fBparent\fR
.sp
\fBkettle recipe\fR \fBexists\fR
.sp
................................................................................
.sp
\fBkettle io\fR \fBsetwidget\fR \fIw\fR
.sp
\fBkettle io\fR \fBfor-gui\fR \fIscript\fR
.sp
\fBkettle io\fR \fBfor-terminal\fR \fIscript\fR
.sp
\fBkettle io\fR \fBputs\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle io\fR \fBtrace\fR \fItext\fR
.sp
\fBkettle io\fR \fBtrace-on\fR
.sp
\fBkettle io\fR \fBanimation begin\fR
.sp
................................................................................
.sp
\fBkettle io\fR \fBanimation last\fR \fItext\fR
.sp
\fBkettle io\fR \fItag\fR \fIscript\fR
.sp
\fBkettle io\fR m\fItag\fR \fItext\fR
.sp
\fBlambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR\&.\&.\&.?
.sp
\fBlambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR\&.\&.\&.?
.sp
\fBtry\fR \fIarg\fR\&.\&.\&.
.sp
\fBkettle strutil\fR \fBindent\fR \fItext\fR \fIprefix\fR
.sp
\fBkettle strutil\fR \fBpadl\fR \fIlist\fR
.sp
\fBkettle strutil\fR \fBpadr\fR \fIlist\fR
.sp
................................................................................
\fBkettle strutil\fR \fBundent\fR \fItext\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
This document is the reference to all commands provided by the kettle
package, from the user-visible declarations to the lowest utilities\&.
.PP
It is intended for both power-users wishing to write their own
high-level commands linking into the existing foundations and
developers and maintainers of kettle itself\&.
.PP
A basic user should read
\fIKettle - Application - Build Interpreter\fR
and \fIKettle - Build Declarations\fR instead\&.
.SH OVERVIEW
The high-level architecture is shown in the image below:
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build\&.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
This document is concerned with the lowest level shown, the core
kettle package itself\&. The inner boxes of that architectural box show
the parts which are user-visible, i\&.e\&. providing the DSL commands
explained in \fIKettle - Build Declarations\fR\&.
For the details we have
.PP
.PS
.nf

*critcl    <- doc, testsuite, recipes, tool, options, path, io, try
*tcl       <- doc, testsuite, recipes, path, try
................................................................................
try
lambda

.fi
.PE
.PP
In this image we now see all the components found inside of the kettle
package, their organization into layers and their dependencies\&. The
latter is actually a bit simplified, showing only the dependencies
between adjacent layers and leaving out the dependencies crossing
layers\&. Adding them would make the image quite a bit more crowded\&.
.PP
The green boxes are again the user-visible parts, either for
the build declarations\&. The rest is internal\&. Note how and that the
components found in the blue box are all dependent on each other,
i\&.e\&. these are in circular dependencies\&.
.PP
The names in the boxes directly refer to the file names
containing the code of the component, without the extension,
"\fI\&.tcl\fR"\&.
The only file not mentioned is "\fIkettle\&.tcl\fR" which is the
entrypoint to the package and sources all the others\&.
Each component C is generally served by a single ensemble command,
"\fBkettle\fR \fBC\fR"\&. The exceptions are the components exporting
the user-visible declaration commands\&. Their commands, while still
named "\fBkettle\fR \fBC\fR", are not ensembles, but the one
command in that component\&.
.PP
The following sections go through the components from the top
down to the bottom, starting with the user visible commands described
in \fIKettle - Build Declarations\fR, covering all the green boxes\&.
For the remainder:
.TP
gui
\fBGraphical Interface Support\fR
.TP
tool
\fBTool handling\fR
................................................................................
try
\fBError handling\fR
.TP
strutil
\fBString processing\fR
.PP
.PP
Not convered in the above is "\fIstandard\&.tcl\fR"\&. This file
does not export any commands to document\&. It unconditionally defines
the standard recipes instead\&. These are the recipes which are always
available, in contrast to the recipes dynamically created by the
declarations commands in response to their scanning of a package
source directory\&.
.SH "BUILD DECLARATIONS"
.TP
\fBkettle tcl\fR
This command declares the presence of one or more Tcl packages in the
package source directory\&.
.sp
The package source directory is scanned to locate
them\&. Packages are detected by finding a marker (Tcl command) of the
form
.CS


    package provide NAME VERSION

.CE
.IP
in a file, where both \fBNAME\fR and \fBVERSION\fR must be literal
strings, not commands, nor variable references\&. It is best recognized
when found alone on its line\&.
Note that files containing an \fIanti-marker\fR of the form
.CS


    package require critcl

.CE
.IP
are rejected as Tcl packages\&. Use the command \fBkettle critcl3\fR
to detect such packages, mixing Tcl and C\&.
In each accepted package file the command further looks for and
recognizes embedded pragmas of the form
.CS

# @owns: PATH
.CE
.IP
which provides kettle with information about files belonging to the
same package without directly providing it\&. This can be data files, or
other Tcl files sourced by the main package file\&.
.sp
For each detected package \fBP\fR two recipes are defined, to
install and uninstall this package, namely:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-tcl-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry\&.
.sp
Tcl packages are installed into the directory specified by
option \fB--lib-dir\fR despite technically not being binary files\&.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into\&.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR"\&.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively)\&.
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle tcl\fR,
with the proper paths\&.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself\&.
.TP
\fBkettle tclapp\fR \fIpath\fR
This command declares the presence of a Tcl script application found
at the \fIpath\fR under the package source directory\&.
.sp
If the specified application is found the command will define
two recipes to install and uninstall this application, namely:
.RS
.TP
\fBinstall-app-\fIpath\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-applications
     -> uninstall-tcl-applications
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific application up to all and sundry\&.
.sp
Script applications are installed into the directory specified
by option \fB--bin-dir\fR despite technically not being binary
files\&.
.RS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into\&.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR"\&.
.RE
.TP
\fBkettle critcl3\fR
This command declares the presence of one or more critcl-based Tcl
packages in the package source directory, mixing C and Tcl\&.
.sp
The package source directory is scanned to locate
them\&. Packages are detected by finding two markers (Tcl commands) in
the file\&. These markers are of the form
.CS


    package provide NAME VERSION

.CE
.IP
................................................................................


    package require critcl

.CE
.IP
Both \fBNAME\fR and \fBVERSION\fR must be literal strings, not
commands, nor variable references\&. They are best recognized when found
alone on their respective lines\&.
.sp
For each detected package \fBP\fR three recipes are defined, to
install and uninstall this package\&. Installation comes in two
variants, regular and debug:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
\fBdebug-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-binary-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry\&.
.sp
Critcl-based packages are installed into the directory
specified by option \fB--lib-dir\fR\&.
Critcl's choice of the target configuration to build for can be
overrriden via option \fB--target\fR\&.
Kettle's choice of which critcl application to use cane overriden by
option \fB--with-critcl3\fR, except if kettle found a
\fBcritcl\fR package and runs everything itself instead of
invoking critcl child processes\&.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into\&.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR"\&.
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code\&.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself\&.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code\&.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3\&.kit\fR",
.IP [3]
"\fIcritcl3\&.tcl\fR",
.IP [4]
"\fIcritcl3\&.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl\&.kit\fR",
.IP [7]
"\fIcritcl\&.tcl\fR", and
.IP [8]
"\fIcritcl\&.exe\fR"
.RE
.IP
found on the \fBPATH\fR\&. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application\&. In that case kettle will run everything in itself,
without invoking critcl child processes\&.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively)\&.
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle critcl3\fR,
with the proper paths\&.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself\&.
.TP
\fBkettle depends-on\fR \fIpath\fR\&.\&.\&.
This command declares that the current sources depend on the packages
in the specified directories\&. These are best specified as relative
directories and most useful in package bundles where multiple
dependent packages are managed in a single source repository\&.
.sp
The arguments can be paths to files too\&. In that case the files
are assumed to be the build declaration files of the required packages
in question\&. In case of a directory path kettle will search for the
build declaration file it needs\&.
This information is currently only used by the package-specific
"install" and "debug" recipes generated by the kettle commands
\fBkettle tcl\fR and \fBkettle critcl\fR\&.
.TP
\fBkettle doc-destination\fR \fIpath\fR
The "doc" recipe generated by the \fBkettle doc\fR command (see
below) saves the conversion results into the sub-directory specified
by option \fB--with-doc-destination\fR\&.
.sp
This command declares that the results should be put into the
specified non-standard \fIpath\fR instead of the default of
"\fIembedded\fR"\&.
To take effect it has to be run \fIbefore\fR \fBkettle doc\fR is
run\&.
\fINote\fR that the user is still able to override with by setting
\fB--with-doc-destination\fR on the command line\&.
.RS
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from\&.
.sp
This should be a relative path, which will interpreted relative
to the package source directory\&.
.sp
The default value is "\fIembedded\fR"\&.
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command\&.
.RE
.TP
\fBkettle doc\fR ?\fIdocroot\fR?
This command declares the presence of \fBdoctools\fR-based
documentation files under the directory \fIdocroot\fR, which is a path
relative to the source directory\&.
.sp
If not specified \fIdocroot\fR defaults to "\fIdoc\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The commands \fBkettle tcl\fR, \fBkettle critcl3\fR, and
\fBkettle gh-pages\fR run this command implicitly, with the default
paths\&.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before them, with the proper path\&.
.sp
The package documentation directory is scanned to locate the
documentation files\&. They are recognized by containing any of the
marker strings
.RS
.IP \(bu
"\fB[manpage_begin\fR"
.IP \(bu
"\fB--- doctools ---\fR"
.IP \(bu
"\fBtcl\&.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters\&. Possible documentation files are
rejected should they contain any of the anti-markers
.RS
.IP \(bu
"\fB--- !doctools ---\fR"
.IP \(bu
"\fB!tcl\&.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters\&. This last is necessary as doctools
include file feature allows the actual document content to start in an
include file which cannot operate without being includes from a master
file configuring it\&.
.sp
When documentation files are found the command will define
recipes to convert the documentation into manpages and HTML files,
plus recipes install the conversion results\&. The conversion results
themselves are stored as specified by \fBkettle doc-destination\fR
(see above) and associated options\&.
.RS
.TP
\fBdoc\fR
.TP
\fBinstall-doc-html\fR
.TP
\fBinstall-doc-manpages\fR
................................................................................
  uninstall
  -> uninstall-doc
     -> uninstall-doc-html
     -> uninstall-doc-manpages

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific type of documentation up to all and sundry\&.
.sp
HTML documentation is stored under the directory specified by
option \fB--html-dir\fR\&.
Manpages are stored under the directory specified by
option \fB--man-dir\fR\&.
The "doc" recipe uses the \fBdtplite\fR application to perform the
various conversions\&.
.RS
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/html\fR"\&.
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/man\fR"\&.
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing\&.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite\&.kit\fR",
"\fIdtplite\&.tcl\fR", and
"\fIdtplite\&.exe\fR"
found on the \fBPATH\fR\&.
.RE
.sp
To simplify usage the command heuristically detects
tklib/diagram based figures by means of internally calling the command
\fBkettle figures\fR with default path arguments
("\fI\fBdoc-sources\fR/figures}\fR"\&.
.sp
If the figures are placed in a non-standard location this
command has to be run before \fBkettle doc\fR, with the proper
paths\&.
.TP
\fBkettle figures\fR ?\fIfigroot\fR?
This command declares the presence of \fBdiagram\fR-based figures
under the directory \fIfigroot\fR, which is a path relative to the
source directory\&.
.sp
If not specified \fIfigroot\fR defaults to "\fIdoc/figures\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The command \fBkettle doc\fR (and indirectly \fBkettle tcl\fR and
\fBkettle critcl3\fR) runs this command implicitly, with the default
paths\&.
This means that if diagrams are stored in a non-standard location
\fBkettle figures\fR must be run explicitly before them, with the
proper path\&.
.sp
The package diagram directory is scanned to locate the diagram
files\&. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl\&.tk//DSL diagram//EN//\fR"
.RE
.IP
in their first 1024 characters\&.
.sp
When diagram files are found the command will define recipes to
convert the diagrams into PNG raster images (saved as siblings to
their source files), and to render the diagrams on a Tk canvas\&.
.RS
.TP
\fBfigures\fR
.TP
\fBshow-figures\fR
.RE
.sp
The recipes use the \fBdia\fR application (of \fBtklib\fR)
to perform the conversions, and GUI rendering\&.
.RS
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing\&.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia\&.kit\fR",
"\fIdia\&.tcl\fR", and
"\fIdia\&.exe\fR"
found on the \fBPATH\fR\&.
.RE
.TP
\fBkettle gh-pages\fR
This command declares the presence of a \fIgh-pages\fR branch in the
repository, as is used by, for example, \fIhttp://github\&.com\fR, to
manage the web-site for a project in the rpeository of the project\&.
.sp
The command confirms the presence of documentation and that the
local repository is \fBgit\fR-based\&. If neither is true nothing
done\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
It runs the command \fBkettle doc\fR command implicitly, with the
default paths, to ensure that its own check for documentation work
properly\&.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before this command, with
the proper path\&.
.sp
When the above tests pass the command will define a recipe
named \fBgh-pages\fR, which performs all the automatable steps to
copy the embedded documentation of the project into its
\fIgh-pages\fR branch\&. Afterward the checkout is left at the
\fIgh-pages\fR branch, for the user to review and commit\&. While the
last step could be automated the review cannot, making the point moot\&.
.TP
\fBkettle testsuite\fR ?\fItestroot\fR?
This command declares the presence of a \fBtcltest\fR-based
testsuite under the directory \fItestroot\fR, which is a path relative
to the source directory\&.
.sp
If not specified \fItestroot\fR defaults to "\fItests\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The commands \fBkettle tcl\fR and \fBkettle critcl3\fR) run this
command implicitly, with the default paths\&.
This means that if a testsuite is stored in a non-standard location
\fBkettle testsuite\fR must be run explicitly before them, with the
proper path\&.
.sp
The package testsuite directory is scanned to locate the test
files\&. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl\&.tk//DSL tcltest//EN//\fR"
.RE
.IP
in their first 1024 characters\&.
.sp
When testsuites are found the command will define a recipe to
run them\&. This recipe will recursively invoke the recipes "debug" (or
"install" if the former does not exist, or fails) before performing
the tests, installing the package under test (and its dependencies) in
a local directory for use by the testsuites\&. The supporting commands
provided by kettle (see \fIKettle - Testsuite Support\fR) know how
to use this\&.
.RS
.TP
\fBtest\fR
.RE
.sp
The verbosity of testsuite output to the terminal is specified
by the option \fB--log-mode\fR\&.
The ability to save testsuite output to a series of files is specified
by the option \fB--log\fR\&.
The tclsh shell used for running the testsuites is specified by option
\fB--with-shell\fR\&.
.RS
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined\&. Its value determines the
verbosity of test suite information printed to the terminal or log window\&.
.sp
The default is \fBcompact\fR\&.
.TP
\fB--log\fR path
An option for recipe 'test', if defined\&. Its value is the path "stem"
for a series of files testsuite information is saved into\&. The actual
files use the specified stem and add their specifc file extension to
it\&.
.sp
The default is the empty string, disabling the saving of
testsuite information\&.
.TP
\fB--with-shell\fR path
.RE
.PP
.SH "GRAPHICAL INTERFACE SUPPORT"
This layer contains the command for the creation of the standard
graphical interface to the system\&.
.TP
\fBkettle gui\fR \fBmake\fR
This high-level command creates a standard graphical interface
providing access to all options and defined recipes, through two tabs
in a notebook\&.
.sp
Options are handled by type specific fields, the details of
which are created by the option type definitions found under
\fBkettle ovalidate\fR, as specified in section
\fBOption Types and Validation\fR\&.
.sp
Recipes are acessible through one button per recipe\&.
.sp
Output is written to a text widget acting as a log window, in
the same tab which contains the action buttons\&.
.PP
.SH "TOOL HANDLING"
This layer contains commands to manage the declaration of a dependency
on external comands, and their use\&.
.TP
\fBkettle tool\fR \fBdeclare\fR \fInames\fR ?\fIvalidator\fR?
This command declares the need for an external tool which can have any
of the listed \fInames\fR\&.
The first element of that list is the name the tool will be known
under within kettle, also called the \fIprimary name\fR of the
tool\&.
This is the name to hand to \fBkettle tool get\fR below to retrieve
the tool's location\&.
.sp
Similarly the primary name is used to define an option named
--with-\fBname\fR, used to hold the path found by searching for the
tool on the \fBPATH\fR under its various names, and to allow the user
to override kettle's choice\&.
.sp
If \fIvalidator\fR is specified it will be treated as the body
of an anonymous procedure with a single argument \fIcmd\fR, the path
of the tool found on \fBPATH\fR and returning a boolean value telling
the caller if this path is acceptable (result == \fBtrue\fR), or
not\&. In case of the latter the system will continue searching with the
next name in \fInames\fR\&.
.TP
\fBkettle tool\fR \fBget\fR \fIname\fR
This command returns the path to the \fIname\fRd tool, assuming that
it was \fBdeclare\fRd before\&.
If no such tool is specified the command prints an error message and
aborts the execution of the current recipe and its callers\&.
.PP
.SH "RECURSIVE INVOKATIONS"
The commands of this layer enable recipes to recursively invoke other
recipes, for the current and in other packages\&.
.TP
\fBkettle\fR \fBinvoke\fR
.PP
.SH "OPTION DATABASE"
This layer manages the option database, which both holds the
configuration options, their definitions and values, as also named
shared global state\&.
.TP
\fBkettle option\fR \fBdefine\fR
.TP
\fBkettle option\fR \fBonchange\fR
.TP
\fBkettle option\fR \fBno-work-key\fR
.TP
................................................................................
\fBkettle option\fR \fBsave\fR
.TP
\fBkettle option\fR \fBload\fR
.TP
\fBkettle option\fR \fBconfig\fR
.PP
.SH "OPTION TYPES AND VALIDATION"
This layer defines the validation types usable by the options\&.
.TP
\fBkettle ovalidate\fR \fBenum\fR
.TP
\fBkettle ovalidate\fR \fBany\fR
.TP
\fBkettle ovalidate\fR \fBstring\fR
.TP
\fBkettle ovalidate\fR \fBboolean\fR
.TP
\fBkettle ovalidate\fR \fBlistsimple\fR
.TP
\fBkettle ovalidate\fR \fBdirectory\fR
.TP
\fBkettle ovalidate\fR \fBreadable\&.file\fR
.TP
\fBkettle ovalidate\fR \fBpath\fR
.PP
.SH "PATH UTILITIES"
This layer contains the commands \&.\&.\&.
.TP
\fBkettle path\fR \fBbench-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBbindir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBcat\fR \fIpath\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBcathead\fR \fIpath\fR \fIn\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBcopy-file\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBcopy-files\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBcritcl3-package-file\fR \fIfile\fR
.TP
\fBkettle path\fR \fBdiagram-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBdoctools-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBdry-barrier\fR ?\fIdryscript\fR?
.TP
\fBkettle path\fR \fBexec\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBfixhashbang\fR \fIfile\fR \fIshell\fR
.TP
\fBkettle path\fR \fBforeach-file\fR \fIpath\fR \fIpv\fR \fIscript\fR
.TP
\fBkettle path\fR \fBgrep\fR \fIpattern\fR \fIdata\fR
.TP
................................................................................
.TP
\fBkettle path\fR \fBin\fR \fIpath\fR \fIscript\fR
.TP
\fBkettle path\fR \fBincdir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBinstall-application\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBinstall-file-group\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBinstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBinstall-script\fR \fIsrc\fR \fIdstdir\fR \fIshell\fR
.TP
\fBkettle path\fR \fBkettle-build-file\fR \fIpath\fR
.TP
\fBkettle path\fR \fBlibdir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBmandir\fR ?\fIpath\fR?
.TP
\fBkettle path\fR \fBnorm\fR \fIpath\fR
.TP
\fBkettle path\fR \fBpipe\fR \fIlv\fR \fIscript\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBrelative\fR \fIbase\fR \fIdst\fR
.TP
\fBkettle path\fR \fBrelativecwd\fR \fIdst\fR
.TP
\fBkettle path\fR \fBrelativesrc\fR \fIdst\fR
.TP
\fBkettle path\fR \fBremove-path\fR \fIbase\fR \fIpath\fR
.TP
\fBkettle path\fR \fBremove-paths\fR \fIbase\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBrgrep\fR \fIpattern\fR \fIdata\fR
.TP
\fBkettle path\fR \fBscan\fR \fIlabel\fR \fIroot\fR \fIpredicate\fR
.TP
\fBkettle path\fR \fBscript\fR
.TP
................................................................................
.TP
\fBkettle path\fR \fBtmpfile\fR ?\fIprefix\fR?
.TP
\fBkettle path\fR \fBuninstall-application\fR \fIsrc\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBuninstall-file-group\fR \fIlabel\fR \fIdstdir\fR
.TP
\fBkettle path\fR \fBuninstall-file-set\fR \fIlabel\fR \fIdstdir\fR \fIarg\fR\&.\&.\&.
.TP
\fBkettle path\fR \fBwrite\fR \fIpath\fR \fIcontents\fR \fIarg\fR\&.\&.\&.
.PP
.SH "RECIPE DATABASE"
This layer contains the commands managing the database of all known
recipes, ready for execution\&.
.TP
\fBkettle recipe\fR \fBdefine\fR
.TP
\fBkettle recipe\fR \fBparent\fR
.TP
\fBkettle recipe\fR \fBexists\fR
.TP
................................................................................
\fBkettle recipe\fR \fBhelp\fR
.TP
\fBkettle recipe\fR \fBrun\fR
.PP
.SH "STATUS MANAGEMENT"
The command of this layer manage the status of the currently executing
recipe and the database holding the knowledge about all executed
recipes, keyed by their name, location and relevant configuration\&.
This database is shared among instances of kettle during recursive
invokation\&.
.TP
\fBkettle status\fR \fBbegin\fR
.TP
\fBkettle status\fR \fBfail\fR
.TP
\fBkettle status\fR \fBok\fR
.TP
................................................................................
\fBkettle status\fR \fBload\fR
.TP
\fBkettle status\fR \fBclear\fR
.PP
.SH "IO VIRTUALIZATION"
This section describes the IO virtualization layer used to decouple
the higher layer's output from the actual destination, terminal or gui
log window\&.
.TP
\fBkettle io\fR \fBsetwidget\fR \fIw\fR
This command sets the text widget to use for output, redirecting all
output made through \fBkettle io puts\fR and \fBkettle io trace\fR
from the terminal to this widget\&.
.TP
\fBkettle io\fR \fBfor-gui\fR \fIscript\fR
.TP
\fBkettle io\fR \fBfor-terminal\fR \fIscript\fR
These two commands execute the script in their calling context if the
IO system is using text widget or terminal for output, respectively\&.
.TP
\fBkettle io\fR \fBputs\fR \fIarg\fR\&.\&.\&.
This command is an emulation of Tcl's builtin \fBputs\fR which writes
to either a terminal (default), or a text widget\&. The latter happens
only if such a widget was set with \fBkettle io set-widget\fR\&.
.sp
The full syntax of the builtin \fBputs\fR is implemented\&.
.sp
This redirection affects only the standard channels however,
all other channels given to the command will go to their proper files,
sockets, etc\&.
.TP
\fBkettle io\fR \fBtrace\fR \fItext\fR
This command is the tracing of kettle internals\&. It will not produce
output until \fBkettle io trace-on\fR is invoked\&.
The specified \fItext\fR is run through a round of substitution (in
the callers context), resolving variables and commands embedded into
it\&. This allows the use of brace-quoting, preventing the execution of
such embedded commands while tracing is disabled\&.
.TP
\fBkettle io\fR \fBtrace-on\fR
This command activates the tracing of internals, enabling
\fBkettle io trace\fR to produce output\&.
.TP
\fBkettle io\fR \fBanimation begin\fR
This command is the first in a group of four implementing the
foundations for text-based progress bars and the like\&.
.sp
When invoked it initializes the internal state for writing on
the last line of the terminal without moving into the next line\&. This
sets the maximum column used to \fB0\fR, and the current prefix to
the empty string\&.
.TP
\fBkettle io\fR \fBanimation write\fR \fItext\fR
This command writes the concatenation of the current prefix and input
\fItext\fR to the current line, clearing and then overwriting the
previous content of the same line\&. By writing different texts an
animation effect can be generated, with only the prefix staying
constant\&. The command takes care to track the largest column
characters have been written to and to clear them even if the current
string does not cover them\&.
.TP
\fBkettle io\fR \fBanimation indent\fR \fItext\fR
This command extends the current prefix with \fItext\fR\&. Nothing else
happens\&.
.TP
\fBkettle io\fR \fBanimation last\fR \fItext\fR
This command is the last in the group of four handling animation
effects\&. It first \fBwrite\fRs the \fItext\fR as usual and then
moves the terminal to the next line, making \fItext\fR the last
shown string of the animation and that which is kept shown\&.
.TP
\fBkettle io\fR \fItag\fR \fIscript\fR
This command activates the color named by \fItag\fR, then executes the
\fIscript\fR and lastly resets the output to the standard colors\&.
.sp
This means that output generated by IO commands in the script
have the activated color\&. Note that the command does \fInot\fR
support the nesting of color activations\&.
.sp
The allowed color tags are:
.RS
.TP
\fBok\fR
.TP
\fBwarn\fR
................................................................................
.TP
\fBwhite\fR
.RE
.TP
\fBkettle io\fR m\fItag\fR \fItext\fR
This command is similar to the previous, except that all color tags
are prefixed with \fBm\fR (for markup) and the argument is a string,
not a script\&. The string is extended with color control commands
activating and deactivating the chosen color at beginning and end, and
then returned as the result of the command\&.
.PP
.SH "GENERAL UTILITIES"
This, the lowest layer of the system contains general utility commands
for string processing, anonymous procedures and error handling\&.
.SS "ANONYMOUS PROCEDURES"
.TP
\fBlambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR\&.\&.\&.?
.TP
\fBlambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR\&.\&.\&.?
These commands are wrappers around Tcl 8\&.5's builtin \fBapply\fR
command, making the creation of anonymous procedures a bit
easier\&. Apply uses nested lists, the API here flattens that, matching
the API of \fBproc\fR\&.
.sp
The command arguments are like for \fBproc\fR, with three
exceptions\&.
.RS
.IP [1]
There is no procedure name\&. Obviously\&.
.IP [2]
After the procedure body we can pre-specify some or all
of the procedure arguments, i\&.e\&. perform currying\&.
.IP [3]
The @-variant takes the name of the \fInamespace\fR the body
will be executed in\&.
.RE
.PP
.SS "ERROR HANDLING"
.TP
\fBtry\fR \fIarg\fR\&.\&.\&.
This command is an implementation of Tcl 8\&.6's try/trap/finally
command in pure Tcl, providing forward-compatibility with 8\&.6 in this
respect\&. (Iit is just too useful when it comes to erro handling,
especially cleanup of transient things like temp files)\&.
.sp
Syntax and semantics fully match the Tcl 8\&.6 command\&. The code
was written by Donal Fellows, it is the initial implementation of the
builtin, before it got re-implemented in C and byte-coded\&.
.PP
.SS "STRING PROCESSING"
.TP
\fBkettle strutil\fR \fBindent\fR \fItext\fR \fIprefix\fR
This command splits the input \fItext\fR into lines, indents each line
using the \fIprefix\fR and then returns the re-joined text\&.
.sp
Note that the prefix is not applied to empty lines (containing
only whitespace)\&. Any whitespace in empty lines is actually completely
eliminated\&.
.TP
\fBkettle strutil\fR \fBpadl\fR \fIlist\fR
.TP
\fBkettle strutil\fR \fBpadr\fR \fIlist\fR
These two commands take a list of strings, compute the maximum length
and then pads all shorter strings to this length (using spaces),
returning the modified list\&. The order of the strings in the result is
not changed\&. The commands differ in where the padding is
applied\&.
.sp
\fBpadr\fR adds the spaces at the end of the string (to the
right) yielding a left-aligned result\&.  Whereas \fBpadl\fR adds the
spaces at the beginning of the string (to the left) yielding a
right-aligned result\&.
.sp
Regardless of the differences, the result is a list of strings
of the same length\&. Useful when having to print a table\&. Provide a
column of the table as input, and the result is properly aligned for
printing\&.
.TP
\fBkettle strutil\fR \fBreflow\fR \fItext\fR ?\fIprefix\fR?
This command strips empty header and footer lines from the input
\fItext\fR, undents it and then re-indents using the \fIprefix\fR\&. If
the latter is not specified it will default to 4 spaces\&.
.sp
The result of all the modifications is then returned as the
result of the command\&.
.TP
\fBkettle strutil\fR \fBundent\fR \fItext\fR
This command splits the input \fItext\fR into lines, computes longest
common prefix of whitespace over all lines, removes that prefix and
then returns the re-joined text\&.
.sp
The effect is an un-indenting of the lines in the \fItext\fR
which preserves the general shape of the left margin\&.
.sp
Note that empty lines (containing only whitespace) do not take
part in the prefix calculation\&. Any whitespace in empty lines is
actually completely eliminated\&.
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_app.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_app.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_app" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_app \- Kettle - Application - Build Interpreter
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
\fBkettle\fR ?\fB-f\fR \fIbuildfile\fR? ?\fB-trace\fR? (\fIgoal\fR|\fB--option\fR \fIvalue\fR)...
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
Here we document the kettle application available to a user of kettle,
i.e. a package developer using (or wishing to use) kettle as the build
system for their code.
.PP
This application resides between the kettle core and the build
script written by the package developer, as shown in the archtectural
diagram below.
.PP
IMAGE: arch_app
.PP
For the build (declaration) commands available to build scripts
based on kettle see \fIKettle - Build Declarations\fR.
.SH "THE KETTLE APPLICATION"
The \fBkettle\fR application is the main interpreter for build
declarations. It can be used directly, or as a shell in the hash-bang
line of build files.
.PP
Its general syntax is
.TP
\fBkettle\fR ?\fB-f\fR \fIbuildfile\fR? ?\fB-trace\fR? (\fIgoal\fR|\fB--option\fR \fIvalue\fR)...
In a hash-bang line for a build file the syntax is 'kettle -f', with
the build file becoming the argument to \fB-f\fR, and the arguments
to the build file then following, starting with the optional
\fB-trace\fR.
.sp
Note: The application will look for a build file
"\fIbuild.tcl\fR" in the current working, if no build file is
specified.
.sp
Configuration options and recipes to run can be mixed on the
commandline, with the options processed first, and then the
recipes. For this to work all the options require a value.
.sp
The list of known options, help about them, and their state
after option processing can be queried through the standard recipes
\fBlist-options\fR, \fBhelp-options\fR, and
\fBshow-configuraton\fR.
.sp
The list of known recipes and help about them can be queried
through the standard recipes \fBlist-recipes\fR, and
\fBhelp-recipes\fR.
.sp
Note that the set of recipes is dynamically constructed based
on the scans of source directory made by kettle at the direction of
the build file. I.e. the options on the command line are processed
first, then the build file is used to scan the sources and initialize
the necessary recipes, at last the recipes on the command line are
run.
.sp
The application understands one dot-file for configuration,
"\fI~/.kettle/config\fR". This file is expected to contain
user-specific standard options to use. Its contents are processed as
part of the option processing, before the options found on the command
line.
For all other extensibility the user is reminded that build file are
Tcl files, with the full power of the language behind them. Which
includes the builtin command \fBsource\fR.
.sp
If no recipe is specified on the command line a standard recipe
is run. On unix platforms it is "help", whereas on windows "gui" is
used.
.PP
.SH OPTIONS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR".
.TP
\fB--color\fR boolean
The value of this configuration option determines if output is
colorized or not.
.sp
The default value is platform-dependent.
On windows the default is \fBoff\fR, disabling colorization.
On unix the default is \fBon\fR, activating colorization. Except if
it could be determined that the script's \fBstdout\fR is not a
proper terminal, then the default is \fBoff\fR.
.sp
For this last check the system attempts to use the package
\fBTclx\fR. If that package is not available then it cannot be
determined if \fBstdout\fR is a proper terminal, thus colorization
is active.
.TP
\fB--config\fR path
This is an internal option used by kettle for the communication
between parent and child instances when handling a recursive
invokation. The generated file specified as the value of the option
holds the configuration of the parent, for the child to read and use.
.TP
\fB--dry\fR boolean
The value of this configuration option determines if (un)installation
modifies the file system (\fBoff\fR) or not (\fBon\fR == dry run).
.sp
The default value is \fBoff\fR. This means that the system
will modify the file system as instructed by recipes.
.TP
\fB--exec-prefix\fR path
This configuration option specifies the path to the root directory for
all platform-dependent (binary) installation files.
.sp
The default value is "\fI\fB--prefix\fR\fR".
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/html\fR".
.TP
\fB--ignore-glob\fR list
This option specifies the set of files and directories to ignore
during directory scans, as a Tcl list of glob patterns to match.
.sp
The default value is
.RS
.IP [1]
*~
.IP [2]
_FOSSIL_
.IP [3]
.fslckout
.IP [4]
.fos
.IP [5]
.git
.IP [6]
.svn
.IP [7]
CVS
.IP [8]
.hg
.IP [9]
RCS
.IP [10]
SCCS
.IP [11]
*.bak
.IP [12]
*.bzr
.IP [13]
*.cdv
.IP [14]
*.pc
.IP [15]
_MTN
.IP [16]
_build
.IP [17]
_darcs
.IP [18]
_sgbak
.IP [19]
blib
.IP [20]
autom4te.cache
.IP [21]
cover_db
.IP [22]
~.dep
.IP [23]
~.dot
.IP [24]
~.nib
.IP [25]
~.plst
.RE
.IP
matching the special files and directories of various source code
control systems, the backup files of various editors, and the like.
.TP
\fB--include-dir\fR path
This configuration option specifies the path to the directory package
C header files will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/include\fR".
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR".
.TP
\fB--log\fR path
An option for recipe 'test', if defined. Its value is the path "stem"
for a series of files testsuite information is saved into. The actual
files use the specified stem and add their specifc file extension to
it.
.sp
The default is the empty string, disabling the saving of
testsuite information.
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined. Its value determines the
verbosity of test suite information printed to the terminal or log window.
.sp
The default is \fBcompact\fR.
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/man\fR".
.TP
\fB--prefix\fR path
This configuration option specifies the path to the root directory for
all platform-independent (non-binary) installation files.
.sp
The default value is the twice parent of the
[\fBinfo library\fR] directory of the \fBtclsh\fR used to
run the \fBkettle\fR application.
.TP
\fB--state\fR path
This is an internal option used by kettle for the communication
between parent and child instances when handling a recursive
invokation. The generated file specified as the value of the option
holds the work state of the parent, for the child to read and extend.
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself.
.TP
\fB--verbose\fR boolean
The value of this configuration option determines if tracing of system
internals is done (\fBon\fR), or not (\fBoff\fR). This is the
option equivalent of the special flag \fB-trace\fR.
.sp
The default value is \fBoff\fR, disabling tracing of internals.
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from.
.sp
This should be a relative path, which will interpreted relative
to the package source directory.
.sp
The default value is "\fIembedded\fR".
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3.kit\fR",
.IP [3]
"\fIcritcl3.tcl\fR",
.IP [4]
"\fIcritcl3.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl.kit\fR",
.IP [7]
"\fIcritcl.tcl\fR", and
.IP [8]
"\fIcritcl.exe\fR"
.RE
.IP
found on the \fBPATH\fR. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application. In that case kettle will run everything in itself,
without invoking critcl child processes.
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia.kit\fR",
"\fIdia.tcl\fR", and
"\fIdia.exe\fR"
found on the \fBPATH\fR.
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite.kit\fR",
"\fIdtplite.tcl\fR", and
"\fIdtplite.exe\fR"
found on the \fBPATH\fR.
.TP
\fB--with-shell\fR path
.PP
.SH "STANDARD RECIPES"
The following recipes are understood by \fBkettle\fR regardless of
build definitions. They are its \fIstandard\fR recipes.
.TP
\fBgui\fR
Opens a standard graphical interface.
This is the standard recipe run on windows if no recipe was
specified on the command line.
.TP
\fBhelp-options\fR
Print the help for all known options.
.TP
\fBhelp-recipes\fR
Print the help for all defined recipes.
.TP
\fBhelp\fR
The combination of the previous two recipes.
This is the standard recipe run on unix if no recipe was
specified on the command line.
.TP
\fBlist-options\fR
Print a list of all known options.
.TP
\fBlist-recipes\fR
Print a list of all defined recipes.
.TP
\fBlist\fR
The combination of the previous two recipes.
.TP
\fBnull\fR
This recipe does nothing.
It is generally only useful for kettle developers, in
combination with option \fB-trace\fR.
.TP
\fBshow-configuration\fR
Print the state of the option database after processing the
dot-file and command line settings.
.TP
\fBshow-state\fR
Print the state of various internal global settings
after processing the dot-file and command line settings.
.PP
.SH "BUILD.TCL EXAMPLE"
A simple example of a build.tcl script is that for kettle itself.
.PP
Stripping out the special code taking care of the fact that it
cannot assume to have kettle installed already this reduces to the
code below, and of that only the last two lines are relevant in terms
of build declarations. The first three are the (bourne) shell magic to
find and run the kettle application in the \fBPATH\fR environment
variable. (The actual code assumes that \fBkettle\fR is found the
working directory, again it cannot assume to be installed already).
.PP
.CS


#!/bin/sh
# -*- tcl -*- \\
exec kettle -f "$0" "${1+$@}"
kettle tcl
kettle tclapp kettle

.CE
.PP
The code asks the system to search for and handle all Tcl
script packages to be found in the directory of the "\fIbuild.tcl\fR"
file, and declares that we have a script application named
\fBkettle\fR in the same directory.
As the documentation files and figures are in the standard locations,
\fBkettle tcl\fR is allowed to handle them implicitly.
.PP
Done.
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|

|






|


|


|
|



|




|


|
|



|



|


|
|



|




|



|



|


|


|
|

|

|
|


|
|





|


|


|



|

|
|
|

|


|

|




|
|



|

|
|



|

|



|

|



|








|

|

|

|



|





|

|

|

|











|



|

|

|

|



|



|

|



|


|


|


|
|

|


|


|
|

|



|

|



|



|




|
|



|


|



|
|

|




|


|

|


|




|






|

|

|



|

|

|


|


|
|



|



|
|
|
|



|



|
|
|
|





|


|

|


|


|


|

|


|


|


|


|

|



|



|

|
|




|

|
|













|

|

|

|

|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
'\"
'\" Generated from file 'kettle_app\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_app" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_app \- Kettle - Application - Build Interpreter
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
\fBkettle\fR ?\fB-f\fR \fIbuildfile\fR? ?\fB-trace\fR? (\fIgoal\fR|\fB--option\fR \fIvalue\fR)\&.\&.\&.
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
Here we document the kettle application available to a user of kettle,
i\&.e\&. a package developer using (or wishing to use) kettle as the build
system for their code\&.
.PP
This application resides between the kettle core and the build
script written by the package developer, as shown in the archtectural
diagram below\&.
.PP
IMAGE: arch_app
.PP
For the build (declaration) commands available to build scripts
based on kettle see \fIKettle - Build Declarations\fR\&.
.SH "THE KETTLE APPLICATION"
The \fBkettle\fR application is the main interpreter for build
declarations\&. It can be used directly, or as a shell in the hash-bang
line of build files\&.
.PP
Its general syntax is
.TP
\fBkettle\fR ?\fB-f\fR \fIbuildfile\fR? ?\fB-trace\fR? (\fIgoal\fR|\fB--option\fR \fIvalue\fR)\&.\&.\&.
In a hash-bang line for a build file the syntax is 'kettle -f', with
the build file becoming the argument to \fB-f\fR, and the arguments
to the build file then following, starting with the optional
\fB-trace\fR\&.
.sp
Note: The application will look for a build file
"\fIbuild\&.tcl\fR" in the current working, if no build file is
specified\&.
.sp
Configuration options and recipes to run can be mixed on the
commandline, with the options processed first, and then the
recipes\&. For this to work all the options require a value\&.
.sp
The list of known options, help about them, and their state
after option processing can be queried through the standard recipes
\fBlist-options\fR, \fBhelp-options\fR, and
\fBshow-configuraton\fR\&.
.sp
The list of known recipes and help about them can be queried
through the standard recipes \fBlist-recipes\fR, and
\fBhelp-recipes\fR\&.
.sp
Note that the set of recipes is dynamically constructed based
on the scans of source directory made by kettle at the direction of
the build file\&. I\&.e\&. the options on the command line are processed
first, then the build file is used to scan the sources and initialize
the necessary recipes, at last the recipes on the command line are
run\&.
.sp
The application understands one dot-file for configuration,
"\fI~/\&.kettle/config\fR"\&. This file is expected to contain
user-specific standard options to use\&. Its contents are processed as
part of the option processing, before the options found on the command
line\&.
For all other extensibility the user is reminded that build file are
Tcl files, with the full power of the language behind them\&. Which
includes the builtin command \fBsource\fR\&.
.sp
If no recipe is specified on the command line a standard recipe
is run\&. On unix platforms it is "help", whereas on windows "gui" is
used\&.
.PP
.SH OPTIONS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into\&.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR"\&.
.TP
\fB--color\fR boolean
The value of this configuration option determines if output is
colorized or not\&.
.sp
The default value is platform-dependent\&.
On windows the default is \fBoff\fR, disabling colorization\&.
On unix the default is \fBon\fR, activating colorization\&. Except if
it could be determined that the script's \fBstdout\fR is not a
proper terminal, then the default is \fBoff\fR\&.
.sp
For this last check the system attempts to use the package
\fBTclx\fR\&. If that package is not available then it cannot be
determined if \fBstdout\fR is a proper terminal, thus colorization
is active\&.
.TP
\fB--config\fR path
This is an internal option used by kettle for the communication
between parent and child instances when handling a recursive
invokation\&. The generated file specified as the value of the option
holds the configuration of the parent, for the child to read and use\&.
.TP
\fB--dry\fR boolean
The value of this configuration option determines if (un)installation
modifies the file system (\fBoff\fR) or not (\fBon\fR == dry run)\&.
.sp
The default value is \fBoff\fR\&. This means that the system
will modify the file system as instructed by recipes\&.
.TP
\fB--exec-prefix\fR path
This configuration option specifies the path to the root directory for
all platform-dependent (binary) installation files\&.
.sp
The default value is "\fI\fB--prefix\fR\fR"\&.
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/html\fR"\&.
.TP
\fB--ignore-glob\fR list
This option specifies the set of files and directories to ignore
during directory scans, as a Tcl list of glob patterns to match\&.
.sp
The default value is
.RS
.IP [1]
*~
.IP [2]
_FOSSIL_
.IP [3]
\&.fslckout
.IP [4]
\&.fos
.IP [5]
\&.git
.IP [6]
\&.svn
.IP [7]
CVS
.IP [8]
\&.hg
.IP [9]
RCS
.IP [10]
SCCS
.IP [11]
*\&.bak
.IP [12]
*\&.bzr
.IP [13]
*\&.cdv
.IP [14]
*\&.pc
.IP [15]
_MTN
.IP [16]
_build
.IP [17]
_darcs
.IP [18]
_sgbak
.IP [19]
blib
.IP [20]
autom4te\&.cache
.IP [21]
cover_db
.IP [22]
~\&.dep
.IP [23]
~\&.dot
.IP [24]
~\&.nib
.IP [25]
~\&.plst
.RE
.IP
matching the special files and directories of various source code
control systems, the backup files of various editors, and the like\&.
.TP
\fB--include-dir\fR path
This configuration option specifies the path to the directory package
C header files will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/include\fR"\&.
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into\&.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR"\&.
.TP
\fB--log\fR path
An option for recipe 'test', if defined\&. Its value is the path "stem"
for a series of files testsuite information is saved into\&. The actual
files use the specified stem and add their specifc file extension to
it\&.
.sp
The default is the empty string, disabling the saving of
testsuite information\&.
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined\&. Its value determines the
verbosity of test suite information printed to the terminal or log window\&.
.sp
The default is \fBcompact\fR\&.
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/man\fR"\&.
.TP
\fB--prefix\fR path
This configuration option specifies the path to the root directory for
all platform-independent (non-binary) installation files\&.
.sp
The default value is the twice parent of the
[\fBinfo library\fR] directory of the \fBtclsh\fR used to
run the \fBkettle\fR application\&.
.TP
\fB--state\fR path
This is an internal option used by kettle for the communication
between parent and child instances when handling a recursive
invokation\&. The generated file specified as the value of the option
holds the work state of the parent, for the child to read and extend\&.
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code\&.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself\&.
.TP
\fB--verbose\fR boolean
The value of this configuration option determines if tracing of system
internals is done (\fBon\fR), or not (\fBoff\fR)\&. This is the
option equivalent of the special flag \fB-trace\fR\&.
.sp
The default value is \fBoff\fR, disabling tracing of internals\&.
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from\&.
.sp
This should be a relative path, which will interpreted relative
to the package source directory\&.
.sp
The default value is "\fIembedded\fR"\&.
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command\&.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code\&.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3\&.kit\fR",
.IP [3]
"\fIcritcl3\&.tcl\fR",
.IP [4]
"\fIcritcl3\&.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl\&.kit\fR",
.IP [7]
"\fIcritcl\&.tcl\fR", and
.IP [8]
"\fIcritcl\&.exe\fR"
.RE
.IP
found on the \fBPATH\fR\&. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application\&. In that case kettle will run everything in itself,
without invoking critcl child processes\&.
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing\&.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia\&.kit\fR",
"\fIdia\&.tcl\fR", and
"\fIdia\&.exe\fR"
found on the \fBPATH\fR\&.
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing\&.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite\&.kit\fR",
"\fIdtplite\&.tcl\fR", and
"\fIdtplite\&.exe\fR"
found on the \fBPATH\fR\&.
.TP
\fB--with-shell\fR path
.PP
.SH "STANDARD RECIPES"
The following recipes are understood by \fBkettle\fR regardless of
build definitions\&. They are its \fIstandard\fR recipes\&.
.TP
\fBgui\fR
Opens a standard graphical interface\&.
This is the standard recipe run on windows if no recipe was
specified on the command line\&.
.TP
\fBhelp-options\fR
Print the help for all known options\&.
.TP
\fBhelp-recipes\fR
Print the help for all defined recipes\&.
.TP
\fBhelp\fR
The combination of the previous two recipes\&.
This is the standard recipe run on unix if no recipe was
specified on the command line\&.
.TP
\fBlist-options\fR
Print a list of all known options\&.
.TP
\fBlist-recipes\fR
Print a list of all defined recipes\&.
.TP
\fBlist\fR
The combination of the previous two recipes\&.
.TP
\fBnull\fR
This recipe does nothing\&.
It is generally only useful for kettle developers, in
combination with option \fB-trace\fR\&.
.TP
\fBshow-configuration\fR
Print the state of the option database after processing the
dot-file and command line settings\&.
.TP
\fBshow-state\fR
Print the state of various internal global settings
after processing the dot-file and command line settings\&.
.PP
.SH "BUILD\&.TCL EXAMPLE"
A simple example of a build\&.tcl script is that for kettle itself\&.
.PP
Stripping out the special code taking care of the fact that it
cannot assume to have kettle installed already this reduces to the
code below, and of that only the last two lines are relevant in terms
of build declarations\&. The first three are the (bourne) shell magic to
find and run the kettle application in the \fBPATH\fR environment
variable\&. (The actual code assumes that \fBkettle\fR is found the
working directory, again it cannot assume to be installed already)\&.
.PP
.CS


#!/bin/sh
# -*- tcl -*- \\
exec kettle -f "$0" "${1+$@}"
kettle tcl
kettle tclapp kettle

.CE
.PP
The code asks the system to search for and handle all Tcl
script packages to be found in the directory of the "\fIbuild\&.tcl\fR"
file, and declares that we have a script application named
\fBkettle\fR in the same directory\&.
As the documentation files and figures are in the standard locations,
\fBkettle tcl\fR is allowed to handle them implicitly\&.
.PP
Done\&.
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_changes.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_changes.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_changes" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_changes \- Kettle Changes
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
This document provides an overview of the changes \fBkettle\fR
underwent from version to version.
.SH CHANGES
.SS "CHANGES FOR VERSION 1"
This is the first release of kettle, package and application.
The changes therefore describe the initial features of the system.
.PP
In detail:
.IP [1]
Kettle requires Tcl 8.5 or higher. Tcl 8.4 or less is not
supported.
.IP [2]
The application \fBkettle\fR provides standard setup to run
a file "\fIbuild.tcl\fR", specified either explicitly via option
\fB-f\fR, or implicitly (current working directory).
.sp
This application can be used as the interpreter of a build
declaration file as well. In that case option \fB-f\fR must
be part of the \fB#!\fR-line.
.IP [3]
The core package \fBkettle\fR manages a database of recipes,
and provides standard code invoked automatically after the processing
of the build declarations to show help or run a recipe specified
on the command line.
.sp
Standard recipes provide introspection into the list of known
recipes, and display of general and recipe-specific help.
.IP [4]
Various utility and support packages providing the commands for
the build declarations, and implementation helpers.
.sp
Currently supported are
.RS
.IP [1]
(Un)installation of pure Tcl packages.
.IP [2]
(Un)installation of Tcl script applications.
.IP [3]
(Un)installation of \fBcritcl\fR-based Tcl+C packages.
.IP [4]
(Re)generation and (un)installation of (tcllib) doctools based manpages.
.IP [5]
(Re)generation and display of (tklib) diagram based figures.
.IP [6]
Execution of \fBtcltest\fR-based testsuites.
.IP [7]
Execution of \fBtclbench\fR-based benchmarks.
.RE
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|






|


|


|


|
|



|
|


|
|


|
|




|


|


|




|

|

|

|

|

|

|




|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
'\"
'\" Generated from file 'kettle_changes\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_changes" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_changes \- Kettle Changes
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
This document provides an overview of the changes \fBkettle\fR
underwent from version to version\&.
.SH CHANGES
.SS "CHANGES FOR VERSION 1"
This is the first release of kettle, package and application\&.
The changes therefore describe the initial features of the system\&.
.PP
In detail:
.IP [1]
Kettle requires Tcl 8\&.5 or higher\&. Tcl 8\&.4 or less is not
supported\&.
.IP [2]
The application \fBkettle\fR provides standard setup to run
a file "\fIbuild\&.tcl\fR", specified either explicitly via option
\fB-f\fR, or implicitly (current working directory)\&.
.sp
This application can be used as the interpreter of a build
declaration file as well\&. In that case option \fB-f\fR must
be part of the \fB#!\fR-line\&.
.IP [3]
The core package \fBkettle\fR manages a database of recipes,
and provides standard code invoked automatically after the processing
of the build declarations to show help or run a recipe specified
on the command line\&.
.sp
Standard recipes provide introspection into the list of known
recipes, and display of general and recipe-specific help\&.
.IP [4]
Various utility and support packages providing the commands for
the build declarations, and implementation helpers\&.
.sp
Currently supported are
.RS
.IP [1]
(Un)installation of pure Tcl packages\&.
.IP [2]
(Un)installation of Tcl script applications\&.
.IP [3]
(Un)installation of \fBcritcl\fR-based Tcl+C packages\&.
.IP [4]
(Re)generation and (un)installation of (tcllib) doctools based manpages\&.
.IP [5]
(Re)generation and display of (tklib) diagram based figures\&.
.IP [6]
Execution of \fBtcltest\fR-based testsuites\&.
.IP [7]
Execution of \fBtclbench\fR-based benchmarks\&.
.RE
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_devguide.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
...
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
...
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_devguide.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_devguide" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_devguide \- Kettle - The Developer's Guide
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
This document is a guide for developers working on Kettle,
i.e. maintainers fixing bugs, extending the functionality of
application or package, etc.
.PP
Users of kettle wishing to write their own high-level commands
linking into the existing foundations should read the
\fIKettle - Core\fR document instead, as that is the reference
manpage to the whole functionality available to them, and likely
enough to get going.
.PP
Please read
.IP [1]
\fIKettle - License\fR,
.IP [2]
\fIKettle - How To Get The Sources\fR, and
.IP [3]
\fIKettle - The Installer's Guide\fR
.PP
first, if that was not done already.
.PP
Here we assume that the sources are already available in a directory
of your choice, and that you not only know how to build and install
them, but also have all the necessary requisites to actually do
so. The guide to the sources in particular also explains which source
code management system is used, where to find it, how to set it up,
etc.
.SH "DEVELOPING FOR KETTLE"
.SS ARCHITECTURE
The high-level architecture is shown in the image below:
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
This document is concerned with the lowest level shown, the core
kettle package itself. The inner boxes of that architectural box show
the parts which are user-visible, i.e. providing the DSL commands
explained in \fIKettle - Build Declarations\fR.
For the details we have
.PP
.PS
.nf

*critcl    <- doc, testsuite, recipes, tool, options, path, io, try
*tcl       <- doc, testsuite, recipes, path, try
................................................................................
try
lambda

.fi
.PE
.PP
In this image we now see all the components found inside of the kettle
package, their organization into layers and their dependencies. The
latter is actually a bit simplified, showing only the dependencies
between adjacent layers and leaving out the dependencies crossing
layers. Adding them would make the image quite a bit more crowded.
.PP
The green boxes are again the user-visible parts, either for
the build declarations. The rest is internal. Note how and that the
components found in the blue box are all dependent on each other,
i.e. these are in circular dependencies.
.PP
The names in the boxes directly refer to the file names
containing the code of the component, without the extension,
"\fI.tcl\fR".
The only file not mentioned is "\fIkettle.tcl\fR" which is the
entrypoint to the package and sources all the others.
.PP
More information about the functionality made available by each
component is found in \fIKettle - Core\fR, the reference to all
commands.
.SS "DIRECTORY STRUCTURE"
.TP
Helpers
.TP
Documentation
.RS
.TP
"\fIdoc/\fR"
This directory contains the documentation sources. The texts are written
in \fIdoctools\fR format, whereas the figures are a mixture of TeX (math
formulas), and tklib's \fBdia\fR(gram) package and application.
.TP
"\fIembedded/\fR"
This directory contains the documentation converted to regular manpages
(nroff) and HTML.
It is called embedded because these files, while derived, are part of the
fossil repository, i.e. embedded into it. This enables fossil to access
and display these files when serving the repositories' web interface.
The "Command Reference" link at
\fIhttp://chiselapp.com/user/andreas_kupries/repository/Kettle/home\fR
is, for example, accessing the generated HTML.
.RE
.TP
Package Code, General structure
See the second image in section \fBArchitecture\fR, and the
associated explanations.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|





|


|


|
|





|









|




|

|







|







 







|
|
|







 







|


|


|

|



|
|
|



|








|

|



|

|
|

|
|




|



|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
...
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
...
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
'\"
'\" Generated from file 'kettle_devguide\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_devguide" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_devguide \- Kettle - The Developer's Guide
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
This document is a guide for developers working on Kettle,
i\&.e\&. maintainers fixing bugs, extending the functionality of
application or package, etc\&.
.PP
Users of kettle wishing to write their own high-level commands
linking into the existing foundations should read the
\fIKettle - Core\fR document instead, as that is the reference
manpage to the whole functionality available to them, and likely
enough to get going\&.
.PP
Please read
.IP [1]
\fIKettle - License\fR,
.IP [2]
\fIKettle - How To Get The Sources\fR, and
.IP [3]
\fIKettle - The Installer's Guide\fR
.PP
first, if that was not done already\&.
.PP
Here we assume that the sources are already available in a directory
of your choice, and that you not only know how to build and install
them, but also have all the necessary requisites to actually do
so\&. The guide to the sources in particular also explains which source
code management system is used, where to find it, how to set it up,
etc\&.
.SH "DEVELOPING FOR KETTLE"
.SS ARCHITECTURE
The high-level architecture is shown in the image below:
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build\&.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
This document is concerned with the lowest level shown, the core
kettle package itself\&. The inner boxes of that architectural box show
the parts which are user-visible, i\&.e\&. providing the DSL commands
explained in \fIKettle - Build Declarations\fR\&.
For the details we have
.PP
.PS
.nf

*critcl    <- doc, testsuite, recipes, tool, options, path, io, try
*tcl       <- doc, testsuite, recipes, path, try
................................................................................
try
lambda

.fi
.PE
.PP
In this image we now see all the components found inside of the kettle
package, their organization into layers and their dependencies\&. The
latter is actually a bit simplified, showing only the dependencies
between adjacent layers and leaving out the dependencies crossing
layers\&. Adding them would make the image quite a bit more crowded\&.
.PP
The green boxes are again the user-visible parts, either for
the build declarations\&. The rest is internal\&. Note how and that the
components found in the blue box are all dependent on each other,
i\&.e\&. these are in circular dependencies\&.
.PP
The names in the boxes directly refer to the file names
containing the code of the component, without the extension,
"\fI\&.tcl\fR"\&.
The only file not mentioned is "\fIkettle\&.tcl\fR" which is the
entrypoint to the package and sources all the others\&.
.PP
More information about the functionality made available by each
component is found in \fIKettle - Core\fR, the reference to all
commands\&.
.SS "DIRECTORY STRUCTURE"
.TP
Helpers
.TP
Documentation
.RS
.TP
"\fIdoc/\fR"
This directory contains the documentation sources\&. The texts are written
in \fIdoctools\fR format, whereas the figures are a mixture of TeX (math
formulas), and tklib's \fBdia\fR(gram) package and application\&.
.TP
"\fIembedded/\fR"
This directory contains the documentation converted to regular manpages
(nroff) and HTML\&.
It is called embedded because these files, while derived, are part of the
fossil repository, i\&.e\&. embedded into it\&. This enables fossil to access
and display these files when serving the repositories' web interface\&.
The "Command Reference" link at
\fIhttp://chiselapp\&.com/user/andreas_kupries/repository/Kettle/home\fR
is, for example, accessing the generated HTML\&.
.RE
.TP
Package Code, General structure
See the second image in section \fBArchitecture\fR, and the
associated explanations\&.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_dsl.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
...
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
...
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
...
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
...
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
...
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
...
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_dsl.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_dsl" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_dsl \- Kettle - Build Declarations
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
\fBkettle tcl\fR
.sp
\fBkettle tclapp\fR \fIpath\fR
.sp
\fBkettle critcl3\fR
.sp
\fBkettle depends-on\fR \fIpath\fR...
.sp
\fBkettle doc-destination\fR \fIpath\fR
.sp
\fBkettle doc\fR ?\fIdocroot\fR?
.sp
\fBkettle figures\fR ?\fIfigroot\fR?
.sp
................................................................................
\fBkettle testsuite\fR ?\fItestroot\fR?
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
Here we document the build (declaration) commands available to a user
of kettle, i.e. a package developer using (or wishing to use) kettle
as the build system for their code.
.PP
These commands are provided by the kettle core, as shown in the
archtectural diagram below.
.PP
IMAGE: arch_core
.SH "BUILD COMMANDS"
.TP
\fBkettle tcl\fR
This command declares the presence of one or more Tcl packages in the
package source directory.
.sp
The package source directory is scanned to locate
them. Packages are detected by finding a marker (Tcl command) of the
form
.CS


    package provide NAME VERSION

.CE
.IP
in a file, where both \fBNAME\fR and \fBVERSION\fR must be literal
strings, not commands, nor variable references. It is best recognized
when found alone on its line.
Note that files containing an \fIanti-marker\fR of the form
.CS


    package require critcl

.CE
.IP
are rejected as Tcl packages. Use the command \fBkettle critcl3\fR
to detect such packages, mixing Tcl and C.
In each accepted package file the command further looks for and
recognizes embedded pragmas of the form
.CS

# @owns: PATH
.CE
.IP
which provides kettle with information about files belonging to the
same package without directly providing it. This can be data files, or
other Tcl files sourced by the main package file.
.sp
For each detected package \fBP\fR two recipes are defined, to
install and uninstall this package, namely:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-tcl-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry.
.sp
Tcl packages are installed into the directory specified by
option \fB--lib-dir\fR despite technically not being binary files.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR".
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively).
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle tcl\fR,
with the proper paths.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself.
.TP
\fBkettle tclapp\fR \fIpath\fR
This command declares the presence of a Tcl script application found
at the \fIpath\fR under the package source directory.
.sp
If the specified application is found the command will define
two recipes to install and uninstall this application, namely:
.RS
.TP
\fBinstall-app-\fIpath\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-applications
     -> uninstall-tcl-applications
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific application up to all and sundry.
.sp
Script applications are installed into the directory specified
by option \fB--bin-dir\fR despite technically not being binary
files.
.RS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR".
.RE
.TP
\fBkettle critcl3\fR
This command declares the presence of one or more critcl-based Tcl
packages in the package source directory, mixing C and Tcl.
.sp
The package source directory is scanned to locate
them. Packages are detected by finding two markers (Tcl commands) in
the file. These markers are of the form
.CS


    package provide NAME VERSION

.CE
.IP
................................................................................


    package require critcl

.CE
.IP
Both \fBNAME\fR and \fBVERSION\fR must be literal strings, not
commands, nor variable references. They are best recognized when found
alone on their respective lines.
.sp
For each detected package \fBP\fR three recipes are defined, to
install and uninstall this package. Installation comes in two
variants, regular and debug:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
\fBdebug-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-binary-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry.
.sp
Critcl-based packages are installed into the directory
specified by option \fB--lib-dir\fR.
Critcl's choice of the target configuration to build for can be
overrriden via option \fB--target\fR.
Kettle's choice of which critcl application to use cane overriden by
option \fB--with-critcl3\fR, except if kettle found a
\fBcritcl\fR package and runs everything itself instead of
invoking critcl child processes.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR".
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3.kit\fR",
.IP [3]
"\fIcritcl3.tcl\fR",
.IP [4]
"\fIcritcl3.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl.kit\fR",
.IP [7]
"\fIcritcl.tcl\fR", and
.IP [8]
"\fIcritcl.exe\fR"
.RE
.IP
found on the \fBPATH\fR. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application. In that case kettle will run everything in itself,
without invoking critcl child processes.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively).
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle critcl3\fR,
with the proper paths.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself.
.TP
\fBkettle depends-on\fR \fIpath\fR...
This command declares that the current sources depend on the packages
in the specified directories. These are best specified as relative
directories and most useful in package bundles where multiple
dependent packages are managed in a single source repository.
.sp
The arguments can be paths to files too. In that case the files
are assumed to be the build declaration files of the required packages
in question. In case of a directory path kettle will search for the
build declaration file it needs.
This information is currently only used by the package-specific
"install" and "debug" recipes generated by the kettle commands
\fBkettle tcl\fR and \fBkettle critcl\fR.
.TP
\fBkettle doc-destination\fR \fIpath\fR
The "doc" recipe generated by the \fBkettle doc\fR command (see
below) saves the conversion results into the sub-directory specified
by option \fB--with-doc-destination\fR.
.sp
This command declares that the results should be put into the
specified non-standard \fIpath\fR instead of the default of
"\fIembedded\fR".
To take effect it has to be run \fIbefore\fR \fBkettle doc\fR is
run.
\fINote\fR that the user is still able to override with by setting
\fB--with-doc-destination\fR on the command line.
.RS
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from.
.sp
This should be a relative path, which will interpreted relative
to the package source directory.
.sp
The default value is "\fIembedded\fR".
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command.
.RE
.TP
\fBkettle doc\fR ?\fIdocroot\fR?
This command declares the presence of \fBdoctools\fR-based
documentation files under the directory \fIdocroot\fR, which is a path
relative to the source directory.
.sp
If not specified \fIdocroot\fR defaults to "\fIdoc\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The commands \fBkettle tcl\fR, \fBkettle critcl3\fR, and
\fBkettle gh-pages\fR run this command implicitly, with the default
paths.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before them, with the proper path.
.sp
The package documentation directory is scanned to locate the
documentation files. They are recognized by containing any of the
marker strings
.RS
.IP \(bu
"\fB[manpage_begin\fR"
.IP \(bu
"\fB--- doctools ---\fR"
.IP \(bu
"\fBtcl.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters. Possible documentation files are
rejected should they contain any of the anti-markers
.RS
.IP \(bu
"\fB--- !doctools ---\fR"
.IP \(bu
"\fB!tcl.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters. This last is necessary as doctools
include file feature allows the actual document content to start in an
include file which cannot operate without being includes from a master
file configuring it.
.sp
When documentation files are found the command will define
recipes to convert the documentation into manpages and HTML files,
plus recipes install the conversion results. The conversion results
themselves are stored as specified by \fBkettle doc-destination\fR
(see above) and associated options.
.RS
.TP
\fBdoc\fR
.TP
\fBinstall-doc-html\fR
.TP
\fBinstall-doc-manpages\fR
................................................................................
  uninstall
  -> uninstall-doc
     -> uninstall-doc-html
     -> uninstall-doc-manpages

.CE
.sp
The extended recipes may be created by this process. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific type of documentation up to all and sundry.
.sp
HTML documentation is stored under the directory specified by
option \fB--html-dir\fR.
Manpages are stored under the directory specified by
option \fB--man-dir\fR.
The "doc" recipe uses the \fBdtplite\fR application to perform the
various conversions.
.RS
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/html\fR".
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into.
.sp
The default value is "\fI\fB--prefix\fR/man\fR".
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite.kit\fR",
"\fIdtplite.tcl\fR", and
"\fIdtplite.exe\fR"
found on the \fBPATH\fR.
.RE
.sp
To simplify usage the command heuristically detects
tklib/diagram based figures by means of internally calling the command
\fBkettle figures\fR with default path arguments
("\fI\fBdoc-sources\fR/figures}\fR".
.sp
If the figures are placed in a non-standard location this
command has to be run before \fBkettle doc\fR, with the proper
paths.
.TP
\fBkettle figures\fR ?\fIfigroot\fR?
This command declares the presence of \fBdiagram\fR-based figures
under the directory \fIfigroot\fR, which is a path relative to the
source directory.
.sp
If not specified \fIfigroot\fR defaults to "\fIdoc/figures\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The command \fBkettle doc\fR (and indirectly \fBkettle tcl\fR and
\fBkettle critcl3\fR) runs this command implicitly, with the default
paths.
This means that if diagrams are stored in a non-standard location
\fBkettle figures\fR must be run explicitly before them, with the
proper path.
.sp
The package diagram directory is scanned to locate the diagram
files. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl.tk//DSL diagram//EN//\fR"
.RE
.IP
in their first 1024 characters.
.sp
When diagram files are found the command will define recipes to
convert the diagrams into PNG raster images (saved as siblings to
their source files), and to render the diagrams on a Tk canvas.
.RS
.TP
\fBfigures\fR
.TP
\fBshow-figures\fR
.RE
.sp
The recipes use the \fBdia\fR application (of \fBtklib\fR)
to perform the conversions, and GUI rendering.
.RS
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia.kit\fR",
"\fIdia.tcl\fR", and
"\fIdia.exe\fR"
found on the \fBPATH\fR.
.RE
.TP
\fBkettle gh-pages\fR
This command declares the presence of a \fIgh-pages\fR branch in the
repository, as is used by, for example, \fIhttp://github.com\fR, to
manage the web-site for a project in the rpeository of the project.
.sp
The command confirms the presence of documentation and that the
local repository is \fBgit\fR-based. If neither is true nothing
done.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
It runs the command \fBkettle doc\fR command implicitly, with the
default paths, to ensure that its own check for documentation work
properly.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before this command, with
the proper path.
.sp
When the above tests pass the command will define a recipe
named \fBgh-pages\fR, which performs all the automatable steps to
copy the embedded documentation of the project into its
\fIgh-pages\fR branch. Afterward the checkout is left at the
\fIgh-pages\fR branch, for the user to review and commit. While the
last step could be automated the review cannot, making the point moot.
.TP
\fBkettle testsuite\fR ?\fItestroot\fR?
This command declares the presence of a \fBtcltest\fR-based
testsuite under the directory \fItestroot\fR, which is a path relative
to the source directory.
.sp
If not specified \fItestroot\fR defaults to "\fItests\fR".
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect. Every invokation after that is
ignored.
The commands \fBkettle tcl\fR and \fBkettle critcl3\fR) run this
command implicitly, with the default paths.
This means that if a testsuite is stored in a non-standard location
\fBkettle testsuite\fR must be run explicitly before them, with the
proper path.
.sp
The package testsuite directory is scanned to locate the test
files. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl.tk//DSL tcltest//EN//\fR"
.RE
.IP
in their first 1024 characters.
.sp
When testsuites are found the command will define a recipe to
run them. This recipe will recursively invoke the recipes "debug" (or
"install" if the former does not exist, or fails) before performing
the tests, installing the package under test (and its dependencies) in
a local directory for use by the testsuites. The supporting commands
provided by kettle (see \fIKettle - Testsuite Support\fR) know how
to use this.
.RS
.TP
\fBtest\fR
.RE
.sp
The verbosity of testsuite output to the terminal is specified
by the option \fB--log-mode\fR.
The ability to save testsuite output to a series of files is specified
by the option \fB--log\fR.
The tclsh shell used for running the testsuites is specified by option
\fB--with-shell\fR.
.RS
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined. Its value determines the
verbosity of test suite information printed to the terminal or log window.
.sp
The default is \fBcompact\fR.
.TP
\fB--log\fR path
An option for recipe 'test', if defined. Its value is the path "stem"
for a series of files testsuite information is saved into. The actual
files use the specified stem and add their specifc file extension to
it.
.sp
The default is the empty string, disabling the saving of
testsuite information.
.TP
\fB--with-shell\fR path
.RE
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|







|







 







|


|


|
|


|






|


|









|
|








|
|








|
|







 







|


|


|




|


|


|





|



|




|



|







 







|


|



|




|


|


|




|


|
|







 







|
|


|







 







|


|


|

|



|




|


|


|



|


|




|






|

|

|



|

|

|


|


|
|





|



|




|

|

|

|

|

|
|


|




|



|

|

|





|


|

|


|





|

|


|
|


|

|


|







|


|





|


|


|



|

|







 







|


|


|

|

|




|

|



|

|



|



|
|
|
|





|



|




|

|


|
|


|


|


|


|


|



|








|




|



|
|
|
|




|
|


|
|


|
|


|


|




|
|
|




|

|


|
|

|


|


|


|


|


|


|

|






|

|

|



|
|

|


|
|

|


|





|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
...
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
...
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
...
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
...
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
...
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
...
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
'\"
'\" Generated from file 'kettle_dsl\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_dsl" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_dsl \- Kettle - Build Declarations
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
\fBkettle tcl\fR
.sp
\fBkettle tclapp\fR \fIpath\fR
.sp
\fBkettle critcl3\fR
.sp
\fBkettle depends-on\fR \fIpath\fR\&.\&.\&.
.sp
\fBkettle doc-destination\fR \fIpath\fR
.sp
\fBkettle doc\fR ?\fIdocroot\fR?
.sp
\fBkettle figures\fR ?\fIfigroot\fR?
.sp
................................................................................
\fBkettle testsuite\fR ?\fItestroot\fR?
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
Here we document the build (declaration) commands available to a user
of kettle, i\&.e\&. a package developer using (or wishing to use) kettle
as the build system for their code\&.
.PP
These commands are provided by the kettle core, as shown in the
archtectural diagram below\&.
.PP
IMAGE: arch_core
.SH "BUILD COMMANDS"
.TP
\fBkettle tcl\fR
This command declares the presence of one or more Tcl packages in the
package source directory\&.
.sp
The package source directory is scanned to locate
them\&. Packages are detected by finding a marker (Tcl command) of the
form
.CS


    package provide NAME VERSION

.CE
.IP
in a file, where both \fBNAME\fR and \fBVERSION\fR must be literal
strings, not commands, nor variable references\&. It is best recognized
when found alone on its line\&.
Note that files containing an \fIanti-marker\fR of the form
.CS


    package require critcl

.CE
.IP
are rejected as Tcl packages\&. Use the command \fBkettle critcl3\fR
to detect such packages, mixing Tcl and C\&.
In each accepted package file the command further looks for and
recognizes embedded pragmas of the form
.CS

# @owns: PATH
.CE
.IP
which provides kettle with information about files belonging to the
same package without directly providing it\&. This can be data files, or
other Tcl files sourced by the main package file\&.
.sp
For each detected package \fBP\fR two recipes are defined, to
install and uninstall this package, namely:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-tcl-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry\&.
.sp
Tcl packages are installed into the directory specified by
option \fB--lib-dir\fR despite technically not being binary files\&.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into\&.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR"\&.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively)\&.
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle tcl\fR,
with the proper paths\&.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself\&.
.TP
\fBkettle tclapp\fR \fIpath\fR
This command declares the presence of a Tcl script application found
at the \fIpath\fR under the package source directory\&.
.sp
If the specified application is found the command will define
two recipes to install and uninstall this application, namely:
.RS
.TP
\fBinstall-app-\fIpath\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-applications
     -> uninstall-tcl-applications
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific application up to all and sundry\&.
.sp
Script applications are installed into the directory specified
by option \fB--bin-dir\fR despite technically not being binary
files\&.
.RS
.TP
\fB--bin-dir\fR path
This configuration option specifies the path to the directory
applications (binary and script) will be installed into\&.
.sp
The default value is the directory of the \fBtclsh\fR used
to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/bin\fR"\&.
.RE
.TP
\fBkettle critcl3\fR
This command declares the presence of one or more critcl-based Tcl
packages in the package source directory, mixing C and Tcl\&.
.sp
The package source directory is scanned to locate
them\&. Packages are detected by finding two markers (Tcl commands) in
the file\&. These markers are of the form
.CS


    package provide NAME VERSION

.CE
.IP
................................................................................


    package require critcl

.CE
.IP
Both \fBNAME\fR and \fBVERSION\fR must be literal strings, not
commands, nor variable references\&. They are best recognized when found
alone on their respective lines\&.
.sp
For each detected package \fBP\fR three recipes are defined, to
install and uninstall this package\&. Installation comes in two
variants, regular and debug:
.RS
.TP
\fBinstall-package-\fBP\fR\fR
.TP
\fBdebug-package-\fBP\fR\fR
.TP
................................................................................
  uninstall
  -> uninstall-packages
     -> uninstall-binary-packages
        -> uninstall-app-$path

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific package up to all and sundry\&.
.sp
Critcl-based packages are installed into the directory
specified by option \fB--lib-dir\fR\&.
Critcl's choice of the target configuration to build for can be
overrriden via option \fB--target\fR\&.
Kettle's choice of which critcl application to use cane overriden by
option \fB--with-critcl3\fR, except if kettle found a
\fBcritcl\fR package and runs everything itself instead of
invoking critcl child processes\&.
.RS
.TP
\fB--lib-dir\fR path
This configuration option specifies the path to the directory packages
(binary and script) will be installed into\&.
.sp
The default value is the [\fBinfo library\fR] directory
of the \fBtclsh\fR used to run the \fBkettle\fR application\&.
.sp
If the option \fB--exec-prefix\fR is modified the default
value changes to "\fI\fB--exec-prefix\fR/lib\fR"\&.
.TP
\fB--target\fR string
The value of this option is the target name \fBcritcl\fR should use
to build C code\&.
.sp
The default value is the empty string, leaving the choice of
target to \fBcritcl\fR itself\&.
.TP
\fB--with-critcl3\fR path
This configuration option specifies the path to the tool
\fBcritcl3\fR for the compilation and installation of critcl-based
C code\&.
.sp
The default value is the path to the first of
.RS
.IP [1]
"\fIcritcl3\fR",
.IP [2]
"\fIcritcl3\&.kit\fR",
.IP [3]
"\fIcritcl3\&.tcl\fR",
.IP [4]
"\fIcritcl3\&.exe\fR",
.IP [5]
"\fIcritcl\fR",
.IP [6]
"\fIcritcl\&.kit\fR",
.IP [7]
"\fIcritcl\&.tcl\fR", and
.IP [8]
"\fIcritcl\&.exe\fR"
.RE
.IP
found on the \fBPATH\fR\&. None of these matter however should the
system find the package \fBcritcl\fR version 3 or higher among the
packages known to the \fBtclsh\fR running the \fBkettle\fR
application\&. In that case kettle will run everything in itself,
without invoking critcl child processes\&.
.RE
.sp
To simplify usage the command heuristically detects
documentation and testsuites by means of internally calling the
commands \fBkettle doc\fR and \fBkettle testsuite\fR with default
path arguments ("\fIdoc\fR" and "\fItests\fR" respectively)\&.
.sp
If documentation and/or testsuite are placed in non-standard
locations these commands have to be run before \fBkettle critcl3\fR,
with the proper paths\&.
.sp
If dependencies have been specified, via
\fBkettle depends-on\fR, the package specific install and debug
recipes will recusively invoke install or debug on them before
building the package itself\&.
.TP
\fBkettle depends-on\fR \fIpath\fR\&.\&.\&.
This command declares that the current sources depend on the packages
in the specified directories\&. These are best specified as relative
directories and most useful in package bundles where multiple
dependent packages are managed in a single source repository\&.
.sp
The arguments can be paths to files too\&. In that case the files
are assumed to be the build declaration files of the required packages
in question\&. In case of a directory path kettle will search for the
build declaration file it needs\&.
This information is currently only used by the package-specific
"install" and "debug" recipes generated by the kettle commands
\fBkettle tcl\fR and \fBkettle critcl\fR\&.
.TP
\fBkettle doc-destination\fR \fIpath\fR
The "doc" recipe generated by the \fBkettle doc\fR command (see
below) saves the conversion results into the sub-directory specified
by option \fB--with-doc-destination\fR\&.
.sp
This command declares that the results should be put into the
specified non-standard \fIpath\fR instead of the default of
"\fIembedded\fR"\&.
To take effect it has to be run \fIbefore\fR \fBkettle doc\fR is
run\&.
\fINote\fR that the user is still able to override with by setting
\fB--with-doc-destination\fR on the command line\&.
.RS
.TP
\fB--with-doc-destination\fR path
This configuration option specifies the path to the directory the
generated documentation should be placed into for the documentation
installa recipes to pick up from\&.
.sp
This should be a relative path, which will interpreted relative
to the package source directory\&.
.sp
The default value is "\fIembedded\fR"\&.
.sp
A build declaration file can override this default with the
\fBkettle doc-destination\fR command\&.
.RE
.TP
\fBkettle doc\fR ?\fIdocroot\fR?
This command declares the presence of \fBdoctools\fR-based
documentation files under the directory \fIdocroot\fR, which is a path
relative to the source directory\&.
.sp
If not specified \fIdocroot\fR defaults to "\fIdoc\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The commands \fBkettle tcl\fR, \fBkettle critcl3\fR, and
\fBkettle gh-pages\fR run this command implicitly, with the default
paths\&.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before them, with the proper path\&.
.sp
The package documentation directory is scanned to locate the
documentation files\&. They are recognized by containing any of the
marker strings
.RS
.IP \(bu
"\fB[manpage_begin\fR"
.IP \(bu
"\fB--- doctools ---\fR"
.IP \(bu
"\fBtcl\&.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters\&. Possible documentation files are
rejected should they contain any of the anti-markers
.RS
.IP \(bu
"\fB--- !doctools ---\fR"
.IP \(bu
"\fB!tcl\&.tk//DSL doctools//EN//\fR"
.RE
.IP
in their first 1024 characters\&. This last is necessary as doctools
include file feature allows the actual document content to start in an
include file which cannot operate without being includes from a master
file configuring it\&.
.sp
When documentation files are found the command will define
recipes to convert the documentation into manpages and HTML files,
plus recipes install the conversion results\&. The conversion results
themselves are stored as specified by \fBkettle doc-destination\fR
(see above) and associated options\&.
.RS
.TP
\fBdoc\fR
.TP
\fBinstall-doc-html\fR
.TP
\fBinstall-doc-manpages\fR
................................................................................
  uninstall
  -> uninstall-doc
     -> uninstall-doc-html
     -> uninstall-doc-manpages

.CE
.sp
The extended recipes may be created by this process\&. As other
declarations create similar trees these get merged together, enabling
a user to install parts of the sources at various levels of specifity,
from just a specific type of documentation up to all and sundry\&.
.sp
HTML documentation is stored under the directory specified by
option \fB--html-dir\fR\&.
Manpages are stored under the directory specified by
option \fB--man-dir\fR\&.
The "doc" recipe uses the \fBdtplite\fR application to perform the
various conversions\&.
.RS
.TP
\fB--html-dir\fR path
This configuration option specifies the path to the directory package
documentation in HTML format will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/html\fR"\&.
.TP
\fB--man-dir\fR path
This configuration option specifies the path to the directory package
documentation (manpages, in *roff format) will be installed into\&.
.sp
The default value is "\fI\fB--prefix\fR/man\fR"\&.
.TP
\fB--with-dtplite\fR path
This configuration option specifies the path to the tool
\fBdtplite\fR for doctools-based documentation processing\&.
.sp
The default value is the path to the first of
"\fIdtplite\fR",
"\fIdtplite\&.kit\fR",
"\fIdtplite\&.tcl\fR", and
"\fIdtplite\&.exe\fR"
found on the \fBPATH\fR\&.
.RE
.sp
To simplify usage the command heuristically detects
tklib/diagram based figures by means of internally calling the command
\fBkettle figures\fR with default path arguments
("\fI\fBdoc-sources\fR/figures}\fR"\&.
.sp
If the figures are placed in a non-standard location this
command has to be run before \fBkettle doc\fR, with the proper
paths\&.
.TP
\fBkettle figures\fR ?\fIfigroot\fR?
This command declares the presence of \fBdiagram\fR-based figures
under the directory \fIfigroot\fR, which is a path relative to the
source directory\&.
.sp
If not specified \fIfigroot\fR defaults to "\fIdoc/figures\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The command \fBkettle doc\fR (and indirectly \fBkettle tcl\fR and
\fBkettle critcl3\fR) runs this command implicitly, with the default
paths\&.
This means that if diagrams are stored in a non-standard location
\fBkettle figures\fR must be run explicitly before them, with the
proper path\&.
.sp
The package diagram directory is scanned to locate the diagram
files\&. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl\&.tk//DSL diagram//EN//\fR"
.RE
.IP
in their first 1024 characters\&.
.sp
When diagram files are found the command will define recipes to
convert the diagrams into PNG raster images (saved as siblings to
their source files), and to render the diagrams on a Tk canvas\&.
.RS
.TP
\fBfigures\fR
.TP
\fBshow-figures\fR
.RE
.sp
The recipes use the \fBdia\fR application (of \fBtklib\fR)
to perform the conversions, and GUI rendering\&.
.RS
.TP
\fB--with-dia\fR path
This configuration option specifies the path to the tool
\fBdia\fR for tklib/diagram-based diagram processing\&.
.sp
The default value is the path to the first of
"\fIdia\fR",
"\fIdia\&.kit\fR",
"\fIdia\&.tcl\fR", and
"\fIdia\&.exe\fR"
found on the \fBPATH\fR\&.
.RE
.TP
\fBkettle gh-pages\fR
This command declares the presence of a \fIgh-pages\fR branch in the
repository, as is used by, for example, \fIhttp://github\&.com\fR, to
manage the web-site for a project in the rpeository of the project\&.
.sp
The command confirms the presence of documentation and that the
local repository is \fBgit\fR-based\&. If neither is true nothing
done\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
It runs the command \fBkettle doc\fR command implicitly, with the
default paths, to ensure that its own check for documentation work
properly\&.
This means that if documentation is stored in a non-standard location
\fBkettle doc\fR must be run explicitly before this command, with
the proper path\&.
.sp
When the above tests pass the command will define a recipe
named \fBgh-pages\fR, which performs all the automatable steps to
copy the embedded documentation of the project into its
\fIgh-pages\fR branch\&. Afterward the checkout is left at the
\fIgh-pages\fR branch, for the user to review and commit\&. While the
last step could be automated the review cannot, making the point moot\&.
.TP
\fBkettle testsuite\fR ?\fItestroot\fR?
This command declares the presence of a \fBtcltest\fR-based
testsuite under the directory \fItestroot\fR, which is a path relative
to the source directory\&.
.sp
If not specified \fItestroot\fR defaults to "\fItests\fR"\&.
.sp
While this command can be invoked multiple times, only the
first invokation will have an effect\&. Every invokation after that is
ignored\&.
The commands \fBkettle tcl\fR and \fBkettle critcl3\fR) run this
command implicitly, with the default paths\&.
This means that if a testsuite is stored in a non-standard location
\fBkettle testsuite\fR must be run explicitly before them, with the
proper path\&.
.sp
The package testsuite directory is scanned to locate the test
files\&. They are recognized by containing the marker string
.RS
.IP \(bu
"\fBtcl\&.tk//DSL tcltest//EN//\fR"
.RE
.IP
in their first 1024 characters\&.
.sp
When testsuites are found the command will define a recipe to
run them\&. This recipe will recursively invoke the recipes "debug" (or
"install" if the former does not exist, or fails) before performing
the tests, installing the package under test (and its dependencies) in
a local directory for use by the testsuites\&. The supporting commands
provided by kettle (see \fIKettle - Testsuite Support\fR) know how
to use this\&.
.RS
.TP
\fBtest\fR
.RE
.sp
The verbosity of testsuite output to the terminal is specified
by the option \fB--log-mode\fR\&.
The ability to save testsuite output to a series of files is specified
by the option \fB--log\fR\&.
The tclsh shell used for running the testsuites is specified by option
\fB--with-shell\fR\&.
.RS
.TP
\fB--log-mode\fR compact|full
An option for recipe 'test', if defined\&. Its value determines the
verbosity of test suite information printed to the terminal or log window\&.
.sp
The default is \fBcompact\fR\&.
.TP
\fB--log\fR path
An option for recipe 'test', if defined\&. Its value is the path "stem"
for a series of files testsuite information is saved into\&. The actual
files use the specified stem and add their specifc file extension to
it\&.
.sp
The default is the empty string, disabling the saving of
testsuite information\&.
.TP
\fB--with-shell\fR path
.RE
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_installer.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
...
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
...
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529






530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548




549












































550
551

552
553
554

555
556
557
558
559
560

561
562
563
564
565
566
567
568
...
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_installer.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_install_guide" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_install_guide \- Kettle - The Installer's Guide
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
The audience of this document is anyone wishing to build the
packages, for either themselves, or others.
.PP
For a developer intending to extend or modify the packages we
additionally provide
.IP [1]
\fIKettle - License\fR.
.IP [2]
\fIKettle - The Developer's Guide\fR.
.PP
.PP
Please read \fIKettle - How To Get The Sources\fR first, if that was
not done already. Here we assume that the sources are already
available in a directory of your choice.
.PP
.SH REQUISITES
Before Kettle can be build and used a number of requisites must and/or
should be installed. These are:
.IP [1]
The scripting language Tcl.
This requisite is mandatory.
For details see \fBTcl\fR.
.IP [2]
The package \fBtcltest\fR.
This requisite is optional.
For details see \fBtcltest\fR.
.IP [3]
The package \fBTclx\fR.
This requisite is optional.
For details see \fBTclx\fR.
.IP [4]
The packages \fBTk\fR, \fBwidget::scrolledwindow\fR,
\fBwidget::listsimple\fR, and \fBwidget::dialog\fR.
These requisites are optional.
For details see \fBTk\fR and \fBTklib\fR.
.PP
This list assumes that the machine where Kettle is to be installed is
essentially clean. Of course, if parts of the dependencies listed
below are already installed the associated steps can be skipped. It is
still recommended to read their sections though, to validate that the
dependencies they talk about are indeed installed.
.SS TCL
As we are building a Tcl package and application it should be pretty
much obvious that a working installation of Tcl itself is needed, and
I will not belabor the point.
.PP
Out of the many possibilites use whatever you are comfortable
with, as long as it provides Tcl 8.5, or higher.
This may be a Tcl installation provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself.
.PP
Myself, I used (and still use)
\fIActiveState's\fR [http://www.activestate.com]
ActiveTcl 8.5 distribution during development, as I am most familiar
with it.
.PP
\fI(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them).\fR
.PP
This distribution can be found at
\fIhttp://www.activestate.com/activetcl\fR. Retrieve the archive of
ActiveTcl 8.5 for your platform and install it as directed by
ActiveState.
.PP
Assuming that ActiveTcl got installed I usually run the command
.CS


    teacup update

.CE
to install all packages ActiveState provides, and the kitchensink, as
the distribution itself usually contains only the most important set
of packages. This ensures that the dependencies for Kettle are all
present, and more.
.PP
If that is not your liking you have to read the other sections
about Kettle's dependencies to determine the exact set of packages
required, and install only these using
.CS


    teacup install $packagename

.CE
.PP
Both \fBteacup\fR commands above assume that ActiveState's
TEApot repository at \fIhttp://teapot.activestate.com\fR is in the
list of repositories accessible to \fBteacup\fR. This is automatically
ensured for the ActiveTcl distribution. Others may have to run
.CS


    teacup archive add http://teapot.activestate.com

.CE
to make this happen.
.PP
For those wishing to build and install Tcl on their own, the
relevant sources can be found at
.TP
Tcl
\fIhttp://core.tcl.tk/tcl/\fR
.PP
together with the necessary instructions on how to build it.
.PP
If there are problems with building, installing, or using Tcl
please file a bug against Tcl, or the vendor of your distribution, and
not Kettle.
.SS TCLX
The \fBTclx\fR package is an optional requisite of Kettle.
If it is not installed/available to Kettle it will continue to work,
with features depending on Tclx disabled.
.PP
The only feature using \fBTclx\fR is the colorization of
output, or rather, the code determining if Kettle should produce
colorized output by default, or not.
.PP
Without \fBTclx\fR kettle will (on unix platforms) always
produce colorized output by default. With \fBTclx\fR available
kettle will use it to check if \fBstdout\fR is connected to a proper
terminal and disable colorized output by default if not.
.PP
Now that enough information is available to decide whether Tclx
should be used in your environment or not, the information on how to
get the package.
.PP
Out of the many possibilites for getting Tclx (OS vendor,
os-independent vendor, building from sources) use whatever you are
comfortable with.
.PP
For myself, I am most comfortable with using
\fIActiveState's\fR [http://www.activestate.com]
ActiveTcl distribution and TEApot.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it.
.PP
Assuming that ActiveTcl got installed running the command
.CS


    teacup install Tclx

................................................................................
will install Tclx for your platform, if you have not done the more inclusive
.CS


    teacup update

.CE
to get everything and the kitchensink.
.PP
For those wishing to build and install Tclx on their own, the
relevant sources can be found at
.TP
Tclx
\fIhttp://sourceforge.net/projects/tclx\fR
.PP
together with the necessary instructions on how to build it.
.PP
If there are problems with building, installing, or using Tclx
please file a bug against Tclx, or the vendor of your distribution,
and not Kettle.
.SS TK
Kettle's "gui" recipe requires Tk, obviously, and three packages found
in Tklib (see next section). If Tk or the other packages are not
installed the "gui" recipe cannot be used, and attempting to do so
will fail.
.PP
Beyond that however the rest of Kettle will be fully
functional.
.PP
Out of the many possibilites for getting Tk use whatever you
are comfortable with, as long as it provides Tk 8.5, or higher (we use
the themed widgets, and Tcl 8.5 is our base).
This may be a Tk package provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself.
.PP
Myself, I used (and still use)
\fIActiveState's\fR [http://www.activestate.com]
ActiveTcl 8.5 distribution during development, as I am most familiar
with it.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it.
.PP
Assuming that ActiveTcl got installed Tk will be installed as
well.
.PP
For or those wishing to build and install Tk on their own, the
relevant sources can be found at
.TP
Tk
\fIhttp://core.tcl.tk/tk/\fR
.PP
together with the necessary instructions on how to build it.
.PP
If there are problems with building, installing, or using Tk
please file a bug against Tk, or the vendor of your distribution, and
not Kettle.
.SS TKLIB
Kettle's "gui" recipe requires the following three packages found in
Tklib. If Tk or these packages are not installed the "gui" recipe
cannot be used, and attempting to do so will fail.
.IP [1]
\fBwidget::scrolledwindow\fR
.IP [2]
\fBwidget::listsimple\fR
.IP [3]
\fBwidget::dialog\fR
.PP
.PP
Beyond that however the rest of Kettle will be fully
functional.
.PP
Out of the many possibilites for getting Tclx (OS vendor,
os-independent vendor, building from sources) use whatever you are
comfortable with.
Well, mostly. The package \fBwidget::listsimple\fR currently
exists only in the CVS repository of Tklib (location at the end of the
section), and in ActiveState's TEApot.
.PP
For myself, I am most comfortable with using
\fIActiveState's\fR [http://www.activestate.com]
ActiveTcl distribution and TEApot.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it.
.PP
Assuming that ActiveTcl got installed running the commands
.CS


    teacup install widget::scrolledwindow
    teacup install widget::listsimple
................................................................................
inclusive
.CS


    teacup update

.CE
to get everything and the kitchensink.
.PP
For those wishing to build and install Tklib on their own, the
relevant sources can be found at
.TP
Tcllib/Tklib
\fIhttp://sourceforge.net/projects/tcllib\fR
.PP
together with the necessary instructions on how to build it.
.PP
If there are problems with building, installing, or using Tklib
and its packages please file a bug against Tklib, or the vendor of
your distribution, and not Kettle.
.SS TCLTEST
Kettle's "test" recipe requires the \fBtcltest\fR package.  If
this package is not installed the "test" recipe cannot be used, and
attempting to do so will fail.
.PP
Note however that the sources of tcltest come with a source
distribution of Tcl and the package should always be installed
together with Tcl itself.
.PP
If there are problems with using tcltest please file a bug
against Tcl, or the vendor of your Tcl distribution, and not Kettle.
.SH "BUILD & INSTALLATION"






To install Kettle simply run
.CS


    /path/to/tclsh8.5 /path/to/kettle/build.tcl install

.CE
where "\fI/path/to/tclsh8.5\fR" is the tclsh of your Tcl installation, and
"\fI/path/to/kettle\fR" the location of the Kettle sources on your system.
.PP
This will build the package and application and then places them into
directories where the \fBtclsh8.5\fR will find them. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the \fBPATH\fR.
.PP
On Windows you can invoke the file "\fIbuild.tcl\fR" with a
double-click.  This will pop up a small graphical interface for
entering the destination and performing the installation. This
handling of a double-click is restricted to Windows only however.




.PP












































On unix the same GUI is acessible by invoking "\fIbuild.tcl\fR" using
\fBgui\fR instead of \fBinstall\fR in the example above.

.PP
To get help about the methods of "\fIbuild.tcl\fR", and their complete
syntax, invoke "\fIbuild.tcl\fR" with argument \fBhelp\fR, i.e., like

.CS


    /path/to/tclsh8.5 /path/to/kettle/build.tcl help

.CE

Other methods for gfetting various types of help are:
.IP [1]
help-recipes
.IP [2]
help-options
.IP [3]
help
.IP [4]
................................................................................
.IP [6]
list
.IP [7]
show-configuration
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|





|


|


|




|

|



|
|



|

|
|
|

|
|
|

|
|
|


|
|
|


|
|

|



|


|


|


|
|
|

|


|
|
|










|
|












|
|
|



|


|





|

|



|

|

|



|


|

|



|



|


|
|


|







 







|





|

|



|


|

|


|


|
|


|


|
|
|


|


|





|

|



|


|
|









|



|
|

|


|
|


|







 







|





|

|



|

|

|



|


|
|
>
>
>
>
>
>




|


|
|


|

|

<
<
<
<
>
>
>
>

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

|
|
>



|


>
|







 







|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
...
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581




582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631

632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
...
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
'\"
'\" Generated from file 'kettle_installer\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_install_guide" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_install_guide \- Kettle - The Installer's Guide
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
The audience of this document is anyone wishing to build the
packages, for either themselves, or others\&.
.PP
For a developer intending to extend or modify the packages we
additionally provide
.IP [1]
\fIKettle - License\fR\&.
.IP [2]
\fIKettle - The Developer's Guide\fR\&.
.PP
.PP
Please read \fIKettle - How To Get The Sources\fR first, if that was
not done already\&. Here we assume that the sources are already
available in a directory of your choice\&.
.PP
.SH REQUISITES
Before Kettle can be build and used a number of requisites must and/or
should be installed\&. These are:
.IP [1]
The scripting language Tcl\&.
This requisite is mandatory\&.
For details see \fBTcl\fR\&.
.IP [2]
The package \fBtcltest\fR\&.
This requisite is optional\&.
For details see \fBtcltest\fR\&.
.IP [3]
The package \fBTclx\fR\&.
This requisite is optional\&.
For details see \fBTclx\fR\&.
.IP [4]
The packages \fBTk\fR, \fBwidget::scrolledwindow\fR,
\fBwidget::listsimple\fR, and \fBwidget::dialog\fR\&.
These requisites are optional\&.
For details see \fBTk\fR and \fBTklib\fR\&.
.PP
This list assumes that the machine where Kettle is to be installed is
essentially clean\&. Of course, if parts of the dependencies listed
below are already installed the associated steps can be skipped\&. It is
still recommended to read their sections though, to validate that the
dependencies they talk about are indeed installed\&.
.SS TCL
As we are building a Tcl package and application it should be pretty
much obvious that a working installation of Tcl itself is needed, and
I will not belabor the point\&.
.PP
Out of the many possibilites use whatever you are comfortable
with, as long as it provides Tcl 8\&.5, or higher\&.
This may be a Tcl installation provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself\&.
.PP
Myself, I used (and still use)
\fIActiveState's\fR [http://www\&.activestate\&.com]
ActiveTcl 8\&.5 distribution during development, as I am most familiar
with it\&.
.PP
\fI(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them)\&.\fR
.PP
This distribution can be found at
\fIhttp://www\&.activestate\&.com/activetcl\fR\&. Retrieve the archive of
ActiveTcl 8\&.5 for your platform and install it as directed by
ActiveState\&.
.PP
Assuming that ActiveTcl got installed I usually run the command
.CS


    teacup update

.CE
to install all packages ActiveState provides, and the kitchensink, as
the distribution itself usually contains only the most important set
of packages\&. This ensures that the dependencies for Kettle are all
present, and more\&.
.PP
If that is not your liking you have to read the other sections
about Kettle's dependencies to determine the exact set of packages
required, and install only these using
.CS


    teacup install $packagename

.CE
.PP
Both \fBteacup\fR commands above assume that ActiveState's
TEApot repository at \fIhttp://teapot\&.activestate\&.com\fR is in the
list of repositories accessible to \fBteacup\fR\&. This is automatically
ensured for the ActiveTcl distribution\&. Others may have to run
.CS


    teacup archive add http://teapot\&.activestate\&.com

.CE
to make this happen\&.
.PP
For those wishing to build and install Tcl on their own, the
relevant sources can be found at
.TP
Tcl
\fIhttp://core\&.tcl\&.tk/tcl/\fR
.PP
together with the necessary instructions on how to build it\&.
.PP
If there are problems with building, installing, or using Tcl
please file a bug against Tcl, or the vendor of your distribution, and
not Kettle\&.
.SS TCLX
The \fBTclx\fR package is an optional requisite of Kettle\&.
If it is not installed/available to Kettle it will continue to work,
with features depending on Tclx disabled\&.
.PP
The only feature using \fBTclx\fR is the colorization of
output, or rather, the code determining if Kettle should produce
colorized output by default, or not\&.
.PP
Without \fBTclx\fR kettle will (on unix platforms) always
produce colorized output by default\&. With \fBTclx\fR available
kettle will use it to check if \fBstdout\fR is connected to a proper
terminal and disable colorized output by default if not\&.
.PP
Now that enough information is available to decide whether Tclx
should be used in your environment or not, the information on how to
get the package\&.
.PP
Out of the many possibilites for getting Tclx (OS vendor,
os-independent vendor, building from sources) use whatever you are
comfortable with\&.
.PP
For myself, I am most comfortable with using
\fIActiveState's\fR [http://www\&.activestate\&.com]
ActiveTcl distribution and TEApot\&.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it\&.
.PP
Assuming that ActiveTcl got installed running the command
.CS


    teacup install Tclx

................................................................................
will install Tclx for your platform, if you have not done the more inclusive
.CS


    teacup update

.CE
to get everything and the kitchensink\&.
.PP
For those wishing to build and install Tclx on their own, the
relevant sources can be found at
.TP
Tclx
\fIhttp://sourceforge\&.net/projects/tclx\fR
.PP
together with the necessary instructions on how to build it\&.
.PP
If there are problems with building, installing, or using Tclx
please file a bug against Tclx, or the vendor of your distribution,
and not Kettle\&.
.SS TK
Kettle's "gui" recipe requires Tk, obviously, and three packages found
in Tklib (see next section)\&. If Tk or the other packages are not
installed the "gui" recipe cannot be used, and attempting to do so
will fail\&.
.PP
Beyond that however the rest of Kettle will be fully
functional\&.
.PP
Out of the many possibilites for getting Tk use whatever you
are comfortable with, as long as it provides Tk 8\&.5, or higher (we use
the themed widgets, and Tcl 8\&.5 is our base)\&.
This may be a Tk package provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself\&.
.PP
Myself, I used (and still use)
\fIActiveState's\fR [http://www\&.activestate\&.com]
ActiveTcl 8\&.5 distribution during development, as I am most familiar
with it\&.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it\&.
.PP
Assuming that ActiveTcl got installed Tk will be installed as
well\&.
.PP
For or those wishing to build and install Tk on their own, the
relevant sources can be found at
.TP
Tk
\fIhttp://core\&.tcl\&.tk/tk/\fR
.PP
together with the necessary instructions on how to build it\&.
.PP
If there are problems with building, installing, or using Tk
please file a bug against Tk, or the vendor of your distribution, and
not Kettle\&.
.SS TKLIB
Kettle's "gui" recipe requires the following three packages found in
Tklib\&. If Tk or these packages are not installed the "gui" recipe
cannot be used, and attempting to do so will fail\&.
.IP [1]
\fBwidget::scrolledwindow\fR
.IP [2]
\fBwidget::listsimple\fR
.IP [3]
\fBwidget::dialog\fR
.PP
.PP
Beyond that however the rest of Kettle will be fully
functional\&.
.PP
Out of the many possibilites for getting Tclx (OS vendor,
os-independent vendor, building from sources) use whatever you are
comfortable with\&.
Well, mostly\&. The package \fBwidget::listsimple\fR currently
exists only in the CVS repository of Tklib (location at the end of the
section), and in ActiveState's TEApot\&.
.PP
For myself, I am most comfortable with using
\fIActiveState's\fR [http://www\&.activestate\&.com]
ActiveTcl distribution and TEApot\&.
.PP
See the previous section (\fBTcl\fR) for disclosure and
information on how to get it\&.
.PP
Assuming that ActiveTcl got installed running the commands
.CS


    teacup install widget::scrolledwindow
    teacup install widget::listsimple
................................................................................
inclusive
.CS


    teacup update

.CE
to get everything and the kitchensink\&.
.PP
For those wishing to build and install Tklib on their own, the
relevant sources can be found at
.TP
Tcllib/Tklib
\fIhttp://sourceforge\&.net/projects/tcllib\fR
.PP
together with the necessary instructions on how to build it\&.
.PP
If there are problems with building, installing, or using Tklib
and its packages please file a bug against Tklib, or the vendor of
your distribution, and not Kettle\&.
.SS TCLTEST
Kettle's "test" recipe requires the \fBtcltest\fR package\&.  If
this package is not installed the "test" recipe cannot be used, and
attempting to do so will fail\&.
.PP
Note however that the sources of tcltest come with a source
distribution of Tcl and the package should always be installed
together with Tcl itself\&.
.PP
If there are problems with using tcltest please file a bug
against Tcl, or the vendor of your Tcl distribution, and not Kettle\&.
.SH "BUILD & INSTALLATION INSTRUCTIONS"
.SS "BUILD & INSTALLATION (UNIX)"
This section describes the actions required to install Kettle on Unix
systems (Linux, BSD, and related, including OS X)\&.
If you have to install Kettle on a Windows machine see section
\fBBuild & Installation (Windows)\fR instead\&.
.PP
To install Kettle simply run
.CS


    /path/to/tclsh8\&.5 /path/to/kettle/build\&.tcl install

.CE
where "\fI/path/to/tclsh8\&.5\fR" is the tclsh of your Tcl installation, and
"\fI/path/to/kettle\fR" the location of the Kettle sources on your system\&.
.PP
This will build the package and application and then places them into
directories where the \fBtclsh8\&.5\fR will find them\&. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the \fBPATH\fR\&.
.PP




The build system provides a small GUI for those not comfortable with
the command line\&.
This GUI is accessible by invoking "\fIbuild\&.tcl\fR" without any
arguments\&.
.PP
To get help about the methods of "\fIbuild\&.tcl\fR", and their complete
syntax, invoke "\fIbuild\&.tcl\fR" with argument \fBhelp\fR, i\&.e\&.,
like
.CS


    /path/to/tclsh8\&.5 /path/to/kettle/build\&.tcl help

.CE
.SS "BUILD & INSTALLATION (WINDOWS)"
This section describes the actions required to install Kettle on Windows(tm)
systems\&.
If you have to install Kettle on a Unix machine (Linux, BSD, and
related, including OS X) see section
\fBBuild & Installation (Unix)\fR instead\&.
.PP
To install Kettle simply run
.CS


    /path/to/tclsh8\&.5 /path/to/kettle/kettle -f /path/to/kettle/build\&.tcl install

.CE
where "\fI/path/to/tclsh8\&.5\fR" is the tclsh of your Tcl installation,
and "\fI/path/to/kettle\fR" the location of the Kettle sources on your
system\&.
Please note that and how we are using the non-installed
\fBkettle\fR application found in the sources to install itself\&.
.PP
This will build the package and application and then places them into
directories where the \fBtclsh8\&.5\fR will find them\&. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the \fBPATH\fR\&.
.PP
The above is written without assuming any associations from
extensions (like "\fI\&.tcl\fR") to executables responsible for the file
with that extension\&.
Actually, given that "\fIbuild\&.tcl\fR" is technically a
"\fIkettle\fR"-script, which in turn is a "\fI\&.tcl\fR"-script I am not
sure if Windows is able to handle such a chain of interpreters\&.
The command given above simply spells out the entire chain\&.
.PP
The build system provides a small GUI for those not comfortable with
the command line\&.
This GUI is accessible by invoking "\fIbuild\&.tcl\fR" without any

arguments from the command line\&.
.PP
To get help about the methods of "\fIbuild\&.tcl\fR", and their complete
syntax, invoke "\fIbuild\&.tcl\fR" with argument \fBhelp\fR, i\&.e\&.,
like
.CS


    /path/to/tclsh8\&.5 /path/to/kettle/kettle -f /path/to/kettle/build\&.tcl help

.CE
.SS "BUILD & INSTALLATION (HELP)"
Kettle commands for getting various types of help are:
.IP [1]
help-recipes
.IP [2]
help-options
.IP [3]
help
.IP [4]
................................................................................
.IP [6]
list
.IP [7]
show-configuration
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_intro.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
...
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
...
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_intro.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_introduction" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_introduction \- Kettle - Introduction to Kettle
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
Kettle is a system to make building Tcl packages quick and easy. More
importantly, possibly, to make writing the build system for Tcl
packages easy.
.PP
As such kettle is several things:
.IP [1]
A DSL helping you to write build systems for your packages.
.IP [2]
A package implementing this DSL.
.IP [3]
An application which can serve as the interpreter for a build
file containing commands in the above DSL.
.PP
All of these will be explained in the documentation, although not
everything is for everybody. I.e. a user of the DSL requires a
different set of knowledge than a developer working on extending
kettle's DSL, etc.
.SH "RELATED DOCUMENTS"
.IP [1]
\fIKettle - License\fR.
.IP [2]
\fIKettle - How To Get The Sources\fR.
.IP [3]
\fIKettle - The Installer's Guide\fR.
.IP [4]
\fIKettle - The Developer's Guide\fR.
.PP
.SH "SYSTEM ARCHITECTURE"
The image below provides a basic overview of the system's
architecture, with a package's custom build file at the top, using DSL
commands from core layer, under the mediation of the kettle
application.
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
+-------------------------------------------------------------------------------+
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
The manpages relevant to a user of kettle, i.e. to a package
developer wishing to use it as the build system for her code are:
.IP [1]
\fIKettle - Application - Build Interpreter\fR
.IP [2]
\fIKettle - Build Declarations\fR
.IP [3]
\fIKettle - Testsuite support\fR
................................................................................
.IP [1]
\fIKettle - The Developer's Guide\fR
.IP [2]
\fIKettle - Core\fR
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|





|
|

|



|

|


|


|

|


|

|

|

|





|




|







 







|







 







|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
...
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
...
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
'\"
'\" Generated from file 'kettle_intro\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_introduction" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_introduction \- Kettle - Introduction to Kettle
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
Kettle is a system to make building Tcl packages quick and easy\&. More
importantly, possibly, to make writing the build system for Tcl
packages easy\&.
.PP
As such kettle is several things:
.IP [1]
A DSL helping you to write build systems for your packages\&.
.IP [2]
A package implementing this DSL\&.
.IP [3]
An application which can serve as the interpreter for a build
file containing commands in the above DSL\&.
.PP
All of these will be explained in the documentation, although not
everything is for everybody\&. I\&.e\&. a user of the DSL requires a
different set of knowledge than a developer working on extending
kettle's DSL, etc\&.
.SH "RELATED DOCUMENTS"
.IP [1]
\fIKettle - License\fR\&.
.IP [2]
\fIKettle - How To Get The Sources\fR\&.
.IP [3]
\fIKettle - The Installer's Guide\fR\&.
.IP [4]
\fIKettle - The Developer's Guide\fR\&.
.PP
.SH "SYSTEM ARCHITECTURE"
The image below provides a basic overview of the system's
architecture, with a package's custom build file at the top, using DSL
commands from core layer, under the mediation of the kettle
application\&.
.PP
.PS
.nf
+-------------------------------------------------------------------------------+
| build\&.tcl                                                                     |
+-------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------+
| kettle                                                                        |
|        +----------------------------------------------------------------------+
|        | +-------------+ +----------------+ +-------------+ +-----------------+
|        | | kettle::tcl | | kettle::tclapp | | kettle::doc | | kettle::figures |
+--------+ +-------------+ +----------------+ +-------------+ +-----------------+
................................................................................
+-------------------------------------------------------------------------------+
| kettle, kettle::util                                                          |
+-------------------------------------------------------------------------------+

.fi
.PE
.PP
The manpages relevant to a user of kettle, i\&.e\&. to a package
developer wishing to use it as the build system for her code are:
.IP [1]
\fIKettle - Application - Build Interpreter\fR
.IP [2]
\fIKettle - Build Declarations\fR
.IP [3]
\fIKettle - Testsuite support\fR
................................................................................
.IP [1]
\fIKettle - The Developer's Guide\fR
.IP [2]
\fIKettle - Core\fR
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_license.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_license.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_license" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_license \- Kettle - License
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
The package is under the BSD license.
.SH LICENSE
.PP
This software is copyrighted by Andreas Kupries and other
parties.  The following terms apply to all files associated with the
software unless explicitly disclaimed in individual files.
.PP
The authors hereby grant permission to use, copy, modify,
distribute, and license this software and its documentation for any
purpose, provided that existing copyright notices are retained in all
copies and that this notice is included verbatim in any
distributions. No written agreement, license, or royalty fee is
required for any of the authorized uses.  Modifications to this
software may be copyrighted by their authors and need not follow the
licensing terms described here, provided that the new terms are
clearly indicated on the first page of each file where they apply.
.PP
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR
ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.PP
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
.PP
GOVERNMENT USE: If you are acquiring this software on behalf of
the U.S. government, the Government shall have only "Restricted
Rights" in the software and related documentation as defined in the
Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).
If you are acquiring the software on behalf of the Department of
Defense, the software shall be classified as "Commercial Computer
Software" and the Government shall have only "Restricted Rights" as
defined in Clause 252.227-7014 (b) (3) of DFARs.  Notwithstanding the
foregoing, the authors grant the U.S. Government and others acting in
its behalf permission to use and distribute the software in accordance
with the terms specified in this license.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|





|


|

|



|
|





|
|


|





|




|

|


|

|



|
|

|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
'\"
'\" Generated from file 'kettle_license\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_license" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_license \- Kettle - License
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
The package is under the BSD license\&.
.SH LICENSE
.PP
This software is copyrighted by Andreas Kupries and other
parties\&.  The following terms apply to all files associated with the
software unless explicitly disclaimed in individual files\&.
.PP
The authors hereby grant permission to use, copy, modify,
distribute, and license this software and its documentation for any
purpose, provided that existing copyright notices are retained in all
copies and that this notice is included verbatim in any
distributions\&. No written agreement, license, or royalty fee is
required for any of the authorized uses\&.  Modifications to this
software may be copyrighted by their authors and need not follow the
licensing terms described here, provided that the new terms are
clearly indicated on the first page of each file where they apply\&.
.PP
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR
ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE\&.
.PP
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT\&.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\&.
.PP
GOVERNMENT USE: If you are acquiring this software on behalf of
the U\&.S\&. government, the Government shall have only "Restricted
Rights" in the software and related documentation as defined in the
Federal Acquisition Regulations (FARs) in Clause 52\&.227\&.19 (c) (2)\&.
If you are acquiring the software on behalf of the Department of
Defense, the software shall be classified as "Commercial Computer
Software" and the Government shall have only "Restricted Rights" as
defined in Clause 252\&.227-7014 (b) (3) of DFARs\&.  Notwithstanding the
foregoing, the authors grant the U\&.S\&. Government and others acting in
its behalf permission to use and distribute the software in accordance
with the terms specified in this license\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_sources.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_sources.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_sources" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_sources \- Kettle - How To Get The Sources
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
The audience of this document is anyone wishing to either have
just a look at Kettle's source code, or build the packages, or to
extend and modify them.
.PP
For builders and developers we additionally provide
.IP [1]
\fIKettle - License\fR.
.IP [2]
\fIKettle - The Installer's Guide\fR.
.IP [3]
\fIKettle - The Developer's Guide\fR.
.PP
respectively.
.SH "SOURCE LOCATION"
The official repository for Kettle can be found at
\fIhttp://chiselapp.com/user/andreas_kupries/repository/Kettle\fR
.SH RETRIEVAL
Assuming that you simply wish to look at the sources, or build a
specific revision, the easiest way of retrieving it is to:
.IP [1]
Log into this site, as "anonymous", using the semi-random password in the captcha.
.IP [2]
Go to the "Timeline".
.IP [3]
Choose the revision you wish to have and
.IP [4]
follow its link to its detailed information page.
.IP [5]
On that page, choose either the "ZIP" or "Tarball" link to get
a copy of this revision in the format of your choice.
.PP
.SH "SOURCE CODE MANAGEMENT"
For the curious (or a developer-to-be), the sources are managed by the
\fIFossil SCM\fR [http://www.fossil-scm.org].
Binaries for popular platforms can be found directly at its
\fIdownload page\fR [http://www.fossil-scm.org/download.html].
.PP
With that tool available the full history can be retrieved via:
.CS


    fossil clone  http://chiselapp.com/user/andreas_kupries/repository/Kettle  kettle.fossil

.CE
followed by
.CS


    mkdir kettle
    cd kettle
    fossil open ../kettle.fossil

.CE
to get a checkout of the head of the trunk.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|





|


|



|



|

|

|

|


|




|

|



|


|



|

|





|








|


|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
'\"
'\" Generated from file 'kettle_sources\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_sources" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_sources \- Kettle - How To Get The Sources
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
The audience of this document is anyone wishing to either have
just a look at Kettle's source code, or build the packages, or to
extend and modify them\&.
.PP
For builders and developers we additionally provide
.IP [1]
\fIKettle - License\fR\&.
.IP [2]
\fIKettle - The Installer's Guide\fR\&.
.IP [3]
\fIKettle - The Developer's Guide\fR\&.
.PP
respectively\&.
.SH "SOURCE LOCATION"
The official repository for Kettle can be found at
\fIhttp://chiselapp\&.com/user/andreas_kupries/repository/Kettle\fR
.SH RETRIEVAL
Assuming that you simply wish to look at the sources, or build a
specific revision, the easiest way of retrieving it is to:
.IP [1]
Log into this site, as "anonymous", using the semi-random password in the captcha\&.
.IP [2]
Go to the "Timeline"\&.
.IP [3]
Choose the revision you wish to have and
.IP [4]
follow its link to its detailed information page\&.
.IP [5]
On that page, choose either the "ZIP" or "Tarball" link to get
a copy of this revision in the format of your choice\&.
.PP
.SH "SOURCE CODE MANAGEMENT"
For the curious (or a developer-to-be), the sources are managed by the
\fIFossil SCM\fR [http://www\&.fossil-scm\&.org]\&.
Binaries for popular platforms can be found directly at its
\fIdownload page\fR [http://www\&.fossil-scm\&.org/download\&.html]\&.
.PP
With that tool available the full history can be retrieved via:
.CS


    fossil clone  http://chiselapp\&.com/user/andreas_kupries/repository/Kettle  kettle\&.fossil

.CE
followed by
.CS


    mkdir kettle
    cd kettle
    fossil open \&.\&./kettle\&.fossil

.CE
to get a checkout of the head of the trunk\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/files/kettle_test.n.

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
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

237
238
239
240






















241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/man/files/kettle_test.n' by tcllib/doctools with format 'nroff'
'\"

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "kettle_test" n 1 doc "Kettle - The Quick Brew System"






















.BS
.SH NAME
kettle_test \- Kettle - Testsuite Support
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
\fB::kt\fR \fBsource\fR \fIpath\fR
.sp
\fB::kt\fR \fBsource*\fR \fIpattern\fR
.sp
\fB::kt\fR \fBfind\fR \fIpattern\fR
.sp
\fB::kt\fR \fBcheck\fR \fIname\fR \fIversion\fR
.sp
\fB::kt\fR \fBrequire\fR \fItype\fR \fIname\fR \fIarg\fR...
.sp
\fB::kt\fR \fBlocal\fR \fItype\fR \fIname\fR \fIarg\fR...
.sp
\fB::kt\fR \fBdictsort\fR \fIdict\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system.
.PP
.TP
\fB::kt\fR \fBsource\fR \fIpath\fR
This command sources the file specified by the \fIpath\fR.
In contrast to the builtin \fB::source\fR command, this resolves
relative paths relative to the \fBtcltest::testsDirectory\fR.
.TP
\fB::kt\fR \fBsource*\fR \fIpattern\fR
This command sources all files found in the
\fBtcltest::testsDirectory\fR and matching the pattern.
.TP
\fB::kt\fR \fBfind\fR \fIpattern\fR
This command returns a list of all files found in the
\fBtcltest::testsDirectory\fR and matching the pattern.
.TP
\fB::kt\fR \fBcheck\fR \fIname\fR \fIversion\fR
This command assumes that the package \fIname\fR is present, and
verifies that we are using at least the specified \fIversion\fR.
If not the command aborts the testsuite in a manner kettle's test
controller can detect and respond to.
.sp
This is useful for checking the versions of the Tcl core and/or
tcltest.
\fINote\fR that the whole of kettle assumes to be run under at least
Tcl 8.5, and having tcltest 2 available.
.TP
\fB::kt\fR \fBrequire\fR \fItype\fR \fIname\fR \fIarg\fR...
This command is a wrapper around Tcl's builtin \fBpackage require\fR
which aborts the testsuite in a manner kettle's test controller can
detect and respond to if the specified \fIexternal\fR package is not
found.
.sp
The \fItype\fR can be one of \fBsupport\fR, or
\fBtesting\fR, indicating the use of the package in the testsuite,
i.e. a supporting package, or the package under test itself. Exactly
one package should have this type.
.TP
\fB::kt\fR \fBlocal\fR \fItype\fR \fIname\fR \fIarg\fR...
This command is like \fBkt require\fR above, except its search of
packages is restricted to the local packages provided by the test
controller, which should be the package under test, and its local
dependencies, if any.
.TP
\fB::kt\fR \fBdictsort\fR \fIdict\fR
This command takes a Tcl dictionary, sorts its contents by its keys
(\fBlsort -dict\fR), and returns the sorted dictionary.
.sp
This is useful to impose a canonical order on dictionary and
array results whose natural order can change between Tcl versions, or
package revisions.
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp.com/user/andreas_kupries/repository/Kettle/index].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

|

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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|









|

|








|


|



|

|



|



|



|

|


|

|

|



|



|
|

|



|



|



|


|


|

|

|




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
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
'\"
'\" Generated from file 'kettle_test\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "kettle_test" n 1 doc "Kettle - The Quick Brew System"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
kettle_test \- Kettle - Testsuite Support
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
\fB::kt\fR \fBsource\fR \fIpath\fR
.sp
\fB::kt\fR \fBsource*\fR \fIpattern\fR
.sp
\fB::kt\fR \fBfind\fR \fIpattern\fR
.sp
\fB::kt\fR \fBcheck\fR \fIname\fR \fIversion\fR
.sp
\fB::kt\fR \fBrequire\fR \fItype\fR \fIname\fR \fIarg\fR\&.\&.\&.
.sp
\fB::kt\fR \fBlocal\fR \fItype\fR \fIname\fR \fIarg\fR\&.\&.\&.
.sp
\fB::kt\fR \fBdictsort\fR \fIdict\fR
.sp
.BE
.SH DESCRIPTION
.PP
.PP
Welcome to Kettle, a set of packages providing support for writing
build code for Tcl packages\&.
.PP
Please read the document \fIKettle - Introduction to Kettle\fR,
if you have not done so already, to get an overview of the whole system\&.
.PP
.TP
\fB::kt\fR \fBsource\fR \fIpath\fR
This command sources the file specified by the \fIpath\fR\&.
In contrast to the builtin \fB::source\fR command, this resolves
relative paths relative to the \fBtcltest::testsDirectory\fR\&.
.TP
\fB::kt\fR \fBsource*\fR \fIpattern\fR
This command sources all files found in the
\fBtcltest::testsDirectory\fR and matching the pattern\&.
.TP
\fB::kt\fR \fBfind\fR \fIpattern\fR
This command returns a list of all files found in the
\fBtcltest::testsDirectory\fR and matching the pattern\&.
.TP
\fB::kt\fR \fBcheck\fR \fIname\fR \fIversion\fR
This command assumes that the package \fIname\fR is present, and
verifies that we are using at least the specified \fIversion\fR\&.
If not the command aborts the testsuite in a manner kettle's test
controller can detect and respond to\&.
.sp
This is useful for checking the versions of the Tcl core and/or
tcltest\&.
\fINote\fR that the whole of kettle assumes to be run under at least
Tcl 8\&.5, and having tcltest 2 available\&.
.TP
\fB::kt\fR \fBrequire\fR \fItype\fR \fIname\fR \fIarg\fR\&.\&.\&.
This command is a wrapper around Tcl's builtin \fBpackage require\fR
which aborts the testsuite in a manner kettle's test controller can
detect and respond to if the specified \fIexternal\fR package is not
found\&.
.sp
The \fItype\fR can be one of \fBsupport\fR, or
\fBtesting\fR, indicating the use of the package in the testsuite,
i\&.e\&. a supporting package, or the package under test itself\&. Exactly
one package should have this type\&.
.TP
\fB::kt\fR \fBlocal\fR \fItype\fR \fIname\fR \fIarg\fR\&.\&.\&.
This command is like \fBkt require\fR above, except its search of
packages is restricted to the local packages provided by the test
controller, which should be the package under test, and its local
dependencies, if any\&.
.TP
\fB::kt\fR \fBdictsort\fR \fIdict\fR
This command takes a Tcl dictionary, sorts its contents by its keys
(\fBlsort -dict\fR), and returns the sorted dictionary\&.
.sp
This is useful to impose a canonical order on dictionary and
array results whose natural order can change between Tcl versions, or
package revisions\&.
.PP
.SH LICENSE
This package, written by Andreas Kupries, is BSD licensed\&.
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such at the
\fIKettle Tracker\fR [https://chiselapp\&.com/user/andreas_kupries/repository/Kettle/index]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
build tea
.SH CATEGORY
Build support

Changes to embedded/man/index.n.

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
...
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
...
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200


201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235

236
237
238
239






















240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
'\"
'\" Generated by tcllib/doctools/idx with format 'nroff'

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Keyword Index" n






















.BS
.SH INDEX
doc
.RS
build tea
.RS
.TP
\fBfiles/kettle.n\fR
kettle
.TP
\fBfiles/kettle_app.n\fR
kettle_app
.TP
\fBfiles/kettle_changes.n\fR
kettle_changes
.TP
\fBfiles/kettle_devguide.n\fR
kettle_devguide
.TP
\fBfiles/kettle_dsl.n\fR
kettle_dsl
.TP
\fBfiles/kettle_installer.n\fR
kettle_install_guide
.TP
\fBfiles/kettle_intro.n\fR
kettle_introduction
.TP
\fBfiles/kettle_license.n\fR
kettle_license
.TP
\fBfiles/kettle_sources.n\fR
kettle_sources
.TP
\fBfiles/kettle_test.n\fR
kettle_test
.RE


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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







|


|


|


|


|


|


|


|


|


|


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
...
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
...
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
...
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248

249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
'\"
'\" Generated by tcllib/doctools/idx with format 'nroff'
.TH "Keyword Index" n
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH INDEX
doc
.RS
build tea
.RS
.TP
\fBfiles/kettle\&.n\fR
kettle
.TP
\fBfiles/kettle_app\&.n\fR
kettle_app
.TP
\fBfiles/kettle_changes\&.n\fR
kettle_changes
.TP
\fBfiles/kettle_devguide\&.n\fR
kettle_devguide
.TP
\fBfiles/kettle_dsl\&.n\fR
kettle_dsl
.TP
\fBfiles/kettle_installer\&.n\fR
kettle_install_guide
.TP
\fBfiles/kettle_intro\&.n\fR
kettle_introduction
.TP
\fBfiles/kettle_license\&.n\fR
kettle_license
.TP
\fBfiles/kettle_sources\&.n\fR
kettle_sources
.TP
\fBfiles/kettle_test\&.n\fR
kettle_test
.RE

Changes to embedded/man/toc.n.

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
...
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
...
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200


201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235

236
237
238
239






















240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
'\"
'\" Generated by tcllib/doctools/toc with format 'nroff'

'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The

'\"	options follow on successive lines, in four columns separated
'\"	by tabs.

'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $


'\"




'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO


.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..

.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Table Of Contents" n






















.BS
.SH CONTENTS
doc
.RS
.TP
\fBkettle\fR
\fIfiles/kettle.n\fR: Kettle - Core
.TP
\fBkettle_app\fR
\fIfiles/kettle_app.n\fR: Kettle - Application - Build Interpreter
.TP
\fBkettle_changes\fR
\fIfiles/kettle_changes.n\fR: Kettle Changes
.TP
\fBkettle_devguide\fR
\fIfiles/kettle_devguide.n\fR: Kettle - The Developer's Guide
.TP
\fBkettle_dsl\fR
\fIfiles/kettle_dsl.n\fR: Kettle - Build Declarations
.TP
\fBkettle_install_guide\fR
\fIfiles/kettle_installer.n\fR: Kettle - The Installer's Guide
.TP
\fBkettle_introduction\fR
\fIfiles/kettle_intro.n\fR: Kettle - Introduction to Kettle
.TP
\fBkettle_license\fR
\fIfiles/kettle_license.n\fR: Kettle - License
.TP
\fBkettle_sources\fR
\fIfiles/kettle_sources.n\fR: Kettle - How To Get The Sources
.TP
\fBkettle_test\fR
\fIfiles/kettle_test.n\fR: Kettle - Testsuite Support


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



|








|












|









|
|
|









|







 







|
|
|






|







 







|
|
|







 







|





|





|

>
>



|


|




|

|










|





|




>



<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>






|


|


|


|


|


|


|


|


|


|
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
...
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
...
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
...
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248

249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
'\"
'\" Generated by tcllib/doctools/toc with format 'nroff'
.TH "Table Of Contents" n
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive

.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"

.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
................................................................................
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
................................................................................
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
................................................................................
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..

.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH CONTENTS
doc
.RS
.TP
\fBkettle\fR
\fIfiles/kettle\&.n\fR: Kettle - Core
.TP
\fBkettle_app\fR
\fIfiles/kettle_app\&.n\fR: Kettle - Application - Build Interpreter
.TP
\fBkettle_changes\fR
\fIfiles/kettle_changes\&.n\fR: Kettle Changes
.TP
\fBkettle_devguide\fR
\fIfiles/kettle_devguide\&.n\fR: Kettle - The Developer's Guide
.TP
\fBkettle_dsl\fR
\fIfiles/kettle_dsl\&.n\fR: Kettle - Build Declarations
.TP
\fBkettle_install_guide\fR
\fIfiles/kettle_installer\&.n\fR: Kettle - The Installer's Guide
.TP
\fBkettle_introduction\fR
\fIfiles/kettle_intro\&.n\fR: Kettle - Introduction to Kettle
.TP
\fBkettle_license\fR
\fIfiles/kettle_license\&.n\fR: Kettle - License
.TP
\fBkettle_sources\fR
\fIfiles/kettle_sources\&.n\fR: Kettle - How To Get The Sources
.TP
\fBkettle_test\fR
\fIfiles/kettle_test\&.n\fR: Kettle - Testsuite Support

Changes to embedded/www/doc/files/kettle.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_app.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_app.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_app.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_app.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_app.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_changes.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_changes.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_changes.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_changes.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_changes.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_devguide.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_devguide.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_devguide.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_devguide.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_devguide.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_dsl.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_dsl.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_dsl.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_dsl.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_dsl.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_installer.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
...
117
118
119
120
121
122
123
124






125
126
127
128
129
130
131
...
351
352
353
354
355
356
357
358





359
360
361
362
363
364
365
366
367
368


369
370
371
372



































373
374

375
376

377
378
379


380
381
382
383
384
385
386
387
388
389

390
391
392
393
394
395
396
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_installer.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_install_guide.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>
................................................................................
<li class="subsection"><a href="#subsection1">Tcl</a></li>
<li class="subsection"><a href="#subsection2">Tclx</a></li>
<li class="subsection"><a href="#subsection3">Tk</a></li>
<li class="subsection"><a href="#subsection4">Tklib</a></li>
<li class="subsection"><a href="#subsection5">tcltest</a></li>
</ul>
</li>
<li class="section"><a href="#section3">Build &amp; Installation</a></li>






<li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
................................................................................
<p>Note however that the sources of tcltest come with a source
distribution of Tcl and the package should always be installed
together with Tcl itself.</p>
<p>If there are problems with using tcltest please file a bug
against Tcl, or the vendor of your Tcl distribution, and not Kettle.</p>
</div>
</div>
<div id="section3" class="section"><h2><a name="section3">Build &amp; Installation</a></h2>





<p>To install Kettle simply run</p>
<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/build.tcl install
</pre>
<p>where &quot;<b class="file">/path/to/tclsh8.5</b>&quot; is the tclsh of your Tcl installation, and
&quot;<b class="file">/path/to/kettle</b>&quot; the location of the Kettle sources on your system.</p>
<p>This will build the package and application and then places them into
directories where the <b class="cmd">tclsh8.5</b> will find them. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the <b class="variable">PATH</b>.</p>


<p>On Windows you can invoke the file &quot;<b class="file">build.tcl</b>&quot; with a
double-click.  This will pop up a small graphical interface for
entering the destination and performing the installation. This
handling of a double-click is restricted to Windows only however.</p>



































<p>On unix the same GUI is acessible by invoking &quot;<b class="file">build.tcl</b>&quot; using
<b class="const">gui</b> instead of <b class="const">install</b> in the example above.</p>

<p>To get help about the methods of &quot;<b class="file">build.tcl</b>&quot;, and their complete
syntax, invoke &quot;<b class="file">build.tcl</b>&quot; with argument <b class="method">help</b>, i.e., like</p>

<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/build.tcl help
</pre>


<p>Other methods for gfetting various types of help are:</p>
<ol class="enumerated">
<li><p>help-recipes</p></li>
<li><p>help-options</p></li>
<li><p>help</p></li>
<li><p>list-recipes</p></li>
<li><p>list-options</p></li>
<li><p>list</p></li>
<li><p>show-configuration</p></li>
</ol>

</div>
<div id="section4" class="section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
<a href="https://chiselapp.com/user/andreas_kupries/repository/Kettle/index">Kettle Tracker</a>.
Please also report any ideas for enhancements you may have for either







|







 







|
>
>
>
>
>
>







 







|
>
>
>
>
>










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

|
>

|

>
>
|









>







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
...
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
...
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382


383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419

420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_installer.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_install_guide.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>
................................................................................
<li class="subsection"><a href="#subsection1">Tcl</a></li>
<li class="subsection"><a href="#subsection2">Tclx</a></li>
<li class="subsection"><a href="#subsection3">Tk</a></li>
<li class="subsection"><a href="#subsection4">Tklib</a></li>
<li class="subsection"><a href="#subsection5">tcltest</a></li>
</ul>
</li>
<li class="section"><a href="#section3">Build &amp; Installation Instructions</a>
<ul>
<li class="subsection"><a href="#subsection6">Build &amp; Installation (Unix)</a></li>
<li class="subsection"><a href="#subsection7">Build &amp; Installation (Windows)</a></li>
<li class="subsection"><a href="#subsection8">Build &amp; Installation (Help)</a></li>
</ul>
</li>
<li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
................................................................................
<p>Note however that the sources of tcltest come with a source
distribution of Tcl and the package should always be installed
together with Tcl itself.</p>
<p>If there are problems with using tcltest please file a bug
against Tcl, or the vendor of your Tcl distribution, and not Kettle.</p>
</div>
</div>
<div id="section3" class="section"><h2><a name="section3">Build &amp; Installation Instructions</a></h2>
<div id="subsection6" class="subsection"><h3><a name="subsection6">Build &amp; Installation (Unix)</a></h3>
<p>This section describes the actions required to install Kettle on Unix
systems (Linux, BSD, and related, including OS X).
If you have to install Kettle on a Windows machine see section
<span class="sectref"><a href="#subsection7">Build &amp; Installation (Windows)</a></span> instead.</p>
<p>To install Kettle simply run</p>
<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/build.tcl install
</pre>
<p>where &quot;<b class="file">/path/to/tclsh8.5</b>&quot; is the tclsh of your Tcl installation, and
&quot;<b class="file">/path/to/kettle</b>&quot; the location of the Kettle sources on your system.</p>
<p>This will build the package and application and then places them into
directories where the <b class="cmd">tclsh8.5</b> will find them. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the <b class="variable">PATH</b>.</p>
<p>The build system provides a small GUI for those not comfortable with
the command line.
This GUI is accessible by invoking &quot;<b class="file">build.tcl</b>&quot; without any


arguments.</p>
<p>To get help about the methods of &quot;<b class="file">build.tcl</b>&quot;, and their complete
syntax, invoke &quot;<b class="file">build.tcl</b>&quot; with argument <b class="method">help</b>, i.e.,
like</p>
<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/build.tcl help
</pre>
</div>
<div id="subsection7" class="subsection"><h3><a name="subsection7">Build &amp; Installation (Windows)</a></h3>
<p>This section describes the actions required to install Kettle on Windows(tm)
systems.
If you have to install Kettle on a Unix machine (Linux, BSD, and
related, including OS X) see section
<span class="sectref"><a href="#subsection6">Build &amp; Installation (Unix)</a></span> instead.</p>
<p>To install Kettle simply run</p>
<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/kettle -f /path/to/kettle/build.tcl install
</pre>
<p>where &quot;<b class="file">/path/to/tclsh8.5</b>&quot; is the tclsh of your Tcl installation,
and &quot;<b class="file">/path/to/kettle</b>&quot; the location of the Kettle sources on your
system.
Please note that and how we are using the non-installed
<b class="syscmd"><a href="kettle.html">kettle</a></b> application found in the sources to install itself.</p>
<p>This will build the package and application and then places them into
directories where the <b class="cmd">tclsh8.5</b> will find them. Note that the
installed kettle application is modified to use the chosen tclsh
instead of searching for one on the <b class="variable">PATH</b>.</p>
<p>The above is written without assuming any associations from
extensions (like &quot;<b class="file">.tcl</b>&quot;) to executables responsible for the file
with that extension.
Actually, given that &quot;<b class="file">build.tcl</b>&quot; is technically a
&quot;<b class="file">kettle</b>&quot;-script, which in turn is a &quot;<b class="file">.tcl</b>&quot;-script I am not
sure if Windows is able to handle such a chain of interpreters.
The command given above simply spells out the entire chain.</p>
<p>The build system provides a small GUI for those not comfortable with
the command line.
This GUI is accessible by invoking &quot;<b class="file">build.tcl</b>&quot; without any

arguments from the command line.</p>
<p>To get help about the methods of &quot;<b class="file">build.tcl</b>&quot;, and their complete
syntax, invoke &quot;<b class="file">build.tcl</b>&quot; with argument <b class="method">help</b>, i.e.,
like</p>
<pre class="example">
    /path/to/tclsh8.5 /path/to/kettle/kettle -f /path/to/kettle/build.tcl help
</pre>
</div>
<div id="subsection8" class="subsection"><h3><a name="subsection8">Build &amp; Installation (Help)</a></h3>
<p>Kettle commands for getting various types of help are:</p>
<ol class="enumerated">
<li><p>help-recipes</p></li>
<li><p>help-options</p></li>
<li><p>help</p></li>
<li><p>list-recipes</p></li>
<li><p>list-options</p></li>
<li><p>list</p></li>
<li><p>show-configuration</p></li>
</ol>
</div>
</div>
<div id="section4" class="section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such at the
<a href="https://chiselapp.com/user/andreas_kupries/repository/Kettle/index">Kettle Tracker</a>.
Please also report any ideas for enhancements you may have for either

Changes to embedded/www/doc/files/kettle_intro.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_intro.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_introduction.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_intro.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_introduction.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_license.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_license.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_license.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_license.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_license.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_sources.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_sources.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_sources.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_sources.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_sources.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>

Changes to embedded/www/doc/files/kettle_test.html.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Kettle/kettle/embedded/www/doc/files/kettle_test.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_test.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>







|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'kettle_test.man' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ kettle_test.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>