1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
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
169
170
171
172
173
174
175
176
177
178
179
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
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
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
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
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
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
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
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
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
1452
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
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
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
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
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
1728
1729
1730
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title>ETM Users Manual</title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<style>
body {
margin: auto;
padding-right: 1em;
padding-left: 1em;
max-width: 44em;
border-left: 1px solid black;
border-right: 1px solid black;
color: black;
font-family: Verdana, sans-serif;
font-size: 100%;
line-height: 140%;
color: #333;
}
pre, tt{
font-family: monospace;
padding: 2px 4px;
}
code{
white-space: pre-wrap;
font-size: 110%;
padding: 1px 1px;
}
h1 a, h2 a, h3 a, h4 a, h5 a, li a {
text-decoration: none;
color: #7a5ada;
}
header, h1, h2, h3, h4, h5 { font-family: verdana;
font-weight: bold;
/*border-bottom: 1px dotted black;*/
color: #7a5ada; }
header {
font-size: 130%;
}
h1 {
font-size: 130%;
}
h2 {
font-size: 110%;
border-bottom: 1px dotted black;
}
h3 {
font-size: 100%;
border-bottom: 1px dotted black;
}
h4 {
font-size: 90%;
font-style: italic;
border-bottom: 1px dotted black;
}
h5 {
font-size: 85%;
font-style: italic;
border-bottom: 1px dotted black;
}
h1.title {
font-size: 200%;
font-weight: bold;
padding-top: 0.2em;
padding-bottom: 0.2em;
text-align: left;
border: none;
}
dt code {
font-weight: bold;
}
dd p {
margin-top: 0;
}
#footer {
padding-top: 1em;
font-size: 70%;
color: gray;
text-align: center;
}
</style>
<div id="header">
<h1 class="title">ETM Users Manual</h1>
</div>
<div id="TOC">
<ul>
<li><a href="#overview">Overview</a><ul>
<li><a href="#sample-entries">Sample entries</a></li>
<li><a href="#starting-etm">Starting etm</a></li>
<li><a href="#views">Views</a></li>
<li><a href="#creating-new-items">Creating New Items</a></li>
<li><a href="#editing-existing-items">Editing Existing Items</a></li>
<li><a href="#timers">Timers</a></li>
<li><a href="#sharing-with-other-calendar-applications">Sharing with other calendar applications</a></li>
<li><a href="#tools">Tools</a></li>
<li><a href="#calendars">Calendars</a></li>
<li><a href="#data-organization">Data Organization</a></li>
<li><a href="#colors">Colors</a></li>
<li><a href="#internationalization">Internationalization</a></li>
</ul></li>
<li><a href="#item-types">Item types</a><ul>
<li><a href="#action">~ Action</a></li>
<li><a href="#event">* Event</a></li>
<li><a href="#occasion">^ Occasion</a></li>
<li><a href="#note">! Note</a></li>
<li><a href="#and-tasks">-, % and + Tasks</a></li>
<li><a href="#in-basket">$ In basket</a></li>
<li><a href="#someday-maybe">? Someday maybe</a></li>
<li><a href="#comment"># Comment</a></li>
<li><a href="#defaults">= Defaults</a></li>
</ul></li>
<li><a href="#keys">@Keys</a><ul>
<li><a href="#a-alert"><span class="citation">@a</span> alert</a></li>
<li><a href="#b-beginby"><span class="citation">@b</span> beginby</a></li>
<li><a href="#c-context"><span class="citation">@c</span> context</a></li>
<li><a href="#d-description"><span class="citation">@d</span> description</a></li>
<li><a href="#e-extent"><span class="citation">@e</span> extent</a></li>
<li><a href="#f-done-due"><span class="citation">@f</span> done[; due]</a></li>
<li><a href="#g-goto"><span class="citation">@g</span> goto</a></li>
<li><a href="#h-history"><span class="citation">@h</span> history</a></li>
<li><a href="#i-invitees"><span class="citation">@i</span> invitees</a></li>
<li><a href="#j-job"><span class="citation">@j</span> job</a></li>
<li><a href="#k-keyword"><span class="citation">@k</span> keyword</a></li>
<li><a href="#l-location"><span class="citation">@l</span> location</a></li>
<li><a href="#m-memo"><span class="citation">@m</span> memo</a></li>
<li><a href="#n-noshow"><span class="citation">@n</span> noshow</a></li>
<li><a href="#o-overdue"><span class="citation">@o</span> overdue</a></li>
<li><a href="#p-priority"><span class="citation">@p</span> priority</a></li>
<li><a href="#q-datetime"><span class="citation">@q</span> datetime</a></li>
<li><a href="#r-repetition-rule"><span class="citation">@r</span> repetition rule</a></li>
<li><a href="#s-starting-datetime"><span class="citation">@s</span> starting datetime</a></li>
<li><a href="#t-tags"><span class="citation">@t</span> tags</a></li>
<li><a href="#u-user"><span class="citation">@u</span> user</a></li>
<li><a href="#v-action_rates-key"><span class="citation">@v</span> action_rates key</a></li>
<li><a href="#w-action_markups-key"><span class="citation">@w</span> action_markups key</a></li>
<li><a href="#x-expense"><span class="citation">@x</span> expense</a></li>
<li><a href="#z-time-zone"><span class="citation">@z</span> time zone</a></li>
<li><a href="#include">@+ include</a></li>
<li><a href="#exclude">@- exclude</a></li>
</ul></li>
<li><a href="#dates">Dates</a><ul>
<li><a href="#fuzzy-dates">Fuzzy dates</a></li>
<li><a href="#time-periods">Time periods</a></li>
<li><a href="#time-zones">Time zones</a></li>
<li><a href="#anniversary-substitutions">Anniversary substitutions</a></li>
<li><a href="#easter">Easter</a></li>
</ul></li>
<li><a href="#preferences">Preferences</a><ul>
<li><a href="#template-expansions">Template expansions</a></li>
<li><a href="#options">Options</a></li>
</ul></li>
<li><a href="#custom-view">Custom view</a><ul>
<li><a href="#view-type">View type</a></li>
<li><a href="#groupby-setting">Groupby setting</a></li>
<li><a href="#groupby-examples">Groupby examples</a></li>
<li><a href="#view-options">View Options</a></li>
<li><a href="#saving-view-specifications">Saving view specifications</a></li>
</ul></li>
<li><a href="#shortcuts">Shortcuts</a><ul>
<li><a href="#menu">Menu</a></li>
<li><a href="#edit">Edit</a></li>
</ul></li>
</ul>
</div>
<h1 id="overview"><a href="#overview">Overview</a></h1>
<p>In contrast to most calendar/todo applications, creating items (events, tasks, and so forth) in etm does not require filling out fields in a form. Instead, items are created as free-form text entries using a simple, intuitive format and stored in plain text files.</p>
<p>Dates in the examples below are entered using <em>fuzzy parsing</em> - e.g., <code>+7</code> for seven days from today, <code>fri</code> for the first Friday on or after today, <code>+1/1</code> for the first day of next month, <code>sun - 6d</code> for Monday of the current week. See <a href="#dates">Dates</a> for details.</p>
<h2 id="sample-entries"><a href="#sample-entries">Sample entries</a></h2>
<ul>
<li><p>A sales meeting (an event) [s]tarting seven days from today at 9:00am with an [e]xtent of one hour and a default [a]lert 5 minutes before the start:</p>
<pre><code>* sales meeting @s +7 9a @e 1h @a 5</code></pre></li>
<li><p>The sales meeting with another [a]lert 2 days before the meeting to (e)mail a reminder to a list of recipients:</p>
<pre><code>* sales meeting @s +7 9a @e 1h @a 5
@a 2d: e; who@when.com, what@where.org</code></pre></li>
<li><p>Prepare a report (a task) for the sales meeting [b]eginning 3 days early:</p>
<pre><code>- prepare report @s +7 @b 3</code></pre></li>
<li><p>A period [e]xtending 35 minutes (an action) spent working on the report yesterday:</p>
<pre><code>~ report preparation @s -1 @e 35</code></pre></li>
<li><p>Get a haircut (a task) on the 24th of the current month and then [r]epeatedly at (d)aily [i]ntervals of (14) days and, [o]n completion, (r)estart from the completion date:</p>
<pre><code>- get haircut @s 24 @r d &i 14 @o r</code></pre></li>
<li><p>Payday (an occasion) on the last week day of each month. The <code>&s -1</code> part of the entry extracts the last date which is both a weekday and falls within the last three days of the month):</p>
<pre><code>^ payday @s 1/1 @r m &w MO, TU, WE, TH, FR
&m -1, -2, -3 &s -1</code></pre></li>
<li><p>Take a prescribed medication daily (a reminder) [s]tarting today and [r]epeating (d)aily at [h]ours 10am, 2pm, 6pm and 10pm [u]ntil (12am on) the fourth day from today. Trigger the default [a]lert zero minutes before each reminder:</p>
<pre><code>* take Rx @s +0 @r d &h 10, 14, 18, 22 &u +4 @a 0</code></pre></li>
<li><p>Move the water sprinkler (a reminder) every thirty mi[n]utes on Sunday afternoons using the default alert zero minutes before each reminder:</p>
<pre><code>* Move sprinkler @s 1 @r n &i 30 &w SU &h 14, 15, 16, 17 @a 0</code></pre>
<p>To limit the sprinkler movement reminders to the [M]onths of April through September each year append <code>&M 4, 5, 6, 7, 8, 9</code> to the <span class="citation">@r</span> entry.</p></li>
<li><p>Grandparent's day (an occasion) each year on the first Sunday in September after Labor day:</p>
<pre><code>^ Grandparent's Day @s 2012-09-01
@r y &M 9 &w SU &m 7, 8, 9, 10, 11, 12, 13 </code></pre></li>
<li><p>Presidential election day (an occasion) every four years on the first Tuesday after a Monday in November:</p>
<pre><code>^ Presidential Election Day @s 2012-11-06
@r y &i 4 &M 11 &w TU &m 2, 3, 4, 5, 6, 7, 8 </code></pre></li>
<li><p>Join the etm discussion group (a task) [s]tarting 14 days from today. Because of the <span class="citation">@g</span> (goto) link, pressing <em>G</em> when this item is selected in the gui would open the link using the system default application which, in this case, would be your default browser:</p>
<pre><code>- join the etm discussion group @s +14
@g groups.google.com/group/eventandtaskmanager/topics</code></pre></li>
</ul>
<h2 id="starting-etm"><a href="#starting-etm">Starting etm</a></h2>
<p>To start the etm GUI open a terminal window and enter <code>etm</code> at the prompt:</p>
<pre><code>$ etm</code></pre>
<p>If you have not done a system installation of etm you will need first to cd to the directory where you unpacked etm.</p>
<p>Note: if you change the window size and/or position of the etm window on your display and quit etm from the etm file menu, then the closing size and position will be restored when you restart etm.</p>
<p>You can add a command to use the CLI instead of the GUI. For example, to get the complete command line usage information printed to the terminal window just add a question mark:</p>
<pre><code>$ etm ?
Usage:
etm [logging level] [path] [?] [acmsv]
With no arguments, etm will set logging level 3 (warn), use settings from
the configuration file ~/.etm/etmtk.cfg, and open the GUI.
If the first argument is an integer not less than 1 (debug) and not greater
than 5 (critical), then set that logging level and remove the argument.
If the first (remaining) argument is the path to a directory that contains
a file named etmtk.cfg, then use that configuration file and remove the
argument.
If the first (remaining) argument is one of the commands listed below, then
execute the remaining arguments without opening the GUI.
a ARG display the agenda view using ARG, if given, as a filter.
c ARGS display a custom view using the remaining arguments as the
specification. (Enclose ARGS in single quotes to prevent shell
expansion.)
d ARG display the day view using ARG, if given, as a filter.
k ARG display the keywords view using ARG, if given, as a filter.
m INT display a custom view using the remaining argument, which
must be a positive integer, to display a custom view using the
corresponding entry from the file given by report_specifications
in etmtk.cfg.
Use ? m to display the numbered list of entries from this file.
n ARG display the notes view using ARG, if given, as a filter.
N ARGS Create a new item using the remaining arguments as the item
specification. (Enclose ARGS in single quotes to prevent shell
expansion.)
p ARG display the path view using ARG, if given, as a filter.
t ARG display the tags view using ARG, if given, as a filter.
v display information about etm and the operating system.
? ARG display (this) command line help information if ARGS = '' or,
if ARGS = X where X is one of the above commands, then display
details about command X. 'X ?' is equivalent to '? X'.</code></pre>
<p>For example, you can print your agenda to the terminal window by adding the letter "a":</p>
<pre><code>$ etm a
Today
> set up luncheon meeting with Joe Smith 4d
Tomorrow
* test command line event 3pm ~ 4pm
* Aerobics 5pm ~ 6pm
- follow up with Mary Jones
Now
Available
- Hair cut -1d
Next
errands
- milk and eggs
phone
- reservation for Saturday dinner
Someday
? lose weight and exercise more</code></pre>
<p>You can filter the output by adding a (case-insensitive) argument:</p>
<pre><code>$ etm a hair
Now
Available
- Hair cut -1d</code></pre>
<p>or <code>etm d mar .*2014</code> to show your items for March, 2014.</p>
<p>You can add a question mark to a command to get details about the commmand, e.g.:</p>
<pre><code>Usage:
etm c <type> <groupby> [options]
Generate a custom view where type is either 'a' (action) or 'c' (composite).
Groupby can include *semicolon* separated date specifications and
elements from:
c context
f file path
k keyword
t tag
u user
A *date specification* is either
w: week number
or a combination of one or more of the following:
yy: 2-digit year
yyyy: 4-digit year
MM: month: 01 - 12
MMM: locale specific abbreviated month name: Jan - Dec
MMMM: locale specific month name: January - December
dd: month day: 01 - 31
ddd: locale specific abbreviated week day: Mon - Sun
dddd: locale specific week day: Monday - Sunday
Options include:
-b begin date
-c context regex
-d depth (CLI type a only)
-e end date
-f file regex
-k keyword regex
-l location regex
-o omit (type c only)
-s summary regex
-S search regex
-t tags regex
-u user regex
-w column 1 width
-W column 2 width
Example:
etm c 'c ddd, MMM dd yyyy -b 1 -e +1/1'</code></pre>
<p>Note: The CLI offers the same views and reporting, with the exception of week and month view, as the GUI. It is also possible to create new items in the CLI with the <code>n</code> command. Other modifications such as copying, deleting, finishing and so forth, can only be done in the GUI or, perhaps, in your favorite text editor. An advantage to using the GUI is that it provides auto-completion and validation.</p>
<p>Tip: If you have a terminal open, you can create a new item or put something to finish later in your inbox quickly and easily with the "N" command. For example,</p>
<pre><code> etm N '123 456-7890'</code></pre>
<p>would create an entry in your inbox with this phone number. (With no type character an "$" would be supplied automatically to make the item an inbox entry and no further validation would be done.)</p>
<h2 id="views"><a href="#views">Views</a></h2>
<p>All views display only items consistent with the current choices of active calendars. Click the settings icon on the left side of the top menu bar to choose active calendars.</p>
<p>Week and month views have three panes. The top one displays a graphic illustration of scheduled times for the relevant period, the middle one displays an tree view of items grouped by date and the bottom one displays detail information. Custom view also has three panes but the top one is an entry area for providing the specification for the custom view. All other views have two panes - a tree view in the top pane and details in the bottom pane.</p>
<p>If a (case-insensitive) filter is entered then the display in the tree view will be limited to items that match somewhere in either the branch or the leaf. Relevant branches will automatically be expanded to show matches.</p>
<p>In week and month views, <em>Home</em> selects the current date. In all views other than week and month, <em>Home</em> selects the first item in the tree pane.</p>
<p>In all views, pressing <em>Return</em> with an item selected will open a context menu with options to copy, delete, edit and so forth.</p>
<p>In all views, clicking in the details panel with an item selected will open the item for editing if it is not repeating and otherwise prompt for the instance(s) to be changed.</p>
<p>In all views, pressing <em>O</em> will open a dialog to choose the outline depth. Pressing <em>L</em> will toggle the display of a column displaying item <em>labels</em> where, for example, an item with <span class="citation">@a</span>, <span class="citation">@d</span> and <span class="citation">@u</span> fields would have the label "adu". Pressing <em>S</em> will show a text verion of the current display suitable for copy and paste. The text version will respect the current outline depth in the view.</p>
<p>In custom view it is possible to export the current view in either text or CSV (comma separated values) format to a file of your choosing.</p>
<p>Note. In custom view you need to move the focus from the view specification entry field in order for the shortcuts <em>O</em>, <em>L</em> and <em>S</em> to work.</p>
<p>In all views:</p>
<ul>
<li><p>if an item is selected:</p>
<ul>
<li><p>pressing <em>Shift-H</em> will show a history of changes for the file containing the selected item, first prompting for the number of changes.</p></li>
<li><p>pressing <em>Shift-X</em> will export the selected item in iCal format.</p></li>
</ul></li>
<li><p>if an item is not selected:</p>
<ul>
<li><p>pressing <em>Shift-H</em> will show a history of changes for all files, first prompting for the number of changes.</p></li>
<li><p>pressing <em>Shift-X</em> will export all items in active calendars in iCal format.</p></li>
</ul></li>
</ul>
<h3 id="agenda-view"><a href="#agenda-view">Agenda View</a></h3>
<p>What you need to know now beginning with your schedule for the next few days and followed by items in these groups:</p>
<ul>
<li><p><strong>In basket</strong>: In basket items and items with missing types or other errors.</p></li>
<li><p><strong>Now</strong>: All <em>scheduled</em> (dated) tasks whose due dates have passed including delegated tasks and waiting tasks (tasks with unfinished prerequisites) grouped by available, delegated and waiting and, within each group, by the due date.</p></li>
<li><p><strong>Next</strong>: All <em>unscheduled</em> (undated) tasks grouped by context (home, office, phone, computer, errands and so forth) and sorted by priority and extent. These tasks correspond to GTD's <em>next actions</em>. These are tasks which don't really have a deadline and can be completed whenever a convenient opportunity arises. Check this view, for example, before you leave to run errands for opportunities to clear other errands.</p></li>
<li><p><strong>Someday</strong>: Someday (maybe) items for periodic review.</p></li>
</ul>
<p>Note: Finished tasks, actions and notes are not displayed in this view.</p>
<h3 id="week-and-month-views"><a href="#week-and-month-views">Week and Month Views</a></h3>
<p>These views only differ in whether the graphic in the top pane describes a week or a month. All dated items appear in the middle, tree pane in these view, grouped by date and sorted by starting time and item type. Displayed items include:</p>
<ul>
<li><p>All non-repeating, dated items.</p></li>
<li><p>All repetitions of repeating items with a finite number of repetitions. This includes 'list-only' repeating items and items with <code>&u</code> (until) or <code>&t</code> (total number of repetitions) entries.</p></li>
<li><p>For repeating items with an infinite number of repetitions, those repetitions that occur within the first <code>weeks_after</code> weeks after the current week are displayed along with the first repetition after this interval. This assures that at least one repetition will be displayed for infrequently repeating items such as voting for president.</p></li>
</ul>
<p>The graphic display in the top pane has a square cell for each week/month date. Within this cell, scheduled, <em>busy</em> times are indicated by segments of a square busy border that surrounds the date. This border can be regarded as a 24-hour clock face that proceeds clockwise from 12am at the lower, left-hand corner with 6 hour segments for each side: 12am - 6am moving upward on the left side, 6am - 12pm moving rightward along the top, 12pm - 6pm moving downward along the right side and, finally, 6pm - 12pm moving leftward along the bottom. When nothing is scheduled for a date, the border is blank. When only one event is scheduled for a date, say from 9am until 3pm, then the border would be colored from the middle of the top side (9am) around the top, right-hand corner and downward to the middle of the right side (3pm). When other periods are scheduled, corresponding portions of the border would be colored. If two or more scheduled periods overlap, then a small, red box appears in the lower, left-hand corner of the border to warn of the conflict.</p>
<p>When the top pane has the focus, the left/right cursor keys move to the previous/subsequent week or month and the up/down cursor keys move to the previous/subsequent date. Either <em>Home</em> or <em>Space</em> moves the display to the current date. Pressing <em>J</em> will first prompt for a fuzzy-parsed date and then "jump" to the specified date. Whenever a date is selected in the top pane, the date tree in the middle pane is scrolled, if necessary, to display the selected date first. Whenever a date is selected in either week or month view, the same date is automatically becomes the selection in the other view as well.</p>
<p>Note: If a date is selected for which no items are scheduled, then the last date with scheduled items on or before the selected date will become the selected date in the middle, tree pane.</p>
<p>Tip: Want to see your next appointment with Dr. Jones? Switch to day view and enter "jones" in the filter.</p>
<p>Tip. You can display a list of busy times or, after providing the needed period in minutes, a list of free times that would accommodate the requirement within the selected week/month. Both options are in the <em>View</em> menu.</p>
<h3 id="week-view"><a href="#week-view">Week View</a></h3>
<p>Events and occasions displayed graphically by week with one column for each day. Left and right cursor keys change, respectively, to the previous and next week. Up and down cursor keys select, respectively, the previous and next items within the given week. Items can also be selected by moving the mouse over the item. The details for the selected item are displayed at the bottom of the screen. Pressing return with an item selected or double-clicking an item opens a context menu. Control-clicking an unscheduled time opens a dialog to create an event for that date and time.</p>
<h3 id="month-view"><a href="#month-view">Month View</a></h3>
<p>Events and occasions displayed graphically by month. Left and right cursor keys change, respectively, to the previous and next month. Up and down cursor keys select, respectively, the previous and next days within the given month. Days can also be selected by moving the mouse over the item. A list of occasions and events for the selected day is displayed at the bottom of the screen. Double clicking a date or pressing <em>Return</em> with a date selected opens a dialog to create an item for that date.</p>
<p>The current date and days with occasions are highlighted.</p>
<p>Tip. You can display a list of busy times or, after providing the needed period in minutes, a list of free times that would accommodate the requirement within the selected month. Both options are in the <em>View</em> menu.</p>
<h3 id="tag-view"><a href="#tag-view">Tag View</a></h3>
<p>All items with tag entries grouped by tag and sorted by type and <em>relevant datetime</em>. Note that items with multiple tags will be listed under each tag.</p>
<p>Tip: Use the filter to limit the display to items with a particular tag.</p>
<h3 id="keyword-view"><a href="#keyword-view">Keyword View</a></h3>
<p>All items grouped by keyword and sorted by type and <em>relevant datetime</em>.</p>
<h3 id="path-view"><a href="#path-view">Path View</a></h3>
<p>All items grouped by file path and sorted by type and <em>relevant datetime</em>. Use this view to review the status of your projects.</p>
<p>The <em>relevant datetime</em> is the past due date for any past due task, the starting datetime for any non-repeating item and the datetime of the next instance for any repeating item.</p>
<p>Note: Items that you have "commented out" by beginning the item with a <code>#</code> will only be visible in this view.</p>
<h3 id="note-view"><a href="#note-view">Note View</a></h3>
<p>All notes grouped and sorted by keyword and summary.</p>
<h3 id="custom"><a href="#custom">Custom</a></h3>
<p>Design your own view. See <a href="#custom-view">Custom view</a> for details.</p>
<h2 id="creating-new-items"><a href="#creating-new-items">Creating New Items</a></h2>
<p>Items of any type can be created by pressing <em>N</em> in the GUI and then providing the details for the item in the resulting dialog.</p>
<p>An event can also be created by double-clicking in a date cell in either Week or Month View - the corresponding date will be entered as the starting date when the dialog opens.</p>
<p>When editing an item, clicking on <em>Finish</em> or pressing <em>Shift-Return</em> will validate your entry. If there are errors, they will be displayed and you can return to the editor to correct them. If there are no errors, this will be indicated in a dialog, e.g.,</p>
<pre><code>Task scheduled for Tue Jun 03
Save changes and exit?</code></pre>
<p>Tip. When creating or editing a repeating item, pressing <em>Finish</em> will also display a list of instances that will be generated.</p>
<p>Click on <em>Ok</em> or press <em>Return</em> or <em>Shift-Return</em> to save the item and close the editor. Click on <em>Cancel</em> or press <em>Escape</em> to return to the editor.</p>
<p>If this is a new item and there are no errors, clicking on <em>Ok</em> or pressing <em>Return</em> will open a dialog to select the file to store the item with the current monthly file already selected. Pressing <em>Shift-Return</em> will bypass the file selection dialog and save to the current monthly file.</p>
<h2 id="editing-existing-items"><a href="#editing-existing-items">Editing Existing Items</a></h2>
<p>Double-clicking an item or pressing <em>Return</em> when an item is selected will open a context menu of possible actions:</p>
<ul>
<li>Copy</li>
<li>Delete</li>
<li>Edit</li>
<li>Edit file</li>
<li>Finish (unfinished tasks only)</li>
<li>Reschedule</li>
<li>Schedule new</li>
<li>Klone as timer</li>
<li>Open link (items with <code>@g</code> entries only)</li>
<li>Show user details (items with <code>@u</code> entries only)</li>
</ul>
<p>When either <em>Copy</em> or <em>Edit</em> is chosen for a repeating item, you can further choose:</p>
<ol style="list-style-type: decimal">
<li>this instance</li>
<li>this and all subsequent instances</li>
<li>all instances</li>
</ol>
<p>When <em>Delete</em> is chosen for a repeating item, a further choice is available:</p>
<ol start="4" style="list-style-type: decimal">
<li>all previous instances</li>
</ol>
<p>Tip: Use <em>Reschedule</em> to enter a date for an undated item or to change the scheduled date for the item or the selected instance of a repeating item. All you have to do is enter the new (fuzzy parsed) datetime.</p>
<h2 id="timers"><a href="#timers">Timers</a></h2>
<h3 id="countdown-timer"><a href="#countdown-timer">countdown timer</a></h3>
<p>To start a countdown timer press <em>z</em>, change the default number of minutes if necessary and press <em>Return</em>. The time that the timer will expire will be displayed in the status bar with a <code>-</code> prefix.</p>
<p>If <code>countdown_command</code> is given in <em>etmtk.cfg</em>, then it will be executed when the timer expires and the countdown message dialog will appear with the last chosen number of minutes as the default. You can either press <em>Return</em> to start another countdown or press <em>Escape</em> to cancel. If activated, the time that the countdown timer will expire will be displayed in the status bar.</p>
<h3 id="snooze-timer"><a href="#snooze-timer">snooze timer</a></h3>
<p>When the last alert of type <code>m</code> (message) is triggered for an item, the alert dialog that is displayed offers the option of snoozing, i.e., repeating the alert after a number of minutes you choose. If activated, the alert corresponding to snooze timer can be displayed along with any other remaining alerts using <em>Tools/Show remaining alerts</em>.</p>
<p>If <code>snooze_command</code> is given in <em>etmtk.cfg</em>, then it will be executed when the snooze timer expires and the alert message dialog will appear with the last chosen number of minutes as the default. You can either press <em>Return</em> to snooze again or press <em>Escape</em> to cancel.</p>
<h3 id="action-timer"><a href="#action-timer">action timer</a></h3>
<p>For people who bill their time or just like to keep track of how they spend their time, etm allows you to create an action by pressing <em>T</em> to start a timer. You will see an entry area with a list of any existing timers below. As you enter characters in the entry area, the list below will shrink to those whose beginnings match the characters you've entered. You can either select a timer from the list to start that timer or enter new name in the entry area to create and start a new timer. If a timer is running, it will automatically be paused when you start a new timer or switch to another timer.</p>
<p>Tip. Devoting time to two different clients this morning? Create two timers, one for each client and just switch back and forth using <em>T</em> when you switch from one client to the other. The timers are ordered in the list so that the most recently paused will be at the top.</p>
<p>While a timer is selected, the name, elapsed time and status - running or paused - is displayed in the status bar along with the number of active timers in parentheses. Pressing <em>I</em> toggles the timer between running and paused. You can configure etm's options to, for example, play one sound at intervals when a timer is running and another sound when the selected timer is paused and you can also specify the length of the interval and the volume.</p>
<p>When one or more timers are active and none are running, idle time is accumulated and displayed, by default, in the status bar. The idle time display can be toggled on and off and accumulated idle time can be reset to zero. It is also possible to transfer minutes from accumulated idle time to the current action timer.</p>
<p>When you have one or more active timers, you can press <em>Shift-T</em> to select one to finish. The selected timer will be paused if it is running and you will be presented with an entry area to create a new action with the following details already filled in: <code>~ timer name @s starting datetime @e elapsed time</code>. You can edit this entry in any way you like and then save it. When you do so, this timer will be removed from your list of active timers. You can also press <em>Shift-I</em> to select a timer to delete. Any accumulated time for the selected timer will be added to the accumulated idle time and the timer will be removed from the list of active timers.</p>
<p>It is also possible to start a timer by selecting an event, note, task or whatever, from one of <em>etm</em>'s Views and then choosing <em>Item/Klone as timer</em> from the menu or pressing <em>K</em>. A start timer dialog will be opened with the summary of the item you selected as the name together with any @-keys from the selected item that are listed in <code>action_keys</code> in your <code>etmtk.cfg</code>. You can edit this entry if you like or just press <em>Return</em> to accept it and start the timer. If you already have an active timer with this name, it will be restarted. Otherwise a new timer will be created and started.</p>
<p>Tip. Suppose you have a client, John Smith, and will be doing some work for him this morning relating to the project "Motion". If you don't already have a task relating to this begin by creating one for today, June 16, 2015, by pressing <em>N</em> and entering</p>
<pre><code>- work @k SmithJohn:Motion @s +0</code></pre>
<p>The first activity related to this task involves a phone call to Sally. Select the task you just created and then press <em>K</em> to start a timer. Change <code>work</code> to <code>call Sally</code> and press <em>Return</em> to start the timer. When you've finished the call, press <em>I</em> to pause the timer. Based on this phone conversation, you decide the next activity should be to review Local Rule 4567, so once again select the task, press <em>K</em> and then change <code>work</code> to <code>review Local Rule 4567</code> and press <em>Return</em> to start this timer. When you're done, once again press <em>I</em> to pause this timer. You can repeat this process as often as you like. If you need to spend more time on 4567, press <em>T</em> and select it from the list of timers. When you're done, you can press <em>Shift-T</em> to select a timer from the list and finish it. Selecting the "call Sally" timer would produce an entry for the new action something like the following</p>
<pre><code>~ call Sally @k SmithJohn:Motion @s 2015-06-16 9:27am @e 12m</code></pre>
<p>You can edit this action if you like, but it is already set up to bill 12 minutes to the "Motion" project for client "John Smith" for an activity labeled "call Sally" and will appear as such in reports you generate for this period, so you can just save it as it is. Do the same with your other timers and you will have a complete record of time spent by client, project and activity for the day.</p>
<p>The state of your active timers is saved whenever you quit etm using by choosing <em>Quit</em> from the file menu or using the shortcut so that whenever you restart etm on the same day, the active timers will be restored.</p>
<p>If etm is running when a new day begins (midnight local time) or if you stop etm and start it again on a later date, in-basket entries for each of your active timers will be created in the relevant monthly file. These entries will be exactly the same as if you had finished each of the timers save for the use of <code>$</code> (in basket) rather than <code>~</code> (action) as the type character. You can edit or delete these as you wish. If a timer is selected (displayed in the status bar), then a new timer with the same name will be created for the new date but with zero elapsed time. If the timer was running at midnight, then the new timer will also be running. Idle time will automatically be reset to zero.</p>
<h2 id="sharing-with-other-calendar-applications"><a href="#sharing-with-other-calendar-applications">Sharing with other calendar applications</a></h2>
<p>Both export and import are supported for files in iCalendar format in ways that depend upon settings in <code>etmtk.cfg</code>.</p>
<p>If an absolute path is entered for <code>current_icsfolder</code>, for example, then <code>.ics</code> files corresponding to the entries in <code>calendars</code> will be created in this folder and updated as necessary. If there are no entries in calendars, then a single file, <code>all.ics</code>, will be created in this folder and updated as necessary.</p>
<p>If an item is selected, then pressing Shift-X in the gui will export the selected item in iCalendar format to <code>icsitem_file</code>. If an item is not selected, pressing Shift-X will export the active calendars in iCalendar format to <code>icscal_file</code>.</p>
<p>If <code>icssync_folder</code> is given, then files in this folder with the extension <code>.txt</code> and <code>.ics</code> will automatically kept concurrent using export to iCalendar and import from iCalendar. I.e., if the <code>.txt</code> file is more recent than than the <code>.ics</code> then the <code>.txt</code> file will be exported to the <code>.ics</code> file. On the other hand, if the <code>.ics</code> file is more recent then it will be imported to the <code>.txt</code> file. In either case, the contents of the file to be updated will be overwritten with the new content and the last acess/modified times for both will be set to the current time.</p>
<p>If <code>ics_subscriptions</code> is given, it should be a list of [URL, FILE] tuples. The URL is a calendar subscription, e.g., for a Google Calendar subscription the URL, FILE tuple would be something like:</p>
<pre><code> ['https://www.google.com/calendar/ical/.../basic.ics', 'personal/google.txt']
</code></pre>
<p>With this entry, pressing Shift-M in the gui would import the calendar from the URL, convert it from ics to etm format and then write the result to <code>personal/google.txt</code> in the etm data directory. Note that this data file should be regarded as read-only since any changes made to it will be lost with the next subscription update.</p>
<p>Finally, when creating a new item in the etm editor, you can paste an iCalendar entry such as the following VEVENT:</p>
<pre><code>BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ForeTees//NONSGML v1.0//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VEVENT
UID:1403607754438-11547@127.0.0.1-33
DTSTAMP:20140624T070234
DTSTART:20140630T080000
SUMMARY:8:00 AM Tennis Reservation
LOCATION:Governors Club
DESCRIPTION: Player 1: ...
URL:http://www1.foretees.com/governorsclub
END:VEVENT
END:VCALENDAR</code></pre>
<p>When you press <em>Finish</em>, the entry will be converted to etm format</p>
<pre><code>^ 8:00 AM Tennis Reservation @s 2014-06-30 8am
@d Player 1: ...
@z US/Eastern</code></pre>
<p>and you can choose the file to hold it.</p>
<p>The following etm and iCalendar item types are supported:</p>
<ul>
<li><p>export from etm:</p>
<ul>
<li>occasion to VEVENT without end time</li>
<li>event (with or without extent) to VEVENT</li>
<li>action to VJOURNAL</li>
<li>note to VJOURNAL</li>
<li>task to VTODO</li>
<li>delegated task to VTODO</li>
<li>task group to VTODO (one for each job)</li>
</ul></li>
<li><p>import from iCalendar</p>
<ul>
<li>VEVENT without end time to occasion</li>
<li>VEVENT with end time to event</li>
<li>VJOURNAL to note</li>
<li>VTODO to task</li>
</ul></li>
</ul>
<h2 id="tools"><a href="#tools">Tools</a></h2>
<h3 id="date-and-time-calculator"><a href="#date-and-time-calculator">Date and time calculator</a></h3>
<p>Enter an expression of the form <code>x [+-] y</code> where <code>x</code> is a date and <code>y</code> is either a date or a time period if <code>-</code> is used and a time period if <code>+</code> is used. Both <code>x</code> and <code>y</code> can be followed by timezones, e.g.,</p>
<pre><code> 4/20 6:15p US/Central - 4/20 4:50p Asia/Shanghai:
14h25m</code></pre>
<p>or</p>
<pre><code> 4/20 4:50p Asia/Shanghai + 14h25m US/Central:
2014-04-20 18:15-0500</code></pre>
<p>Fuzzy dates (other than relative date expressions using <code>+</code> or <code>-</code>) can be used to specify date entries. The local timezone is assumed when none is given.</p>
<h3 id="available-dates-calculator"><a href="#available-dates-calculator">Available dates calculator</a></h3>
<p>Need to see a list of possible dates for a meeting? Get a list of busy dates from each of the members of the group and then use an expression of the form</p>
<pre><code>start; end; busy</code></pre>
<p>where start and end are dates and busy is a comma separated list of the busy dates or intervals for the members. E.g., if your group needs to meet between 6/1 and 6/30 and the members indicate that they cannot meet on 6/2, 6/14-6/22, 6/5-6/9, 6/11-6/15 or 6/17-6/29, then entering</p>
<pre><code>6/1; 6/30; 6/2, 6/14-6/22, 6/5-6/9, 6/11-6/15, 6/17-6/29</code></pre>
<p>would give:</p>
<pre><code>Sun Jun 01
Tue Jun 03
Wed Jun 04
Tue Jun 10
Mon Jun 30</code></pre>
<p>as the possible dates for the meeting.</p>
<h3 id="yearly-calendar"><a href="#yearly-calendar">Yearly calendar</a></h3>
<p>Gives a display such as</p>
<pre><code> January 2014 February 2014 March 2014
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 3 4 5 1 2 1 2
6 7 8 9 10 11 12 3 4 5 6 7 8 9 3 4 5 6 7 8 9
13 14 15 16 17 18 19 10 11 12 13 14 15 16 10 11 12 13 14 15 16
20 21 22 23 24 25 26 17 18 19 20 21 22 23 17 18 19 20 21 22 23
27 28 29 30 31 24 25 26 27 28 24 25 26 27 28 29 30
31
April 2014 May 2014 June 2014
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 3 4 5 6 1 2 3 4 1
7 8 9 10 11 12 13 5 6 7 8 9 10 11 2 3 4 5 6 7 8
14 15 16 17 18 19 20 12 13 14 15 16 17 18 9 10 11 12 13 14 15
21 22 23 24 25 26 27 19 20 21 22 23 24 25 16 17 18 19 20 21 22
28 29 30 26 27 28 29 30 31 23 24 25 26 27 28 29
30
July 2014 August 2014 September 2014
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 3 4 5 6 1 2 3 1 2 3 4 5 6 7
7 8 9 10 11 12 13 4 5 6 7 8 9 10 8 9 10 11 12 13 14
14 15 16 17 18 19 20 11 12 13 14 15 16 17 15 16 17 18 19 20 21
21 22 23 24 25 26 27 18 19 20 21 22 23 24 22 23 24 25 26 27 28
28 29 30 31 25 26 27 28 29 30 31 29 30
October 2014 November 2014 December 2014
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 3 4 5 1 2 1 2 3 4 5 6 7
6 7 8 9 10 11 12 3 4 5 6 7 8 9 8 9 10 11 12 13 14
13 14 15 16 17 18 19 10 11 12 13 14 15 16 15 16 17 18 19 20 21
20 21 22 23 24 25 26 17 18 19 20 21 22 23 22 23 24 25 26 27 28
27 28 29 30 31 24 25 26 27 28 29 30 29 30 31</code></pre>
<p>Left and right cursor keys move backward and forward a year at a time, respectively, and pressing the Home key returns to the current year.</p>
<h3 id="history-of-changes"><a href="#history-of-changes">History of changes</a></h3>
<p>This requires that either <em>git</em> or <em>mercurial</em> is installed. If an item is selected show a history of changes to the file that contains the item. Otherwise show a history of changes for all etm data files. In either case, choose an integer number of the most recent changes to show or choose 0 to show all changes.</p>
<h2 id="calendars"><a href="#calendars">Calendars</a></h2>
<p><em>etm</em> supports using the directory structure in your data directory to create separate <em>calendars</em>. For example, my wife, <em>erp</em>, and I, <em>dag</em>, separate personal and shared items with this structure:</p>
<pre><code>root etm data directory
personal
dag
erp
shared
holidays
birthdays
events</code></pre>
<p>Here, our etm configuration files are located in our home directories:</p>
<pre><code>~dag/.etm/etmtk.cfg
~erp/.etm/etmtk.cfg</code></pre>
<p>Both contain <code>datadir</code> entries specifying the common root data directory mentioned above with these additional entries, respectively:</p>
<p>In <code>~dag/.etm/etmtk.cfg</code>:</p>
<pre><code> calendars
- [dag, true, personal/dag]
- [erp, false, personal/erp]
- [shared, true, shared]</code></pre>
<p>In <code>~erp/.etm/etmtk.cfg</code>:</p>
<pre><code> calendars
- [erp, true, personal/erp]
- [dag, false, personal/dag]
- [shared, true, shared]</code></pre>
<p>Thus, by default, both <em>dag</em> and <em>erp</em> see the entries from their personal files as well as the shared entries and each can optionally view the entries from the other's personal files as well. See the <a href="#preferences">Preferences</a> for details on the <code>calendars</code> entry.</p>
<p>Note for Windows users. The path separator needs to be "escaped" in the calendar paths, e.g., you should enter</p>
<pre><code> - [dag, true, personal\\dag]</code></pre>
<p>instead of</p>
<pre><code> - [dag, true, personal\dag]</code></pre>
<h2 id="data-organization"><a href="#data-organization">Data Organization</a></h2>
<p><em>etm</em> offers many ways of organizing your data. Perhaps, the most obvious is by <em>path</em>, i.e., the directory structure inside your data directory. <em>Path View</em> presents your data using this organization and, as noted above, calendars can be specified using this structure to allow you to choose quickly the calendars whose items will appear in other etm views as well.</p>
<p>The other hierarchical way of organizing your data uses the keywords you specify in your items. <em>Keyword View</em> presents your data using this organization. E.g.,</p>
<pre><code>- my task @k A:B:C
- my other task</code></pre>
<p>would appear in <em>Keyword View</em> as:</p>
<pre><code>A
B
C
- my task
~ none ~
- my other task</code></pre>
<p>There are no hard and fast rules about how to use these hierarchies but the goal is a system that makes complementary uses of path and keyword and fits your needs. As with any filing system, planning and consistency are paramount. For example, one pattern of use for a business might be to use folders for departments and people and keywords for client and project.</p>
<p>It is also possible to add one or more tags to items and use <em>Tag View</em> to see the resulting organization. For example</p>
<pre><code>- item 1 @t red, white, blue
- item 2 @t red @t white
- item 3 @t white @t blue
- item 4 @t red, blue
- item 5 @t white</code></pre>
<p>would appear in <em>Tag View</em> as</p>
<pre><code>blue
- item 1
- item 3
- item 4
red
- item 1
- item 2
- item 4
white
- item 1
- item 2
- item 3
- item 5</code></pre>
<p>A final important way of organizing your data is provided by <em>context</em>. This is designed to support a GTD (Getting Things Done) common practice where possible contexts includes things like phone, errands, email and so forth. Undated tasks such as</p>
<pre><code>- pick up milk @c errands
- call Saul @c phone
- confirm schedule with Bob @c email</code></pre>
<p>would appear <em>Agenda View</em> as</p>
<pre><code>Next
email
- confirm schedule with Bob
errands
- pick up milk
phone
- call Saul
</code></pre>
<p>When you are next checking email, running errands, using the phone or whatever, you can check <em>Agenda View</em> to see what else might be accomplished at the same time. Note that, unlike tags, items can have at most a single context.</p>
<h2 id="colors"><a href="#colors">Colors</a></h2>
<p>Versions of etm after 3.1.39 support custom settings for both foreground (font) and background colors in the GUI. If a file named <code>colors.cfg</code> is found in the etm directory on startup, then the color settings in this file will override the default color settings. If this file is not found, then it will be created and populated with the default color settings. This file can be opened for editing in etm using <em>File/Open/Configuration file</em> from the main menu.</p>
<p>Example files for both dark and light backgrounds are available for download and customization. You can also download <code>colors.py</code>, set your preferred background color inside this script and then run it to see how the different font colors would appear against your chosen background. See also the setting for <code>style</code> under Preferences.</p>
<h2 id="internationalization"><a href="#internationalization">Internationalization</a></h2>
<p>Versions of etm after 3.1.20 provide support for languages beyond English.</p>
<h3 id="end-user"><a href="#end-user">End User</a></h3>
<p>If you, for example, are French and would like to use a version of etm in which menu items and standard phrases are French then you need to download the file <code>fr_FR.mo</code> either from <a href="https://github.com/dagraham/locale">GitHub locale</a> or from <a href="http://people.duke.edu/~dgraham/etmtk/languages">etmtk languages</a> and copy it to the following location in your <code>etmdir</code>:</p>
<pre><code><your etmdir>
languages
fr_FR
LC_MESSAGES
fr_FR.mo
</code></pre>
<p>creating the corresponding directory structure when necessary. Be sure to get the file with the <code>.mo</code> extension, not the one with the <code>.po</code> extension. Next you need to create a file named <code>locale.cfg</code> in your <code>etmdir</code> with the line:</p>
<pre><code>[[fr_FR, UTF-8], QLocale.French, QLocale.France]</code></pre>
<p>perhaps modifying <code>UTF-8</code> to reflect your actual file encoding.</p>
<p>That's it! When you next start etm, <code>locale.cfg</code> will be read, <code>fr_FR</code> will be set as the desired locale and, if it can be found in the specified directory, the translations in <code>fr_FR.mo</code> will be loaded. Now, e.g, instead of <em>Agenda</em> you will see <em>Ordre du jour</em>.</p>
<h3 id="translator"><a href="#translator">Translator</a></h3>
<p>If you would like to assist in providing etm for a particular language, the process is pretty simple. You will need to download the program <a href="https://poedit.net/">poedit</a>. A free version is available for all major platforms.</p>
<p>In the etm source code, whenever a word or phrase appears that will be seen by the user, it is wrapped in a special format using <code>_()</code> so that, e.g., <code>Agenda</code> appears in the source code as <code>_("Agenda")</code>, <code>Today</code> as <code>_("Today")</code> and so forth.</p>
<p>When etm is being prepared for distribution a program called <em>gettext</em> is used to extract the <code>_()</code> entries from wherever they appear in the source and copy them to specially formatted file called <code>etm.pot</code>. This file can be then be used in the open-source program <em>poedit</em> to create a special translation files for different languages. This is how <code>fr_FR.po</code> was created, for example. Translation files are available from the above sources for French (<code>fr_FR.po</code>), German (<code>de_DE.po</code>), Spanish (<code>es_ES.po</code>) and Polish (<code>pl_PL.mo</code>). Alternatively, <code>etm.pot</code> is also available and you can use it to create whatever translation files you wish.</p>
<p>When a <code>.po</code> translation file is opened in <em>poedit</em>, two columns are displayed, the first lists the <code>_()</code> entries from the source code and the second lists the corresponding translation. E.g.,</p>
<pre><code> Agenda Ordre du jour
Today Aujourd’hui</code></pre>
<p>Initially, of course, the translation column is empty and it is the job of the translator to provide the translations. The <em>pro</em> version of <em>poedit</em> (~ $20) provides a third column with likely guesses about the appropriate translation. Most of the choices in <code>fr_FR.po</code>, in fact, came from accepting these best guesses since my knowledge of French is miniscule.</p>
<p>Whenever a <code>.po</code> file is saved in <em>poedit</em>, a compiled version with the extension <code>.mo</code> is automatically created. This compiled version is the one actually used by etm and the only file that an end user needs.</p>
<p>When an end user has followed the steps given above to enable support for a particular language, the actual translations will, of course be limited to those with "second column choices". Extending the example above, suppose the translator has omitted some items</p>
<pre><code> Agenda Ordre du jour
Yesterday
Today Aujourd’hui
Tomorrow</code></pre>
<p>Then whenever <code>_("Agenda")</code> appears in the source, it will effectively be replaced by <code>"Ordre du jour"</code> and whenever <code>_("Yesterday")</code> appears, it will be replaced by <code>"Yesterday"</code>. I.e., when a translation is available, it will be used; otherwise, the original text will be used.</p>
<p>A translator can thus do as much or as little as he or she pleases and then send me the resulting <code>.po</code> file. I'll replace the current on-line version with this updated version so the next translator can improve upon prior results.</p>
<h1 id="item-types"><a href="#item-types">Item types</a></h1>
<p>There are several types of items in etm. Each item begins with a type character such as an asterisk (event) and continues on one or more lines either until the end of the file is reached or another line is found that begins with a type character. The type character for each item is followed by the item summary and then, perhaps, by one or more <code>@key value</code> pairs - see <a href="#keys">@-Keys</a> for details. The order in which such pairs are entered does not matter.</p>
<h2 id="action"><a href="#action">~ Action</a></h2>
<p>A record of the expenditure of time (<code>@e</code>) and/or money (<code>@x</code>). Actions are not reminders, they are instead records of how time and/or money was actually spent. Action lines begin with a tilde, <code>~</code>.</p>
<pre><code> ~ picked up lumber and paint @s mon 3p @e 1h15m @x 127.32</code></pre>
<p>Entries such as <code>@s mon 3p</code>, <code>@e 1h15m</code> and <code>@x 127.32</code> are discussed below under <em>Item details</em>. Action entries form the basis for time and expense billing using action type custom views - see <a href="#custom-view">Custom view</a> for details.</p>
<p>Tip: You can use either path or keyword or a combination of the two to organize your actions.</p>
<h2 id="event"><a href="#event">* Event</a></h2>
<p>Something that will happen on particular day(s) and time(s). Event lines begin with an asterick, <code>*</code>.</p>
<pre><code> * dinner with Karen and Al @s sat 7p @e 3h</code></pre>
<p>Events have a starting datetime, <code>@s</code> and an extent, <code>@e</code>. The ending datetime is given implicitly as the sum of the starting datetime and the extent. Events that span more than one day are possible, e.g.,</p>
<pre><code> * Sales conference @s 9a wed @e 2d8h</code></pre>
<p>begins at 9am on Wednesday and ends at 5pm on Friday.</p>
<p>An event without an <code>@e</code> entry or with <code>@e 0</code> is regarded as a <em>reminder</em> and, since there is no extent, will not be displayed in <em>busy times</em>.</p>
<h2 id="occasion"><a href="#occasion">^ Occasion</a></h2>
<p>Holidays, anniversaries, birthdays and such. Similar to an event with a date but no starting time and no extent. Occasions begin with a caret sign, <code>^</code>.</p>
<pre><code> ^ The !1776! Independence Day @s 2010-07-04 @r y &M 7 &m 4</code></pre>
<p>On July 4, 2013, this would appear as <code>The 237th Independence Day</code>. Here !1776!` is an example of an <em>anniversary substitution</em> - see <a href="#dates">Dates</a> for details.</p>
<h2 id="note"><a href="#note">! Note</a></h2>
<p>A record of some useful information. Note lines begin with an exclamation point, <code>!</code>.</p>
<pre><code>! xyz software @k software:passwords @d user: dnlg, pw: abc123def</code></pre>
<p>Tip: Since both the GUI and CLI note views group and sort by keyword, it is a good idea to use keywords to organize your notes.</p>
<h2 id="and-tasks"><a href="#and-tasks">-, % and + Tasks</a></h2>
<p>Tasks are reminders of something that needs to be done. There are three possible type characters for tasks: <code>-</code>, <code>%</code> and <code>+</code>; these are discussed below. Each of these can be further distinguished by whether or not the task has entries for <code>@e</code> and/or <code>@s</code>.</p>
<p>When an <code>@e</code> (extent) is provided for any type of task, it is regarded as an estimate of the time required to complete the task.</p>
<ul>
<li><p>Tasks without an <code>@s</code> entry have no due date and are to be done whenever convenient.</p></li>
<li><p>Tasks with an <code>@s</code> entry that specifies <code>12am</code> (or <code>0h</code>) as the starting time are to be completed on or before the date specified.</p></li>
<li><p>Tasks with an <code>@s</code> entry that specifies a starting time <em>other than</em> <code>12am</code> (or <code>0h</code>) but without an <code>@e</code> entry are to be completed on or before the date <em>and time</em> specified. These will be displayed in etm Agenda and Day views before other tasks, sorted by and displaying the starting time.</p></li>
<li><p>Tasks with an <code>@s</code> entry that specifies a starting time <em>other than</em> <code>12am</code> (or <code>0h</code>) and with an <code>@e</code> entry are to be completed during the period that extends from the starting time until <code>@e</code> after the starting time. These will be displayed in etm Agenda and Day views before other tasks, sorted by and displaying the time period in the same manner as events. This period will be regarded as busy time and treated as such by etm in, e.g., Week view. [Tip: Use a non-midnight starting time and an extent when you want to block off a specific period to complete a task.]</p></li>
</ul>
<h3 id="task"><a href="#task">- Task</a></h3>
<p>This is the basic task and begins with a minus sign, <code>-</code>.</p>
<pre><code>- pay bills @s Oct 25</code></pre>
<p>A task with an <code>@s</code> entry becomes due on that date and time and past due when that date has passed. If the task also has an <code>@b</code> begin-by entry, then advance warnings of the task will begin appearing the specified number of days before the task is due.</p>
<h3 id="delegated-task"><a href="#delegated-task">% Delegated task</a></h3>
<p>A task that is assigned to someone else, usually the person designated in an <code>@u</code> entry. Delegated tasks begin with a percent sign, <code>%</code>.</p>
<pre><code> % make reservations for trip @u joe @s fri</code></pre>
<h3 id="task-group"><a href="#task-group">+ Task group</a></h3>
<p>A collection of related tasks, some of which may be prerequisite for others. Task groups begin with a plus sign, <code>+</code>.</p>
<pre><code> + dog house
@j pickup lumber and paint &q 1
@j cut pieces &q 2
@j assemble &q 3
@j paint &q 4</code></pre>
<p>Note that a task group is a single item and is treated as such. E.g., if any job is selected for editing then the entire group is displayed.</p>
<p>Individual jobs are given by the <code>@j</code> entries. The <em>queue</em> entries, <code>&q</code>, set the order --- tasks with smaller &q values are prerequisites for subsequent tasks with larger &q values. In the example above "pickup lumber and paint" does not have any prerequisites. "Pickup lumber and paint", however, is a prerequisite for "cut pieces" which, in turn, is a prerequisite for "assemble". "Assemble", "cut pieces" and "pickup lumber and paint" are all prerequisites for "paint".</p>
<h2 id="in-basket"><a href="#in-basket">$ In basket</a></h2>
<p>A quick, don't worry about the details item to be edited later when you have the time. In basket entries begin with a dollar sign, <code>$</code>.</p>
<pre><code> $ joe 919 123-4567</code></pre>
<p>If you create an item using <em>etm</em> and forget to provide a type character, an <code>$</code> will automatically be inserted.</p>
<h2 id="someday-maybe"><a href="#someday-maybe">? Someday maybe</a></h2>
<p>Something you don't want to forget about altogether but don't want to appear on your next or scheduled lists. Someday maybe items begin with a question mark, <code>?</code>. They are displayed under the heading <em>Someday</em> in Agenda view so that you can easily review them whenever you like.</p>
<pre><code> ? lose weight and exercise more</code></pre>
<h2 id="comment"><a href="#comment"># Comment</a></h2>
<p>Comments begin with a hash mark, <code>#</code>. Such items are ignored by etm save for appearing in the path view. Stick a hash mark in front of any item that you don't want to delete but don't want to see in your other views.</p>
<h2 id="defaults"><a href="#defaults">= Defaults</a></h2>
<p>Default entries begin with an equal sign, <code>=</code>. These entries consist of <code>@key value</code> pairs which then become the defaults for subsequent entries in the same file until another <code>=</code> entry is reached.</p>
<p>Suppose, for example, that a particular file contains items relating to "project_a" for "client_1". Then entering</p>
<pre><code>= @k client_1:project_a</code></pre>
<p>on the first line of the file and</p>
<pre><code>=</code></pre>
<p>on the twentieth line of the file would set the default keyword for entries between the first and twentieth line in the file.</p>
<h1 id="keys"><a href="#keys">@Keys</a></h1>
<h2 id="a-alert"><a href="#a-alert"><span class="citation">@a</span> alert</a></h2>
<p>The specification of the alert(s) to use with the item. One or more alerts can be specified in an item. E.g.,</p>
<pre><code>@a 10m, 5m
@a 1h: s</code></pre>
<p>would trigger the alert(s) specified by <code>default_alert</code> in your <code>etmtk.cfg</code> at 10 and 5 minutes before the starting time and a (s)ound alert one hour before the starting time.</p>
<p>The alert</p>
<pre><code>@a 2d: e; who@what.com, where2@when.org; filepath1, filepath2</code></pre>
<p>would send an email to the two listed recipients exactly 2 days (48 hours) before the starting time of the item with the item summary as the subject, with file1 and file2 as attachments and with the body of the message composed using <code>email_template</code> from your <code>etmtk.cfg</code>.</p>
<p>Similarly, the alert</p>
<pre><code>@a 10m: t; 9191234567@vtext.com, 9197654321@txt.att.net</code></pre>
<p>would send a text message 10 minutes before the starting time of the item to the two mobile phones listed (using 10 digit area code and carrier mms extension) together with the settings for <code>sms</code> in <code>etmtk.cfg</code>. If no numbers are given, the number and mms extension specified in <code>sms.phone</code> will be used. Here are the mms extensions for the major US carriers:</p>
<pre><code>Alltel @message.alltel.com
AT&T @txt.att.net
Nextel @messaging.nextel.com
Sprint @messaging.sprintpcs.com
SunCom @tms.suncom.com
T-mobile @tmomail.net
VoiceStream @voicestream.net
Verizon @vtext.com</code></pre>
<p>Finally,</p>
<pre><code>@a 0: p; program_path</code></pre>
<p>would execute <code>program_path</code> at the starting time of the item.</p>
<p>The format for each of these:</p>
<pre><code>@a <trigger times> [: action [; arguments]]</code></pre>
<p>In addition to the default action used when the optional <code>: action</code> is not given, there are the following possible values for <code>action</code>:</p>
<pre><code>d Execute alert_displaycmd in etmtk.cfg.
e; recipients[;attachments] Send an email to recipients
(a comma separated list of email addresses) optionally
attaching attachments (a comma separated list of file paths).
The item summary is used as the subject of the email and
the expanded value of email_template from etmtk.cfg as the
body. If there is an entry for @i (invitees), these email
addresses will be appended to the list of recipients.
m Display an internal etm message box using alert_template.
p; process Execute the command given by process.
s Execute alert_soundcmd in etmtk.cfg.
t [; phonenumbers] Send text messages to phonenumbers
(a comma separated list of 10 digit phone numbers with the
sms extension of the carrier appended) with the expanded
value of sms.message as the text message.
v Execute alert_voicecmd in etmtk.cfg.</code></pre>
<p>Note: either <code>e</code> or <code>p</code> can be combined with other actions in a single alert but not with one another.</p>
<h2 id="b-beginby"><a href="#b-beginby"><span class="citation">@b</span> beginby</a></h2>
<p>An integer number of days before the starting date time at which to begin displaying <em>begin by</em> notices. When notices are displayed they will be sorted by the item's starting datetime and then by the item's priority, if any.</p>
<h2 id="c-context"><a href="#c-context"><span class="citation">@c</span> context</a></h2>
<p>Intended primarily for tasks to indicate the context in which the task can be completed. Common contexts include home, office, phone, computer and errands. The "next view" supports this usage by showing undated tasks, grouped by context. If you're about to run errands, for example, you can open the "next view", look under "errands" and be sure that you will have no "wish I had remembered" regrets.</p>
<h2 id="d-description"><a href="#d-description"><span class="citation">@d</span> description</a></h2>
<p>An elaboration of the details of the item to complement the summary.</p>
<h2 id="e-extent"><a href="#e-extent"><span class="citation">@e</span> extent</a></h2>
<p>A time period string such as <code>1d2h</code> (1 day 2 hours). For an action, this would be the elapsed time. For a task, this could be an estimate of the time required for completion. For an event, this would be the duration. The ending time of the event would be this much later than the starting datetime.</p>
<p>Tip. Need to determine the appropriate value for <code>@e</code> for a flight when you have the departure and arrival datetimes but the timezones are different? The date calculator (shortcut Shift-D) will accept timezone information so that, e.g., entering the arrival time minus the departure time</p>
<pre><code>4/20 6:15p US/Central - 4/20 4:50p Asia/Shanghai</code></pre>
<p>into the calculator would give</p>
<pre><code>14h25m</code></pre>
<p>as the flight time.</p>
<h2 id="f-done-due"><a href="#f-done-due"><span class="citation">@f</span> done[; due]</a></h2>
<p>Datetimes; tasks, delegated tasks and task groups only. When a task is completed an <code>@f done</code> entry is added to the task. When the task has a due date, <code>; due</code> is appended to the entry. Similarly, when a job from a task group is completed in etm, an <code>&f done</code> or <code>&f done; due</code> entry is appended to the job and it is removed from the list of prerequisites for the other jobs. In both cases <code>done</code> is the completion datetime and <code>due</code>, if added, is the datetime that the task or job was due. The completed task or job is shown as finished on the completion date. When the last job in a task group is finished an <code>@f done</code> or <code>@f done; due</code> entry is added to the task group itself reflecting the datetime that the last job was done and, if the task group is repeating, the <code>&f</code> entries are removed from the individual jobs.</p>
<p>Another step is taken for repeating task groups. When the first job in a task group is completed, the <code>@s</code> entry is updated using the setting for <code>@o</code> (above) to show the next datetime the task group is due and the <code>@f</code> entry is removed from the task group. This means when some, but not all of the jobs for the current repetition have been completed, only these job completions will be displayed. Otherwise, when none of the jobs for the current repetition have been completed, then only that last completion of the task group itself will be displayed.</p>
<p>Consider, for example, the following repeating task group which repeats monthly on the last weekday on or before the 25th.</p>
<pre><code>+ pay bills @s 11/23 @f 10/24;10/25
@r m &w MO,TU,WE,TH,FR &m 23,24,25 &s -1
@j organize bills &q 1
@j pay on-line bills &q 3
@j get stamps, envelopes, checkbook &q 1
@j write checks &q 2
@j mail checks &q 3</code></pre>
<p>Here "organize bills" and "get stamps, envelopes, checkbook" have no prerequisites. "Organize bills", however, is a prerequisite for "pay on-line bills" and both "organize bills" and "get stamps, envelops, checkbook" are prerequisites for "write checks" which, in turn, is a prerequisite for "mail checks".</p>
<p>The repetition that was due on 10/25 was completed on 10/24. The next repetition was due on 11/23 and, since none of the jobs for this repetition have been completed, the completion of the group on 10/24 and the list of jobs due on 11/23 will be displayed initially. The following sequence of screen shots show the effect of completing the jobs for the 11/23 repetition one by one on 11/27.</p>
<h2 id="g-goto"><a href="#g-goto"><span class="citation">@g</span> goto</a></h2>
<p>The path to a file or a URL to be opened using the system default application when the user presses <em>G</em> in the GUI. E.g., here's a task to join the etm discussion group with the URL of the group as the link. In this case, pressing <em>G</em> would open the URL in your default browser.</p>
<pre><code>- join the etm discussion group @s +1/1
@g http://groups.google.com/group/eventandtaskmanager/topics
</code></pre>
<p>Template expansion is supported so it is also possible to use a <code>mailto</code> link such as the following:</p>
<pre><code>- the subject of the email @d The body of the email
@g mailto:sam@what.com?cc=joe@when.net\&subject=!summary!\&body=!d!
</code></pre>
<p>Pressing <em>G</em> with this item selected would create a new message in your email application with "To: sam@what.com", "Cc: joe@when.net", "Subject: The subject of the email" and "The body of the email" already entered.</p>
<p>Tip. Have a pdf file with the agenda for a meeting? Stick an <span class="citation">@g</span> entry with the path to the file in the event you create for the meeting. Then whenever the meeting is selected, <em>G</em> will bring up the agenda.</p>
<h2 id="h-history"><a href="#h-history"><span class="citation">@h</span> history</a></h2>
<p>Used internally with task groups to track completion done;due pairs.</p>
<h2 id="i-invitees"><a href="#i-invitees"><span class="citation">@i</span> invitees</a></h2>
<p>An email address or a list of email addresses for people participating in the item. These email addresses will be appended to the list of recipients for email alerts.</p>
<h2 id="j-job"><a href="#j-job"><span class="citation">@j</span> job</a></h2>
<p>Component tasks or jobs within a task group are given by <code>@j job</code> entries. <code>@key value</code> entries prior to the first <code>@j</code> become the defaults for the jobs that follow. <code>&key value</code> entries given in jobs use <code>&</code> rather than <code>@</code> and apply only to the specific job.</p>
<p>Many key-value pairs can be given either in the group task using <code>@</code> or in the component jobs using <code>&</code>:</p>
<pre><code>@c or &c context
@d or &d description
@e or &e extent
@f or &f done[; due] datetime
@k or &k keyword
@l or &l location
@u or &u user</code></pre>
<p>The key-value pair <code>&h</code> is used internally to track job done;due completions in task groups.</p>
<p>The key-value pair <code>&q</code> (queue position) can <em>only</em> be given in component jobs where it is required. Key-values other than <code>&q</code> and those listed above, can <em>only</em> be given in the initial group task entry and their values are inherited by the component jobs.</p>
<h2 id="k-keyword"><a href="#k-keyword"><span class="citation">@k</span> keyword</a></h2>
<p>A heirarchical classifier for the item. Intended for actions to support time billing where a common format would be <code>client:job:category</code>. <em>etm</em> treats such a keyword as a heirarchy so that an action report grouped by month and then keyword might appear as follows</p>
<pre><code> 27.5h) Client 1 (3)
4.9h) Project A (1)
15h) Project B (1)
7.6h) Project C (1)
24.2h) Client 2 (3)
3.1h) Project D (1)
21.1h) Project E (2)
5.1h) Category a (1)
16h) Category b (1)
4.2h) Client 3 (1)
8.7h) Client 4 (2)
2.1h) Project F (1)
6.6h) Project G (1)</code></pre>
<p>An arbitrary number of heirarchical levels in keywords is supported.</p>
<h2 id="l-location"><a href="#l-location"><span class="citation">@l</span> location</a></h2>
<p>The location at which, for example, an event will take place.</p>
<h2 id="m-memo"><a href="#m-memo"><span class="citation">@m</span> memo</a></h2>
<p>Further information about the item not included in the summary or the description. Since the summary is used as the subject of an email alert and the description is commonly included in the body of an email alert, this field could be used for information not to be included in the email.</p>
<h2 id="n-noshow"><a href="#n-noshow"><span class="citation">@n</span> noshow</a></h2>
<p>Only tasks of type "-" or "%". A value or list of values from <em>d</em>, <em>k</em>, and <em>t</em>, that specify views in which the task should <em>not</em> be shown.</p>
<p>This can provide a "poor man's cron" in which a repeating task with a process alert could be used to run a process at specified times without cluttering the etm views unnecessarily. It could also be used to trigger a periodic reminder during the day to, e.g., take a prescription medication, without filling your day lists.</p>
<p>Tip. Want to be reminded when a meeting should end without seeing an extra reminder for the meeting in your day lists? Create a task with a sound alert at the ending time and then add "<span class="citation">@n</span> d" to hide it from your day lists and, optionally, "<span class="citation">@o</span> s" to automatically remove past due instances.</p>
<h4 id="d-day"><a href="#d-day">d) day</a></h4>
<p>Do not display the task in the day views: agenda, week and month.</p>
<p>Since an undated task would not appear in week or month view, using "d" for such a task only prevents it from being displayed in the "next" section of agenda view. Using "d" for a dated task, on the other hand, prevents it from being displayed in the day lists of agenda, week and month views as well as the "now" section of agenda view.</p>
<h4 id="k-keyword-1"><a href="#k-keyword-1">k) keyword</a></h4>
<p>Do not display the task in keyword view.</p>
<h4 id="t-tag"><a href="#t-tag">t) tag</a></h4>
<p>Do not display the task in tag view.</p>
<p>E.g., with the entry "<span class="citation">@n</span> d, k, t", a task would appear only in path view.</p>
<h2 id="o-overdue"><a href="#o-overdue"><span class="citation">@o</span> overdue</a></h2>
<p>Repeating tasks only. One of the following choices: k) keep, r) restart, or s) skip. Details below.</p>
<h2 id="p-priority"><a href="#p-priority"><span class="citation">@p</span> priority</a></h2>
<p>Either 0 (no priority) or an integer between 1 (highest priority) and 9 (lowest priority). Primarily used with undated tasks.</p>
<h2 id="q-datetime"><a href="#q-datetime"><span class="citation">@q</span> datetime</a></h2>
<p>Used to provide a timestamp for an item. Intended primarily to provide a first-in-first-out queue for related, undated tasks. E.g., the following</p>
<pre><code>- first in queue @c queue @q 2015-10-06 10a @z US/Eastern
- second in queue @c queue @q 2015-10-07 12p @z US/Eastern
- third in queue @c queue @q 2015-10-08 9a @z US/Eastern
- fourth in queue @c queue @q 2015-10-09 8a @z US/Eastern</code></pre>
<p>would appear in Agenda view at 11:35am on 2015-10-09 grouped by the context "queue" and ordered by age with the oldest first:</p>
<pre><code>Next
...
queue
- first in queue 3d2h
- second in queue 1d23h35m
- third in queue 1d2h35m
- fourth in queue 3h35m </code></pre>
<h2 id="r-repetition-rule"><a href="#r-repetition-rule"><span class="citation">@r</span> repetition rule</a></h2>
<p>The specification of how an item is to repeat. Repeating items <strong>must</strong> have an <code>@s</code> entry as well as one or more <code>@r</code> entries. Generated datetimes are those satisfying any of the <code>@r</code> entries and falling <strong>on or after</strong> the datetime given in <code>@s</code>. Note that the datetime given in <code>@s</code> will only be included if it matches one of the datetimes generated by the <code>@r</code> entry.</p>
<p>A repetition rule begins with</p>
<pre><code>@r frequency</code></pre>
<p>where <code>frequency</code> is one of the following characters:</p>
<pre><code>y yearly
m monthly
w weekly
d daily
h hourly
n minutely
l list (a list of datetimes will be provided using @+)</code></pre>
<p>The <code>@r frequency</code> entry can, optionally, be followed by one or more <code>&key value</code> pairs:</p>
<pre><code>&i: interval (positive integer, default = 1) E.g, with frequency w, interval
3 would repeat every three weeks.
&t: total (positive integer) Include no more than this number of repetitions.
&s: bysetpos (integer). When multiple dates satisfy the rule, take the date
from this position in the list, e.g, &s 1 would choose the first element
and &s -1 the last. See the payday example below for an illustration of
bysetpos.
&u: until (datetime) Only include repetitions with starting times falling
on before this datetime.
&M: bymonth (1, 2, ..., 12)
&m: bymonthday (1, 2, ..., 31) Use, e.g., -1 for the last day of the month.
&W: byweekno (1, 2, ..., 53)
&w: byweekday (*English* weekday abbreviation SU ... SA). Use, e.g., 3WE
for the 3rd Wednesday or -1FR, for the last Friday in the month.
&h: byhour (0 ... 23)
&n: byminute (0 ... 59)
&E: byeaster (integer number of days before, < 0, or after, > 0, Easter)</code></pre>
<p>Repetition examples:</p>
<ul>
<li><p>1st and 3rd Wednesdays of each month.</p>
<pre><code>^ 1st and 3rd Wednesdays
@r m &w 1WE, 3WE</code></pre></li>
<li><p>Payday (an occasion) on the last week day of each month. (The <code>&s -1</code> entry extracts the last date which is both a weekday and falls within the last three days of the month.)</p>
<pre><code>^ payday @s 2010-07-01
@r m &w MO, TU, WE, TH, FR &m -1, -2, -3 &s -1</code></pre></li>
<li><p>Take a prescribed medication daily (an event) from the 23rd through the 27th of the current month at 10am, 2pm, 6pm and 10pm and trigger an alert zero minutes before each event.</p>
<pre><code>* take Rx @d 10a 23 @r d &u 11p 27 &h 10, 14 18, 22 @a 0</code></pre></li>
<li><p>Vote for president (an occasion) every four years on the first Tuesday after a Monday in November. (The <code>&m range(2,9)</code> requires the month day to fall within 2 ... 8 and thus, combined with <code>&w TU</code> to be the first Tuesday following a Monday.)</p>
<pre><code>^ Vote for president @s 2012-11-06
@r y &i 4 &M 11 &m range(2,9) &w TU</code></pre></li>
<li><p>Ash Wednesday (an occasion) that occurs 46 days before Easter each year.</p>
<p>^ Ash Wednesday 2010-01-01 <span class="citation">@r</span> y &E -46</p></li>
<li><p>Easter Sunday (an occasion).</p>
<p>^ Easter Sunday 2010-01-01 <span class="citation">@r</span> y &E 0</p></li>
</ul>
<p>A repeating <em>task</em> may optionally also include an <code>@o <k|s|r></code> entry (default = k):</p>
<ul>
<li><p><code>@o k</code>: Keep the current due date if it becomes overdue and use the next due date from the recurrence rule if it is finished early. This would be appropriate, for example, for the task 'file tax return'. The return due April 15, 2009 must still be filed even if it is overdue and the 2010 return won't be due until April 15, 2010 even if the 2009 return is finished early.</p></li>
<li><p><code>@o s</code>: Skip overdue due dates and set the due date for the next repetition to the first due date from the recurrence rule on or after the current date. This would be appropriate, for example, for the task 'put out the trash' since there is no point in putting it out on Tuesday if it's picked up on Mondays. You might just as well wait until the next Monday to put it out. There's also no point in being reminded until the next Monday.</p></li>
<li><p><code>@o r</code>: Restart the repetitions based on the last completion date. Suppose you want to mow the grass once every ten days and that when you mowed yesterday, you were already nine days past due. Then you want the next due date to be ten days from yesterday and not today. Similarly, if you were one day early when you mowed yesterday, then you would want the next due date to be ten days from yesterday and not ten days from today.</p></li>
</ul>
<h2 id="s-starting-datetime"><a href="#s-starting-datetime"><span class="citation">@s</span> starting datetime</a></h2>
<p>When an action is started, an event begins or a task is due.</p>
<h2 id="t-tags"><a href="#t-tags"><span class="citation">@t</span> tags</a></h2>
<p>A tag or list of tags for the item.</p>
<h2 id="u-user"><a href="#u-user"><span class="citation">@u</span> user</a></h2>
<p>Intended to specify the person to whom a delegated task is assigned. Could also be used in actions to indicate the person performing the action.</p>
<h2 id="v-action_rates-key"><a href="#v-action_rates-key"><span class="citation">@v</span> action_rates key</a></h2>
<p>Actions only. A key from <code>action_rates</code> in your <code>etmtk.cfg</code> to apply to the value of <code>@e</code>. Used in actions to apply a billing rate to time spent in an action. E.g., with</p>
<pre><code> minutes: 6
action_rates:
br1: 45.0
br2: 60.0</code></pre>
<p>then entries of <code>@v br1</code> and <code>@e 2h25m</code> in an action would entail a value of <code>45.0 * 2.5 = 112.50</code>.</p>
<h2 id="w-action_markups-key"><a href="#w-action_markups-key"><span class="citation">@w</span> action_markups key</a></h2>
<p>A key from <code>action_markups</code> in your <code>etmtk.cfg</code> to apply to the value of <code>@x</code>. Used in actions to apply a markup rate to expense in an action. E.g., with</p>
<pre><code> weights:
mr1: 1.5
mr2: 10.0</code></pre>
<p>then entries of <code>@w mr1</code> and <code>@x 27.50</code> in an action would entail a value of <code>27.50 * 1.5 = 41.25</code>.</p>
<h2 id="x-expense"><a href="#x-expense"><span class="citation">@x</span> expense</a></h2>
<p>Actions only. A currency amount such as <code>27.50</code>. Used in conjunction with <span class="citation">@w</span> above to bill for action expenditures.</p>
<h2 id="z-time-zone"><a href="#z-time-zone"><span class="citation">@z</span> time zone</a></h2>
<p>The time zone of the item, e.g., US/Eastern. The starting and other datetimes in the item will be interpreted as belonging to this time zone.</p>
<p>Tip. You live in the US/Eastern time zone but a flight that departs Sydney on April 20 at 9pm bound for New York with a flight duration of 14 hours and 30 minutes. The hard way is to convert this to US/Eastern time and enter the flight using that time zone. The easy way is to use Australia/Sydney and skip the conversion:</p>
<pre><code>* Sydney to New York @s 2014-04-23 9pm @e 14h30m @z Australia/Sydney</code></pre>
<p>This flight will be displayed while you're in the Australia/Sydney time zone as extending from 9pm on April 23 until 11:30am on April 24, but in the US/Eastern time zone it will be displayed as extending from 7am until 9:30pm on April 23.</p>
<h2 id="include"><a href="#include">@+ include</a></h2>
<p>A datetime, e.g., <code>@+ 20150420T0930</code>, or list of datetimes to be added to the repetitions generated by <code>@r rrule</code> entries. If only a date is provided, 12:00am is assumed.</p>
<h2 id="exclude"><a href="#exclude">@- exclude</a></h2>
<p>A datetime or list of datetimes to be removed from the repetitions generated by <code>@r rrule</code> entries. If only a date is provided, 12:00am is assumed.</p>
<p>Note that to exclude a datetime from the recurrence rule, the @- datetime <em>must exactly match both the date and time</em> generated by one of the <code>@r rrule</code> entries.</p>
<p>Example of using <code>@-</code> and <code>@+</code>:</p>
<pre><code>@s 2014-02-19 4pm
@r m &w 3WE
@+ 20140924T1600, 20141029T1600
@- 20140917T1600, 20141015T1600</code></pre>
<h1 id="dates"><a href="#dates">Dates</a></h1>
<h2 id="fuzzy-dates"><a href="#fuzzy-dates">Fuzzy dates</a></h2>
<p>When either a <em>datetime</em> or an <em>time period</em> is to be entered, special formats are used in <em>etm</em>. Examples include entering a starting datetime for an item using <code>@s</code> and jumping to a date using Ctrl-J.</p>
<p>Suppose, for example, that it is currently 8:30am on Friday, February 15, 2013. Then, <em>fuzzy dates</em> would expand into the values illustrated below.</p>
<pre><code> mon 2p or mon 14h 2:00pm Monday, February 19
fri 12:00am Friday, February 15
9a -1/1 or 9h -1/1 9:00am Tuesday, January 1
+2/15 12:00am Monday, April 15 2013
8p +7 or 20h +7 8:00pm Friday, February 22
-14 8:30am Friday, February 1
now 8:30am Friday, February 15</code></pre>
<p>Note that expressions using <code>+</code> or <code>-</code> give datetimes relative to the current datetime.</p>
<p>12am is the default time when a time is not explicity entered. E.g., <code>+2/15</code> in the examples above gives 12:00am on April 15.</p>
<p>To avoid ambiguity, always append either 'a', 'p' or 'h' when entering an hourly time, e.g., use <code>1p</code> or <code>13h</code>.</p>
<h2 id="time-periods"><a href="#time-periods">Time periods</a></h2>
<p>Time periods are entered using the format <code>WwDdHhMm</code> where W, D, H and M are integers and w, d, h and m refer to weeks, days, hours and minutes respectively. For example:</p>
<pre><code> 2h30m 2 hours, 30 minutes
2w3d 2 weeks, 3 days
45m 45 minutes</code></pre>
<p>As an example, if it is currently 8:50am on Friday February 15, 2013, then entering <code>now + 2d4h30m</code> into the date calculator would give <code>2013-02-17 1:20pm</code>.</p>
<p>Tip. Need to schedule a reminder in 15 minutes? Use <code>@s +15m</code>.</p>
<h2 id="time-zones"><a href="#time-zones">Time zones</a></h2>
<p>Dates and times are always stored in <em>etm</em> data files as times in the time zone given by the entry for <code>@z</code>. On the other hand, dates and times are always displayed in <em>etm</em> using the local time zone of the system.</p>
<p>For example, if it is currently 8:50am EST on Friday February 15, 2013, and an item is saved on a system in the <code>US/Eastern</code> time zone containing the entry</p>
<pre><code>@s now @z Australia/Sydney</code></pre>
<p>then the data file would contain</p>
<pre><code>@s 2013-02-16 12:50am @z Australia/Sydney</code></pre>
<p>but this item would be displayed as starting at <code>8:50am 2013-02-15</code> on the system in the <code>US/Eastern</code> time zone.</p>
<p>Tip. Need to determine the flight time when the departing timezone is different that the arriving timezone? The date calculator (shortcut Shift-D) will accept timezone information so that, e.g., entering the arrival time minus the departure time</p>
<pre><code>4/20 6:15p US/Central - 4/20 4:50p Asia/Shanghai</code></pre>
<p>into the calculator would give</p>
<pre><code>14h25m</code></pre>
<p>as the flight time.</p>
<h2 id="anniversary-substitutions"><a href="#anniversary-substitutions">Anniversary substitutions</a></h2>
<p>An anniversary substitution is an expression of the form <code>!YYYY!</code> that appears in an item summary. Consider, for example, the occassion</p>
<pre><code>^ !2010! anniversary @s 2011-02-20 @r y</code></pre>
<p>This would appear on Feb 20 of 2011, 2012, 2013 and 2014, respectively, as <em>1st anniversary</em>, <em>2nd anniversary</em>, <em>3rd anniversary</em> and <em>4th anniversary</em>. The suffixes, <em>st</em>, <em>nd</em> and so forth, depend upon the translation file for the locale.</p>
<h2 id="easter"><a href="#easter">Easter</a></h2>
<p>An expression of the form <code>easter(yyyy)</code> can be used as a date specification in <code>@s</code> entries and in the datetime calculator. E.g.</p>
<pre><code>@s easter(2014) 4p</code></pre>
<p>would expand to <code>2014-04-20 4pm</code>. Similarly, in the date calculator</p>
<pre><code>easter(2014) - 48d</code></pre>
<p>(Rose Monday) would return <code>2014-03-03</code>. In repeating items <code>easter(yyyy)</code> is replaced by <code>&E</code>, e.g.,</p>
<pre><code>^ Easter Sunday @s 2010-01-01 @r y &E 0
^ Ash Wednesday @s 2010-01-01 @r y &E -46
^ Rose Monday @s 2010-01-01 @r y &E -48</code></pre>
<h1 id="preferences"><a href="#preferences">Preferences</a></h1>
<p>Configuration options are stored in a file named <code>etmtk.cfg</code> which, by default, belongs to the folder <code>.etm</code> in your home directory. When this file is edited in <em>etm</em> (Shift Ctrl-P), your changes become effective as soon as they are saved --- you do not need to restart <em>etm</em>. These options are listed below with illustrative entries and brief descriptions.</p>
<h2 id="template-expansions"><a href="#template-expansions">Template expansions</a></h2>
<p>The following template expansions can be used in <code>alert_displaycmd</code>, <code>alert_template</code>, <code>alert_voicecmd</code>, <code>email_template</code>, <code>sms_message</code> and <code>sms_subject</code> below.</p>
<ul>
<li><code>!summary!</code></li>
</ul>
<p>the item's summary (this will be used as the subject of email and message alerts)</p>
<ul>
<li><code>!start_date!</code></li>
</ul>
<p>the starting date of the event</p>
<ul>
<li><code>!start_time!</code></li>
</ul>
<p>the starting time of the event</p>
<ul>
<li><code>!time_span!</code></li>
</ul>
<p>the time span of the event (see below)</p>
<ul>
<li><code>!alert_time!</code></li>
</ul>
<p>the time the alert is triggered</p>
<ul>
<li><code>!time_left!</code></li>
</ul>
<p>the time remaining until the event starts</p>
<ul>
<li><code>!when!</code></li>
</ul>
<p>the time remaining until the event starts as a sentence (see below)</p>
<ul>
<li><code>!next!</code></li>
</ul>
<p>how long before the starting time the next alert will be triggered</p>
<ul>
<li><code>!next_alert!</code></li>
</ul>
<p>how long before the starting time the next alert will be triggered as a sentence (see below)</p>
<ul>
<li><code>!d!</code></li>
</ul>
<p>the item's <code>@d</code> (description)</p>
<ul>
<li><code>!l!</code></li>
</ul>
<p>the item's <code>@l</code> (location)</p>
<p>The value of <code>!next!</code> for some illustrative cases:</p>
<ul>
<li><p>The current alert is the last</p>
<p>!next!: None</p>
<p>!next_alert!: 'This is the last alert.'</p></li>
<li><p>The next alert is at the start time</p>
<p>!next!: 'at the start time'</p>
<p>!next_alert!: 'The next alert is at the start time.'</p></li>
<li><p>The next alert is 5 minutes before the start time:</p>
<p>!next!: '5 minutes before the start time'</p>
<p>!next_alert!: 'The next alert is 5 minutes before the start time.'</p></li>
</ul>
<p>The value of <code>!time_span!</code> depends on the starting and ending datetimes. Here are some examples:</p>
<ul>
<li><p>if the start and end <em>datetimes</em> are the same (zero extent): <code>10am Wed, Aug 4</code></p></li>
<li><p>else if the times are different but the <em>dates</em> are the same: <code>10am - 2pm Wed, Aug 4</code></p></li>
<li><p>else if the dates are different: <code>10am Wed, Aug 4 - 9am Thu, Aug 5</code></p></li>
<li><p>additionally, the year is appended if a date falls outside the current year:</p>
<pre><code>10am - 2pm Thu, Jan 3 2013
10am Mon, Dec 31 - 2pm Thu, Jan 3 2013</code></pre></li>
</ul>
<p>Here are values of <code>!time_left!</code> and <code>!when!</code> for some illustrative periods:</p>
<ul>
<li><p><code>2d3h15m</code></p>
<pre><code>time_left : '2 days 3 hours 15 minutes'
when : '2 days 3 hours 15 minutes from now'</code></pre></li>
<li><p><code>20m</code></p>
<pre><code>time_left : '20 minutes'
when : '20 minutes from now'</code></pre></li>
<li><p><code>0m</code></p>
<pre><code>time_left : ''
when : 'now'</code></pre></li>
</ul>
<p>Note that 'now', 'from now', 'days', 'day', 'hours' and so forth are determined by the translation file in use.</p>
<h2 id="options"><a href="#options">Options</a></h2>
<h3 id="action_interval"><a href="#action_interval">action_interval</a></h3>
<pre><code>action_interval: 1</code></pre>
<p>Every <code>action_interval</code> minutes, execute <code>action_timercmd</code> when the timer is running and <code>action_pausecmd</code> when the timer is paused. Choose zero to disable executing these commands.</p>
<h3 id="action_keys"><a href="#action_keys">action_keys</a></h3>
<pre><code>action_keys: "k"</code></pre>
<p>When klone is used to create an action timer, copy the values of the @-keys in this string from the item to the timer. With the default, "k", klone will copy the item's <span class="citation">@k</span> entry, if there is one, in addition to the summary when creating the action. Replacing "k", with "c" would cause klone to copy the item's <span class="citation">@c</span> entry in addition to the summary. With "ck", both the <span class="citation">@c</span> and <span class="citation">@k</span> entries would be copied. Any key that is valid for an action can be used.</p>
<p>E.g., when</p>
<pre><code>- my task @c my context @k my keyword @t my tag</code></pre>
<p>is selected, then the default would create a timer with the name <code>my task @k my keyword</code>.</p>
<h3 id="action_markups"><a href="#action_markups">action_markups</a></h3>
<pre><code>action_markups:
default: 1.0
mu1: 1.5
mu2: 2.0</code></pre>
<p>Possible markup rates to use for <code>@x</code> expenses in actions. An arbitrary number of rates can be entered using whatever labels you like. These labels can then be used in actions in the <code>@w</code> field so that, e.g.,</p>
<pre><code>... @x 25.80 @w mu1 ...</code></pre>
<p>in an action would give this expansion in an action template:</p>
<pre><code>!expense! = 25.80
!charge! = 38.70</code></pre>
<h3 id="action_minutes"><a href="#action_minutes">action_minutes</a></h3>
<pre><code>action_minutes: 6</code></pre>
<p>Round action times up to the nearest <code>action_minutes</code> in action custom view. Possible choices are 1, 6, 12, 15, 30 and 60. With 1, no rounding is done and times are reported as integer minutes. Otherwise, the prescribed rounding is done and times are reported as floating point hours.</p>
<h3 id="action_rates"><a href="#action_rates">action_rates</a></h3>
<pre><code>action_rates:
default: 30.0
br1: 45.0
br2: 60.0</code></pre>
<p>Possible billing rates to use for <code>@e</code> times in actions. An arbitrary number of rates can be entered using whatever labels you like. These labels can then be used in the <code>@v</code> field in actions so that, e.g., with <code>action_minutes: 6</code> then:</p>
<pre><code>... @e 75m @v br1 ...</code></pre>
<p>in an action would give these expansions in an action template:</p>
<pre><code>!hours! = 1.3
!value! = 58.50</code></pre>
<p>If the label <code>default</code> is used, the corresponding rate will be used when <code>@v</code> is not specified in an action.</p>
<p>Note that etm accumulates group totals from the <code>time</code> and <code>value</code> of individual actions. Thus</p>
<pre><code>... @e 75m @v br1 ...
... @e 60m @v br2 ...</code></pre>
<p>would aggregate to</p>
<pre><code>!hours! = 2.3 (= 1.3 + 1)
!value! = 118.50 (= 1.3 * 45.0 + 1 * 60.0)</code></pre>
<h3 id="action_template"><a href="#action_template">action_template</a></h3>
<pre><code>action_template: '!hours!h) !label! (!count!)'</code></pre>
<p>Used for action type custom view. With the above settings for <code>action_minutes</code> and <code>action_template</code>, a custom view might appear as follows:</p>
<pre><code>27.5h) Client 1 (3)
4.9h) Project A (1)
15h) Project B (1)
7.6h) Project C (1)
24.2h) Client 2 (3)
3.1h) Project D (1)
21.1h) Project E (2)
5.1h) Category a (1)
16h) Category b (1)
4.2h) Client 3 (1)
8.7h) Client 4 (2)
2.1h) Project F (1)
6.6h) Project G (1)</code></pre>
<p>Available template expansions for <code>action_template</code> include:</p>
<ul>
<li><p><code>!label!</code>: the item or group label.</p></li>
<li><p><code>!count!</code>: the number of children represented in the reported item or group.</p></li>
<li><p><code>!minutes!:</code> the total time from <code>@e</code> entries in minutes rounded up using the setting for <code>action_minutes</code>.</p></li>
<li><p><code>!hours!</code>: if action_minutes = 1, the time in hours and minutes. Otherwise, the time in floating point hours.</p></li>
<li><p><code>!value!</code>: the billing value of the rounded total time. Requires an action entry such as <code>@v br1</code> and a setting for <code>action_rates</code>.</p></li>
<li><p><code>!expense!</code>: the total expense from <code>@x</code> entries.</p></li>
<li><p><code>!charge!</code>: the billing value of the total expense. Requires an action entry such as <code>@w mu1</code> and a setting for <code>action_markups</code>.</p></li>
<li><p><code>!total!</code>: the sum of <code>!value!</code> and <code>!charge!</code>.</p></li>
</ul>
<p>Note: when aggregating amounts in action type custom view, billing and markup rates are applied first to times and expenses for individual actions and the resulting amounts are then aggregated. Similarly, when times are rounded up, the rounding is done for individual actions and the results are then aggregated.</p>
<h3 id="action_timer"><a href="#action_timer">action_timer</a></h3>
<pre><code>action_timer:
paused: 'play ~/.etm/sounds/timer_paused.wav'
running: 'play ~/.etm/sounds/timer_running.wav'</code></pre>
<p>The command <code>running</code> is executed every <code>action_interval</code> minutes whenever the action timer is running and <code>paused</code> every minute when the action timer is paused.</p>
<h3 id="agenda"><a href="#agenda">agenda</a></h3>
<pre><code>agenda_days: 2
agenda_colors: 2
agenda_indent: 2
agenda_omit: [ac, fn, ns]
agenda_width1: 43
agenda_width2: 17</code></pre>
<p>Sets the number of days to display in agenda view and other parameters affecting the display in the CLI. The colors setting only affects output to current_html. Items in agenda_omit will not be displayed in the agenda day list. Possible choices include:</p>
<ul>
<li><p>ac: actions</p></li>
<li><p>by: begin by warnings</p></li>
<li><p>fn: finished tasks</p></li>
<li><p>ns: notes (dated)</p></li>
<li><p>oc: occasions</p></li>
</ul>
<h3 id="alert_default"><a href="#alert_default">alert_default</a></h3>
<pre><code>alert_default: [m]</code></pre>
<p>The alert or list of alerts to be used when an alert is specified for an item but the type is not given. Possible values for the list include:</p>
<ul>
<li><p>d: display (requires <code>alert_displaycmd</code>)</p></li>
<li><p>m: message (using <code>alert_template</code>)</p></li>
<li><p>s: sound (requires <code>alert_soundcmd</code>)</p></li>
<li><p>v: voice (requires <code>alert_voicecmd</code>)</p></li>
</ul>
<h3 id="alert_displaycmd"><a href="#alert_displaycmd">alert_displaycmd</a></h3>
<pre><code>alert_displaycmd: growlnotify -t !summary! -m '!time_span!'</code></pre>
<p>The command to be executed when <code>d</code> is included in an alert. Possible template expansions are discussed at the beginning of this tab.</p>
<h3 id="alert_soundcmd"><a href="#alert_soundcmd">alert_soundcmd</a></h3>
<pre><code>alert_soundcmd: 'play ~/.etm/sounds/etm_alert.wav'</code></pre>
<p>The command to execute when <code>s</code> is included in an alert. Possible template expansions are discussed at the beginning of this tab.</p>
<h3 id="alert_template"><a href="#alert_template">alert_template</a></h3>
<pre><code>alert_template: '!time_span!\n!l!\n\n!d!'</code></pre>
<p>The template to use for the body of <code>m</code> (message) alerts. See the discussion of template expansions at the beginning of this tab for other possible expansion items.</p>
<h3 id="alert_voicecmd"><a href="#alert_voicecmd">alert_voicecmd</a></h3>
<pre><code>alert_voicecmd: say -v 'Alex' '!summary! begins !when!.'</code></pre>
<p>The command to be executed when <code>v</code> is included in an alert. Possible expansions are are discussed at the beginning of this tab.</p>
<h3 id="alert_wakecmd"><a href="#alert_wakecmd">alert_wakecmd</a></h3>
<pre><code>alert_wakecmd: ~/bin/SleepDisplay -w</code></pre>
<p>If given, this command will be issued to "wake up the display" before executing <code>alert_displaycmd</code>.</p>
<h3 id="ampm"><a href="#ampm">ampm</a></h3>
<pre><code>ampm: true</code></pre>
<p>Use ampm times if true and twenty-four hour times if false. E.g., 2:30pm (true) or 14:30 (false).</p>
<h3 id="completions_width"><a href="#completions_width">completions_width</a></h3>
<pre><code>completions_width: 36</code></pre>
<p>The width in characters of the auto completions popup window.</p>
<h3 id="calendars-1"><a href="#calendars-1">calendars</a></h3>
<pre><code>calendars:
- [dag, true, personal/dag]
- [erp, false, personal/erp]
- [shared, true, shared]</code></pre>
<p>These are (label, default, path relative to <code>datadir</code>) tuples to be interpreted as separate calendars. Those for which default is <code>true</code> will be displayed as default calendars. E.g., with the <code>datadir</code> below, <code>dag</code> would be a default calendar and would correspond to the absolute path <code>/Users/dag/.etm/data/personal/dag</code>. With this setting, the calendar selection dialog would appear as follows:</p>
<p>When non-default calendars are selected, busy times in the "week view" will appear in one color for events from default calendars and in another color for events from non-default calendars.</p>
<p><strong>Only data files that belong to one of the calendar directories or their subdirectories will be accessible within etm.</strong></p>
<h3 id="cfg_files"><a href="#cfg_files">cfg_files</a></h3>
<pre><code>cfg_files:
- completions: []
- reports: []
- users: []</code></pre>
<p>Each of the three list brackets can contain one or more comma separated <em>absolute</em> file paths. Additionally, paths corresponding to active calendars in the <code>datadir</code> directory are searched for files named <code>completions.cfg</code>, <code>reports.cfg</code> and <code>users.cfg</code> and these are processed in addition to the ones from <code>cfg_files</code>.</p>
<p>Note. Windows users should place each absolute path in quotes and escape backslashes, i.e., use <code>\\</code> anywhere <code>\</code> appears in a path.</p>
<ul>
<li><p>Completions</p>
<p>Each line in a completions file provides a possible completion when using the editor. E.g. with these completions</p>
<pre><code>@c computer
@c home
@c errands
@c office
@c phone
@z US/Eastern
@z US/Central
@z US/Mountain
@z US/Pacific
dnlgrhm@gmail.com</code></pre>
<p>entering, for example, "<span class="citation">@c</span>" in the editor and pressing Ctrl-Space, would popup a list of possible completions. Choosing the one you want and pressing <em>Return</em> would insert it and close the popup.</p>
<p>Up and down arrow keys change the selection and either <em>Tab</em> or <em>Return</em> inserts the selection.</p></li>
<li><p>Reports</p>
<p>Each line in a reports file provides a possible reports specification. These are available when using the CLI <code>m</code> command and in the GUI custom view. See <a href="#custom-view">Custom view</a> for details.</p></li>
<li><p>Users</p>
<p>User files contain user (contact) information in a free form, text database. Each entry begins with a unique key for the person and is followed by detail lines each of which begins with a minus sign and contains some detail about the person that you want to record. Any detail line containing a colon should be quoted, e.g.,</p>
<pre><code>jbrown:
- Brown, Joe
- jbr@whatever.com
- 'home: 123 456-7890'
- 'birthday: 1978-12-14'
dcharles:
- Charles, Debbie
- dch@sometime.com
- 'cell: 456 789-0123'
- 'spouse: Rebecca'</code></pre>
<p>Keys from this file are added to auto-completions so that if you type, say, <code>@u jb</code> and press <em>Ctrl-Space</em>, then <code>@u jbrown</code> would be offered for completion.</p>
<p>If an item with the entry <code>@u jbrown</code> is selected in the GUI, you can press "u" to see a popup with the details:</p>
<pre><code>Brown, Joe
jbr@whatever.com
home: 123 456-7890
birthday: 1978-12-14</code></pre></li>
</ul>
<h3 id="countdown-timer-1"><a href="#countdown-timer-1">countdown timer</a></h3>
<pre><code>countdown_command: ''
countdown_minutes: 10</code></pre>
<p>If <code>countdown_command</code> is given, it will be executed when the timer expires; otherwise a beep will be sounded. The default number of minutes for a countdown is given by <code>countdown_minutes</code>. When a timer is active, the time that the timer will expire is displayed in the status bar using the format -H:M:S(am/pm). When a countdown and a snooze timer are both active, the one that will expire first is displayed in the status bar.</p>
<h3 id="current-files"><a href="#current-files">current files</a></h3>
<pre><code>current_htmlfile: ''
current_textfile: ''
current_icsfolder: ''
current_indent: 3
current_opts: ''
current_width1: 40
current_width2: 17</code></pre>
<p>If absolute file paths are entered for <code>current_textfile</code> and/or <code>current_htmlfile</code>, then these files will be created and automatically updated by etm as as plain text or html files, respectively. If <code>current_opts</code> is given then the file will contain a report using these options; otherwise the file will contain an agenda. Indent and widths are taken from these setting with other settings, including color, from <em>report</em> or <em>agenda</em>, respectively.</p>
<p>If an absolute path is entered for <code>current_icsfolder</code>, then ics files corresponding to the entries in <code>calendars</code> will be created in this folder and updated as necessary. If there are no entries in calendars, then a single file, <code>all.ics</code>, will be created in this folder and updated as necessary.</p>
<p>Hint: fans of geektool can use the shell command <code>cat <current_textfile></code> to have the current agenda displayed on their desktops.</p>
<h3 id="datadir"><a href="#datadir">datadir</a></h3>
<pre><code>datadir: ~/.etm/data</code></pre>
<p>All etm data files are in this directory.</p>
<h3 id="dayfirst"><a href="#dayfirst">dayfirst</a></h3>
<pre><code>dayfirst: false</code></pre>
<p>If dayfirst is False, the MM-DD-YYYY format will have precedence over DD-MM-YYYY in an ambiguous date. See also <code>yearfirst</code>.</p>
<h3 id="details_rows"><a href="#details_rows">details_rows</a></h3>
<pre><code>details_rows: 4</code></pre>
<p>The number of rows to display in the bottom, details panel of the main window.</p>
<h3 id="display_idletime"><a href="#display_idletime">display_idletime</a></h3>
<pre><code>display_idletime: True</code></pre>
<p>Show idle time in the status bar by default if True. Display can be toggled on and off in the File/Timer menu. Idle time is accumulated when there are are one or more active timers and none are running.</p>
<h3 id="early_hour"><a href="#early_hour">early_hour</a></h3>
<pre><code>early_hour: 6</code></pre>
<p>When scheduling an event or action with a starting time that begins before this hour, append the query "Is __ the starting time you intended?" to the confirmation. Use 0 to disable this warning altogether. The default, 6, will warn for starting times <em>before</em> 6am.</p>
<h3 id="edit_cmd"><a href="#edit_cmd">edit_cmd</a></h3>
<pre><code>edit_cmd: ~/bin/vim !file! +!line!</code></pre>
<p>This command is used in the command line version of etm to create and edit items. When the command is expanded, <code>!file!</code> will be replaced with the complete path of the file to be edited and <code>!line!</code> with the starting line number in the file. If the editor will open a new window, be sure to include the command to wait for the file to be closed before returning, e.g., with vim:</p>
<pre><code>edit_cmd: ~/bin/gvim -f !file! +!line!</code></pre>
<p>or with sublime text:</p>
<pre><code>edit_cmd: ~/bin/subl -n -w !file!:!line!</code></pre>
<h3 id="email_template"><a href="#email_template">email_template</a></h3>
<pre><code>email_template: 'Time: !time_span!
Locaton: !l!
!d!'</code></pre>
<p>Note that two newlines are required to get one empty line when the template is expanded. This template might expand as follows:</p>
<pre><code> Time: 1pm - 2:30pm Wed, Aug 4
Location: Conference Room
<contents of @d></code></pre>
<p>See the discussion of template expansions at the beginning of this tab for other possible expansion items.</p>
<h3 id="etmdir"><a href="#etmdir">etmdir</a></h3>
<pre><code>etmdir: ~/.etm</code></pre>
<p>Absolute path to the directory for etmtk.cfg and other etm configuration files.</p>
<h3 id="exportdir"><a href="#exportdir">exportdir</a></h3>
<pre><code>exportdir: ~/.etm</code></pre>
<p>Absolute path to the directory for exported CSV files.</p>
<h3 id="encoding"><a href="#encoding">encoding</a></h3>
<pre><code>encoding: {file: utf-8, gui: utf-8, term: utf-8}</code></pre>
<p>The encodings to be used for file IO, the GUI and terminal IO.</p>
<h3 id="filechange_alert"><a href="#filechange_alert">filechange_alert</a></h3>
<pre><code>filechange_alert: 'play ~/.etm/sounds/etm_alert.wav'</code></pre>
<p>The command to be executed when etm detects an external change in any of its data files. Leave this command empty to disable the notification.</p>
<h3 id="fontsize_fixed"><a href="#fontsize_fixed">fontsize_fixed</a></h3>
<pre><code>fontsize_fixed: 0</code></pre>
<p>Use this font size in the details panel, editor and reports. Use 0 to keep the system default.</p>
<h3 id="fontsize_tree"><a href="#fontsize_tree">fontsize_tree</a></h3>
<pre><code>fontsize_tree: 0</code></pre>
<p>Use this font size in the gui treeviews. Use 0 to keep the system default.</p>
<p>Tip: Leave the font sizes set to 0 and run etm with logging level 2 to see the system default sizes.</p>
<h3 id="freetimes"><a href="#freetimes">freetimes</a></h3>
<pre><code>freetimes:
opening: 480 # 8*60 minutes after midnight = 8am
closing: 1020 # 17*60 minutes after midnight = 5pm
minimum: 30 # 30 minutes
buffer: 15 # 15 minutes</code></pre>
<p>Only display free periods between <em>opening</em> and <em>closing</em> that last at least <em>minimum</em> minutes and preserve at least <em>buffer</em> minutes between events. Note that each of these settings must be an <em>interger</em> number of minutes.</p>
<p>E.g., with the above settings and these busy periods:</p>
<pre><code>Busy periods in Week 16: Apr 14 - 20, 2014
------------------------------------------
Mon 14: 10:30am-11:00am; 12:00pm-1:00pm; 5:00pm-6:00pm
Tue 15: 9:00am-10:00am
Wed 16: 8:30am-9:30am; 2:00pm-3:00pm; 5:00pm-6:00pm
Thu 17: 11:00am-12:00pm; 6:00pm-7:00pm; 7:00pm-9:00pm
Fri 18: 3:00pm-4:00pm; 5:00pm-6:00pm
Sat 19: 9:00am-10:30am; 7:30pm-10:00pm</code></pre>
<p>This would be the corresponding list of free periods:</p>
<pre><code>Free periods in Week 16: Apr 14 - 20, 2014
------------------------------------------
Mon 14: 8:00am-10:15am; 11:15am-11:45am; 1:15pm-4:45pm
Tue 15: 8:00am-8:45am; 10:15am-5:00pm
Wed 16: 9:45am-1:45pm; 3:15pm-4:45pm
Thu 17: 8:00am-10:45am; 12:15pm-5:00pm
Fri 18: 8:00am-2:45pm; 4:15pm-4:45pm
Sat 19: 8:00am-8:45am; 10:45am-5:00pm
Sun 20: 8:00am-5:00pm
----------------------------------------
Only periods of at least 30 minutes are displayed.</code></pre>
<p>When displaying free times in week view you will be prompted for the shortest period to display using the setting for <em>minimum</em> as the default.</p>
<p>Tip: Need to tell someone when you're free in a given week? Jump to that week in week view, press <em>Ctrl-F</em>, set the minimum period and then copy and paste the resulting list into an email.</p>
<h3 id="icalendar-settings"><a href="#icalendar-settings">iCalendar settings</a></h3>
<h4 id="icscal_file"><a href="#icscal_file">icscal_file</a></h4>
<p>If an item is not selected, pressing Shift-X in the gui will export the active calendars in iCalendar format to this file.</p>
<pre><code>icscal_file: ~/.etm/etmcal.ics</code></pre>
<h4 id="icsitem_file"><a href="#icsitem_file">icsitem_file</a></h4>
<p>If an item is selected, pressing Shift-X in the gui will export the selected item in iCalendar format to this file.</p>
<pre><code>icsitem_file: ~/.etm/etmitem.ics</code></pre>
<h4 id="icssync_folder"><a href="#icssync_folder">icssync_folder</a></h4>
<pre><code>icssync_folder: ''</code></pre>
<p>A relative path from <code>etmdata</code> to a folder. If given, files in this folder with the extension <code>.txt</code> and <code>.ics</code> will automatically kept concurrent using export to iCalendar and import from iCalendar. I.e., if the <code>.txt</code> file is more recent than than the <code>.ics</code> then the <code>.txt</code> file will be exported to the <code>.ics</code> file. On the other hand, if the <code>.ics</code> file is more recent then it will be imported to the <code>.txt</code> file. In either case, the contents of the file to be updated will be overwritten with the new content and the last acess/modified times for both will be set to the current time.</p>
<p>Note that the calendar application you use to modify the <code>.ics</code> file will impose restrictions on the subsequent content of the <code>.txt</code> file. E.g., if the <code>.txt</code> file has a note entry, then this note will be exported by etm as a VJOURNAL entry to the <code>.ics</code> file. But VJOURNAL entries are not be recognized by many (most) calendar apps. When importing this file to such an application, the note will be omitted and thus will be missing from the <code>.ics</code> file after the next export from the application. The note will then be missing from the <code>.txt</code> file as well after the next automatic update. Restricting the content to events should be safe with with any calendar application.</p>
<p>Additionally, if an absolute path is entered for <code>current_icsfolder</code>, then ics files corresponding to the entries in <code>calendars</code> will be created in this folder and updated as necessary. If there are no entries in calendars, then a single file, <code>all.ics</code>, will be created in this folder and updated as necessary.</p>
<h4 id="ics_subscriptions"><a href="#ics_subscriptions">ics_subscriptions</a></h4>
<pre><code>ics_subscriptions: []</code></pre>
<p>A list of (URL, path) tuples for automatic updates. The URL is a calendar subscription, e.g., for a Google Calendar subscription the entry might be something like:</p>
<pre><code>ics_subscriptions:
- ['https://www.google.com/calendar/ical/.../basic.ics', 'personal/dag/google.txt']
</code></pre>
<p>With this entry, pressing Shift-M in the gui would import the calendar from the URL, convert it from ics to etm format and then write the result to <code>personal/google.txt</code> in the etm data directory. Note that this data file should be regarded as read-only since any changes made to it will be lost with the next subscription update.</p>
<h3 id="local_timezone"><a href="#local_timezone">local_timezone</a></h3>
<pre><code>local_timezone: US/Eastern</code></pre>
<p>This timezone will be used as the default when a value for <code>@z</code> is not given in an item.</p>
<h3 id="message_last"><a href="#message_last">message_last</a></h3>
<pre><code>message_last: 0</code></pre>
<p>The number of seconds to display the message alert for an item before closing it when it is the last. With 0, the message dialog will be kept open indefinitely.</p>
<h3 id="message_next"><a href="#message_next">message_next</a></h3>
<pre><code>message_next: 0</code></pre>
<p>The number of seconds to display the message alert for an item before closing it when it is not the last alert. With 0, the message dialog will be kept open indefinitely.</p>
<h3 id="monthly"><a href="#monthly">monthly</a></h3>
<pre><code>monthly: monthly</code></pre>
<p>Relative path from <code>datadir</code>. With the settings above and for <code>datadir</code> the suggested location for saving new items in, say, October 2012, would be the file:</p>
<pre><code>~/.etm/data/monthly/2012/10.txt</code></pre>
<p>The directories <code>monthly</code> and <code>2012</code> and the file <code>10.txt</code> would, if necessary, be created. The user could either accept this default or choose a different file.</p>
<h3 id="outline_depth"><a href="#outline_depth">outline_depth</a></h3>
<pre><code>outline_depth: 2</code></pre>
<p>The default outline depth to use when opening keyword, note, path or tag view. Once any view is opened, use Ctrl-O to change the depth for that view.</p>
<h3 id="prefix"><a href="#prefix">prefix</a></h3>
<pre><code>prefix: "\n "
prefix_uses: "rj+-tldm"</code></pre>
<p>Apply <code>prefix</code> (whitespace only) to the <span class="citation">@keys</span> in <code>prefix_uses</code> when displaying and saving items. The default would cause the selected elements to begin on a newline and indented by two spaces. E.g.,</p>
<pre><code>+ summary @s 2014-05-09 12am @z US/Eastern
@m memo
@j job 1 &f 20140510T1411;20140509T0000 &q 1
@j job 2 &f 20140510T1412;20140509T0000 &q 2
@j job 3 &q 3
@d description</code></pre>
<h3 id="report"><a href="#report">report</a></h3>
<pre><code>report_begin: '1'
report_end: '+1/1'
report_colors: 2
report_width1: 61
report_width2: 19</code></pre>
<p>Report begin and end are fuzzy parsed dates specifying the default period for reports that group by dates. Each line in the file specified by <code>report_specifications</code> provides a possible specification for a report. E.g.</p>
<pre><code>a MMM yyyy; k[0]; k[1:] -b -1/1 -e 1
a k, MMM yyyy -b -1/1 -e 1
c ddd MMM d yyyy
c f</code></pre>
<p>In custom view these appear in the report specifications pop-up list. A specification from the list can be selected and, perhaps, modified or an entirely new specification can be entered. See <a href="#custom-view">Custom view</a> for details. See also the <a href="#agenda">agenda</a> settings above.</p>
<h3 id="retain_ids"><a href="#retain_ids">retain_ids</a></h3>
<pre><code>retain_ids: false</code></pre>
<p>If true, the unique ids that etm associates with items will be written to the data files and retained between sessions. If false, new ids will be generated for each session.</p>
<p>Retaining ids enables etm to avoid duplicates when importing and exporting iCalendar files.</p>
<h3 id="show_finished"><a href="#show_finished">show_finished</a></h3>
<pre><code>show_finished: 1</code></pre>
<p>Show this many of the most recent completions of repeated tasks or, if 0, show all completions.</p>
<h3 id="smtp"><a href="#smtp">smtp</a></h3>
<pre><code>smtp_from: dnlgrhm@gmail.com
smtp_id: dnlgrhm
smtp_pw: **********
smtp_server: smtp.gmail.com</code></pre>
<p>Required settings for the smtp server to be used for email alerts.</p>
<h3 id="sms"><a href="#sms">sms</a></h3>
<pre><code>sms_message: '!summary!'
sms_subject: '!time_span!'
sms_from: dnlgrhm@gmail.com
sms_pw: **********
sms_phone: 0123456789@vtext.com
sms_server: smtp.gmail.com:587</code></pre>
<p>Required settings for text messaging in alerts. Enter the 10-digit area code and number and mms extension for the mobile phone to receive the text message when no numbers are specified in the alert. The illustrated phone number is for Verizon. Here are the mms extensions for the major carriers:</p>
<pre><code>Alltel @message.alltel.com
AT&T @txt.att.net
Nextel @messaging.nextel.com
Sprint @messaging.sprintpcs.com
SunCom @tms.suncom.com
T-mobile @tmomail.net
VoiceStream @voicestream.net
Verizon @vtext.com</code></pre>
<h3 id="snooze"><a href="#snooze">snooze</a></h3>
<pre><code>snooze_command: ''
snooze_minutes: 10</code></pre>
<p>If <code>snooze_command</code> is given, it will be executed when the timer expires; otherwise a beep will be sounded. The default number of minutes for a snooze is given by <code>snooze_minutes</code>. When a snooze timer is active, the time that the timer will expire is displayed in the status bar in the format +H:M:S(am/pm). When a countdown and a snooze timer are both active, the one that will expire first is displayed in the status bar.</p>
<h3 id="style"><a href="#style">style</a></h3>
<pre><code>style: default</code></pre>
<p>The style to be used for Tk/Tcl widgets. Options for linux include clam, alt, default and classic. Options for OSX add aqua. Note that aqua does not support background colors for buttons and may not be suitable with darker background colors.</p>
<h3 id="sundayfirst"><a href="#sundayfirst">sundayfirst</a></h3>
<pre><code>sundayfirst: false</code></pre>
<p>The setting affects only the twelve month calendar display.</p>
<h3 id="update_minutes"><a href="#update_minutes">update_minutes</a></h3>
<pre><code>update_minutes: 15</code></pre>
<p>Update <code>current_html</code>, <code>current_text</code> and the files in <code>icssync_folder</code> when the number of minutes past the hour modulo <code>update_minutes</code> is equal to zero. I.e. with the default, the update would occur on the hour and at 15, 30 and 45 minutes past the hour. Acceptable settings are integers between 1 and 59. Note that with a setting greater than or equal to 30, the update will occur only twice each hour.</p>
<h3 id="vcs_settings"><a href="#vcs_settings">vcs_settings</a></h3>
<pre><code>vcs_settings:
command: ''
commit: ''
dir: ''
file: ''
history: ''
init: ''
limit: ''</code></pre>
<p>These settings are ignored unless the setting for <code>vcs_system</code> below is either <code>git</code> or <code>mercurial</code>.</p>
<p>Default values will be provided for these settings based on the choice of <code>vcs_system</code> below. Any of the settings that you define here will overrule the defaults.</p>
<p>Here, for example, are the default values of these settings for git under OS X:</p>
<pre><code>vcs_settings:
command: '/usr/bin/git --git-dir {repo} --work-dir {work}'
commit: '/usr/bin/git --git-dir {repo} --work-dir {work} add */\*.txt
&& /usr/bin/git --git-dir {repo} --work-dir {work} commit -a -m "{mesg}"'
dir: '.git'
file: ''
history: '/usr/bin/git -git-dir {repo} --work-dir {work} log
--pretty=format:"- %ar: %an%n%w(70,0,4)%s" -U1 {numchanges}
{file}'
init: '/usr/bin/git init {work}; /usr/bin/git -git-dir {repo}
--work-dir {work} add */\*.txt; /usr/bin/git-git-dir {repo}
--work-dir {work} commit -a -m "{mesg}"'
limit: '-n'</code></pre>
<p>In these settings, <code>{mesg}</code> will be replaced with an internally generated commit message, <code>{numchanges}</code> with an expression that depends upon <code>limit</code> that determines how many changes to show and, when a file is selected, <code>{file}</code> with the corresponding path. If <code>~/.etm/data</code> is your etm datadir, the <code>{repo}</code> would be replaced with <code>~/.etm/data/.git</code> and {work} with <code>~/.etm/data</code>.</p>
<p>Leave these settings empty to use the defaults.</p>
<h3 id="vcs_system"><a href="#vcs_system">vcs_system</a></h3>
<pre><code>vcs_system: ''</code></pre>
<p>This setting must be either <code>''</code> or <code>git</code> or <code>mercurial</code>.</p>
<p>If you specify either git or mercurial here (and have it installed on your system), then etm will automatically commit any changes you make to any of your data files. The history of these changes is available in the GUI with the show changes command (<em>Ctrl-H</em>) and you can, of course, use any git or mercurial commands in your terminal to, for example, restore a previous version of a file.</p>
<h3 id="weeks_after"><a href="#weeks_after">weeks_after</a></h3>
<pre><code>weeks_after: 52</code></pre>
<p>In the day view, all non-repeating, dated items are shown. Additionally all repetitions of repeating items with a finite number of repetitions are shown. This includes 'list-only' repeating items and items with <code>&u</code> (until) or <code>&t</code> (total number of repetitions) entries. For repeating items with an infinite number of repetitions, those repetitions that occur within the first <code>weeks_after</code> weeks after the current week are displayed along with the first repetition after this interval. This assures that for infrequently repeating items such as voting for president, at least one repetition will be displayed.</p>
<h3 id="yearfirst"><a href="#yearfirst">yearfirst</a></h3>
<pre><code>yearfirst: true</code></pre>
<p>If yearfirst is true, the YY-MM-DD format will have precedence over MM-DD-YY in an ambiguous date. See also <code>dayfirst</code>.</p>
<h1 id="custom-view"><a href="#custom-view">Custom view</a></h1>
<p>You can create a custom display of your items using either the <em>custom view</em> in the GUI or the "c" command in the CLI. In both cases, you enter a specification that determines which items will be displayed and how they will be grouped and sorted.</p>
<p>A view <em>specification</em> begins with a <em>type character</em>, either <code>a</code> or <code>c</code>, followed by a <em>groupby setting</em> and then, perhaps, by one or more view <em>options</em>.</p>
<h2 id="view-type"><a href="#view-type">View type</a></h2>
<ul>
<li><p><strong>a</strong>: action</p>
<p>Actions only. Expenditures of time and money recorded in <em>actions</em> with output formatted using <code>action_template</code> computations and expansions. See <a href="#preferences">Preferences</a> for further details about the role of <code>action_template</code> in formatting actions output. Note that only <em>actions</em> are included in this view and, by default, all actions in your active calendars will be included.</p></li>
<li><p><strong>c</strong>: composite</p>
<p>Any item types, including actions, but without <code>action_template</code> computations and expansions. Note that only unfinished tasks and unfinished instances of repeating tasks will be displayed. By default, all items from your active calendars will be included.</p></li>
</ul>
<h2 id="groupby-setting"><a href="#groupby-setting">Groupby setting</a></h2>
<p>A semicolon separated list that determines how items will be grouped and sorted. Possible elements include elements from</p>
<ul>
<li><p>c: context</p></li>
<li><p>f: file path</p></li>
<li><p>k: keyword</p></li>
<li><p>l: location</p></li>
<li><p>t: tag</p></li>
<li><p>u: user</p></li>
</ul>
<p>and/or a <em>date specifications</em> where a <em>date specification</em> is either</p>
<ul>
<li>w: week number</li>
</ul>
<p>or a combination of one or more of the following:</p>
<ul>
<li><p>yy: 2-digit year</p></li>
<li><p>yyyy: 4-digit year</p></li>
<li><p>MM: month: 01 - 12</p></li>
<li><p>MMM: locale specific abbreviated month name: Jan - Dec</p></li>
<li><p>MMMM: locale specific month name: January - December</p></li>
<li><p>dd: month day: 01 - 31</p></li>
<li><p>ddd: locale specific abbreviated week day: Mon - Sun</p></li>
<li><p>dddd: locale specific week day: Monday - Sunday</p></li>
</ul>
<p>Note that the groupby specification affects which items will be displayed. Items that are missing an element specified in <code>groupby</code> will be omitted from the output. E.g., undated tasks and notes will be omitted when a date specification is included, items without keywords will be omitted when <code>k</code> is included and so forth. The latter behavior depends upon the value of the <a href="#m-missing">-m MISSING</a> option.</p>
<p>When a date specification is not included in the groupby setting, undated notes and tasks will be potentially included, but only those instances of dated items that correspond to the <em>relevant datetime</em> of the item of the item will be included, where the <em>relevant datetime</em> is the past due date for any past due tasks, the starting datetime for any non-repeating item and the datetime of the next instance for any repeating item.</p>
<p>Within groups, items are automatically sorted by date, type and time.</p>
<h2 id="groupby-examples"><a href="#groupby-examples">Groupby examples</a></h2>
<p>For example, the specification <code>c ddd, MMM dd yyyy</code> would group by year, month and day together to give output such as</p>
<pre><code>Fri, Apr 1 2011
items for April 1
Sat, Apr 2 2011
items for April 2
...</code></pre>
<p>On the other hand, the specification <code>a w; u; k[0]; k[1:]</code> would group by week number, user and keywords to give output such as</p>
<pre><code>13.1) 2014 Week 14: Mar 31 - Apr 6
6.3) agent 1
1.3) client 1
1.3) project 2
1.3) Activity (12)
5) client 2
4.5) project 1
4.5) Activity (21)
0.5) project 2
0.5) Activity (22)
6.8) agent 2
2.2) client 1
2.2) project 2
2.2) Activity (13)
4.6) client 2
3.9) project 1
3.9) Activity (23)
0.7) project 2
0.7) Activity (23)</code></pre>
<p>With the heirarchial elements, file path and keyword, it is possible to use parts of the element as well as the whole. Consider, for example, the file path <code>A/B/C</code> with the components <code>[A, B, C]</code>. Then for this file path:</p>
<pre><code>f[0] = A
f[:2] = A/B
f[2:] = C
f = A/B/C</code></pre>
<p>Suppose that keywords have the format <code>client:project</code>. Then grouping by year and month, then client and finally project to give output such as</p>
<pre><code>specification: a MMM yyyy; u; k[0]; k[1] -b 1 -e +1/1
13.1) Feb 2014
6.3) agent 1
1.3) client 1
1.3) project 2
1.3) Activity 12
5) client 2
4.5) project 1
4.5) Activity 21
0.5) project 2
0.5) Activity 22
6.8) agent 2
2.2) client 1
2.2) project 2
2.2) Activity 13
4.6) client 2
3.9) project 1
3.9) Activity 23
0.7) project 2
0.7) Activity 23</code></pre>
<h2 id="view-options"><a href="#view-options">View Options</a></h2>
<p>View options are listed below. View type <code>c</code> supports all options except <code>-d</code>. Type <code>a</code> supports all options except <code>-o</code>. These options can be used to further limit which items are displayed.</p>
<h3 id="b-begin_date"><a href="#b-begin_date">-b BEGIN_DATE</a></h3>
<p>Fuzzy parsed date. When a date specification is provided, limit the display of dated items to those with datetimes falling <em>on or after</em> this datetime. Relative day and month expressions can also be used so that, for example, <code>-b -14</code> would begin 14 days before the current date and <code>-b -1/1</code> would begin on the first day of the previous month. It is also possible to add (or subtract) a time period from the fuzzy date, e.g., <code>-b mon + 7d</code> would begin with the second Monday falling on or after today. Default: None.</p>
<h3 id="c-context-1"><a href="#c-context-1">-c CONTEXT</a></h3>
<p>Regular expression. Limit the display to items with contexts matching CONTEXT (ignoring case). Prepend an exclamation mark, i.e., use !CONTEXT rather than CONTEXT, to limit the display to items which do NOT have contexts matching CONTEXT.</p>
<h3 id="d-depth"><a href="#d-depth">-d DEPTH</a></h3>
<p>CLI only. In the GUI use <em>View/Set outline depth</em>. The default, <code>-d 0</code>, includes all outline levels. Use <code>-d 1</code> to include only level 1, <code>-d 2</code> to include levels 1 and 2 and so forth. This setting applies to the CLI only. In the GUI use the command <em>set outline depth</em>.</p>
<p>For example, modifying the specification above by adding <code>-d 3</code> would give the following:</p>
<pre><code>specification: a MMM yyyy; u; k[0]; k[1] -b 1 -e +1/1 -d 3
13.1) Feb 2014
6.3) agent 1
1.3) client 1
5) client 2
6.8) agent 2
2.2) client 1
4.6) client 2</code></pre>
<h3 id="e-end_date"><a href="#e-end_date">-e END_DATE</a></h3>
<p>Fuzzy parsed date. When a date specification is provided, limit the display of dated items to those with datetimes falling <em>before</em> this datetime. As with BEGIN_DATE relative month expressions can be used so that, for example, <code>-b -1/1 -e 1</code> would include all items from the previous month. As with <code>-b</code>, period strings can be appended, e.g., <code>-b mon -e mon + 7d</code> would include items from the week that begins with the first Monday falling on or after today. Default: None.</p>
<h3 id="f-file"><a href="#f-file">-f FILE</a></h3>
<p>Regular expression. Limit the display to items from files whose paths match FILE (ignoring case). Prepend an exclamation mark, i.e., use !FILE rather than FILE, to limit the display to items from files whose path does NOT match FILE.</p>
<h3 id="k-keyword-2"><a href="#k-keyword-2">-k KEYWORD</a></h3>
<p>Regular expression. Limit the display to items with contexts matching KEYWORD (ignoring case). Prepend an exclamation mark, i.e., use !KEYWORD rather than KEYWORD, to limit the display to items which do NOT have keywords matching KEYWORD.</p>
<h3 id="l-location-1"><a href="#l-location-1">-l LOCATION</a></h3>
<p>Regular expression. Limit the display to items with a location matching LOCATION (ignoring case). Prepend an exclamation mark, i.e., use !LOCATION rather than LOCATION, to limit the display to items which do NOT have a location that matches LOCATION.</p>
<h3 id="m-missing"><a href="#m-missing">-m MISSING</a></h3>
<p>Either 0 (the default) or 1. When 1 include items that would otherwise be excluded because of a <em>non-date</em>, groupby specification. E.g., <code>c k</code> would omit items without a keyword entry, but <code>c k -m 1</code> would include such items under a "None" heading. This option does not apply to date specifications, i.e., if a date specification is part of the groupby setting, then undated items will be excluded whatever the value of <code>-m</code>.</p>
<h3 id="o-omit"><a href="#o-omit">-o OMIT</a></h3>
<p>String. Composite type only. Show/hide a)ctions, d)elegated tasks, e)vents, g)roup tasks, n)otes, o)ccasions, s)omeday items and/or t)asks. For example, <code>-o on</code> would show everything except occasions and notes and <code>-o !on</code> would show only occasions and notes.</p>
<h3 id="s-summary"><a href="#s-summary">-s SUMMARY</a></h3>
<p>Regular expression. Limit the display to items containing SUMMARY (ignoring case) in the item summary. Prepend an exclamation mark, i.e., use !SUMMARY rather than SUMMARY, to limit the display to items which do NOT contain SUMMARY in the summary.</p>
<h3 id="s-search"><a href="#s-search">-S SEARCH</a></h3>
<p>Regular expression. Composite type only. Limit the display to items containing SEARCH (ignoring case) anywhere in the <em>item</em> or its file path. Prepend an exclamation mark, i.e., use !SEARCH rather than SEARCH, to limit the display to items which do NOT contain SEARCH in the item or its file path.</p>
<h3 id="t-tags-1"><a href="#t-tags-1">-t TAGS</a></h3>
<p>Comma separated list of case insensitive regular expressions. E.g., use</p>
<pre><code>-t tag1, !tag2</code></pre>
<p>or</p>
<pre><code>-t tag1, -t !tag2</code></pre>
<p>to display items with one or more tags that match 'tag1' but none that match 'tag2'.</p>
<h3 id="u-user-1"><a href="#u-user-1">-u USER</a></h3>
<p>Regular expression. Limit the display to items with user matching USER (ignoring case). Prepend an exclamation mark, i.e., use !USER rather than USER, to limit the display to items which do NOT have a user that matches USER.</p>
<h3 id="w-width"><a href="#w-width">-w WIDTH</a></h3>
<p>Non-negative integer. Truncate the output for column 1 if it exceeds this integer. Do not truncate if this integer is zero.</p>
<h3 id="w-width-1"><a href="#w-width-1">-W WIDTH</a></h3>
<p>Non-negative integer. Truncate the output for column 2 if it exceeds this integer.</p>
<h2 id="saving-view-specifications"><a href="#saving-view-specifications">Saving view specifications</a></h2>
<p>You can save view specifications in your specifications file, <code>~./etm/reports.cfg</code> by default, and then select them in the selection box at the bottom of the custom view window in the GUI or from a list in the CLI.</p>
<p>You can also add specifications to file in the GUI by selecting any item from the list and then replacing the content with anything you like. Press <em>Return</em> to <em>add</em> your specification temporarily to the list. <em>Note that the original entry will not be affected.</em> When you leave the custom view you will have an opportunity to save the additions you have made. If you choose a file, your additions will be inserted into the list and it will be opened for editing.</p>
<h1 id="shortcuts"><a href="#shortcuts">Shortcuts</a></h1>
<h2 id="menu"><a href="#menu">Menu</a></h2>
<pre><code>File
New
Item N
File Shift-N
Timer
Start action timer T
Finish action timer Shift-T
Toggle current timer I
Delete action timer Shift-I
Assign idle time Ctrl-I
Reset idle to zero minutes
Toggle idle timer display
Countdown timer Z
Open
Data file ... Shift-F
Configuration file ... Shift-C
Preferences Shift-P
Scratchpad Shift-S
----
Quit Ctrl-Q
View
Agenda Ctrl-A
Week Ctrl-W
Month Ctrl-M
Tag Ctrl-T
Keyword Ctrl-K
Path Ctrl-P
Note Ctrl-N
Custom Ctrl-C
----
Set outline filter Ctrl-F
Clear outline filter Shift-Ctrl-F
Toggle labels L
Set outline depth O
Toggle finished X
Item
Copy C
Delete BackSpace
Edit E
Edit file Shift-E
Finish F
Move M
Reschedule R
Schedule new S
Klone as timer K
Show date and time details D
Open link G
Show user details U
Tools
Home Home
Jump to date J
----
Show remaining alerts for today A
List busy times in week/month B
List free times in week/month F
Date and time calculator Shift-D
Available dates calculator Shift-A
Yearly calendar Shift-Y
----
Show outline as text Shift-O
Print outline P
Export to iCal Shift-X
Update calendar subscriptions Shift-M
History of changes Shift-H
Custom
Create and display selected report Return
Export report in text format ... Ctrl-T
Export report in csv format ... Ctrl-X
Save changes to report specifications Ctrl-W
Expand report list Down
Help
Search
Shortcuts ?
User manual F1
About F2
Check for update F3 </code></pre>
<h2 id="edit"><a href="#edit">Edit</a></h2>
<pre><code>Show completions Ctrl-Space
Cancel Escape
Save and Close Ctrl-S </code></pre>
</body>
</html>
|
