This file is indexed.

/usr/share/doc/zsh-common/html/Calendar-Function-System.html is in zsh-doc 5.1.1-1ubuntu2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>zsh: 23 Calendar Function System</title>

<meta name="description" content="zsh: 23 Calendar Function System">
<meta name="keywords" content="zsh: 23 Calendar Function System">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2any">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Calendar-Function-System"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Zsh-Modules.html#Zsh-Modules" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="Zsh-Modules.html#The-zsh_002fzutil-Module" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Description-6" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="Calendar-Function-System-1"></a>
<h1 class="chapter">23 Calendar Function System</h1>
<a name="index-calendar-function-system"></a>
<a name="index-zsh_002fdatetime_002c-function-system-based-on"></a>

<hr>
<a name="Description-6"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section">23.1 Description</h2>

<p>The shell is supplied with a series of functions to replace and enhance the
traditional Unix <tt>calendar</tt> programme, which warns the user of imminent
or future events, details of which are stored in a text file (typically
<tt>calendar</tt> in the user&rsquo;s home directory).  The version provided here
includes a mechanism for alerting the user when an event is due.
</p>
<p>In addition functions <tt>age</tt>, <tt>before</tt> and <tt>after</tt> are provided
that can be used in a glob qualifier; they allow files to be selected
based on their modification times.
</p>
<p>The format of the <tt>calendar</tt> file and the dates used there in and in
the <tt>age</tt> function are described first, then the functions that can
be called to examine and modify the <tt>calendar</tt> file.
</p>
<p>The functions here depend on the availability of the <tt>zsh/datetime</tt>
module which is usually installed with the shell.  The library function
<tt>strptime()</tt> must be available; it is present on most recent
operating systems.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Calendar-File-and-Date-Formats">23.2 File and Date Formats</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#Calendar-System-User-Functions">23.3 User Functions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#Calendar-Styles">23.4 Styles</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#Calendar-Utility-Functions">23.5 Utility functions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#Calendar-Bugs">23.6 Bugs</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Calendar-File-and-Date-Formats"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Description-6" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-Format" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="File-and-Date-Formats"></a>
<h2 class="section">23.2 File and Date Formats</h2>


<hr>
<a name="Calendar-File-Format"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Date-Format" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.2.1 Calendar File Format</h3>

<p>The calendar file is by default <tt>~/calendar</tt>.  This can be configured
by the <tt>calendar-file</tt> style, see
<a href="#Calendar-Styles">Styles</a>.  The basic format consists
of a series of separate lines, with no indentation, each including
a date and time specification followed by a description of the event.
</p>
<p>Various enhancements to this format are supported, based on the syntax
of Emacs calendar mode.  An indented line indicates a continuation line
that continues the description of the event from the preceding line
(note the date may not be continued in this way).  An initial ampersand
(<tt>&amp;</tt>) is ignored for compatibility.
</p>
<p>An indented line on which the first non-whitespace character is <tt>#</tt>
is not displayed with the calendar entry, but is still scanned for
information.  This can be used to hide information useful to the
calendar system but not to the user, such as the unique identifier
used by <tt>calendar_add</tt>.
</p>
<p>The Emacs extension that a date with no description may refer to a number
of succeeding events at different times is not supported.
</p>
<p>Unless the <tt>done-file</tt> style has been altered, any events which
have been processed are appended to the file with the same name as the
calendar file with the suffix <tt>.done</tt>, hence <tt>~/calendar.done</tt> by
default.
</p>
<p>An example is shown below.
</p>

<hr>
<a name="Date-Format"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-Format" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Relative-Time-Format" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.2.2 Date Format</h3>

<p>The format of the date and time is designed to allow flexibility without
admitting ambiguity.  (The words &lsquo;date&rsquo; and &lsquo;time&rsquo; are both used in the
documentation below; except where specifically noted this implies a string
that may include both a date and a time specification.)  Note that there is
no localization support; month and day names must be in English and
separator characters are fixed.  Matching is case insensitive, and only the
first three letters of the names are significant, although as a special
case a form beginning &quot;month&quot; does not match &quot;Monday&quot;.  Furthermore, time
zones are not handled; all times are assumed to be local.
</p>
<p>It is recommended that, rather than exploring the intricacies of the
system, users find a date format that is natural to them and stick to it.
This will avoid unexpected effects.  Various key facts should be noted.
</p>
<ul>
<li> In particular, note the confusion between
<var>month</var><tt>/</tt><var>day</var><tt>/</tt><var>year</var> and
<var>day</var><tt>/</tt><var>month</var><tt>/</tt><var>year</var> when the month is numeric; these
formats should be avoided if at all possible.  Many alternatives are
available.
</li><li> The year must be given in full to avoid confusion, and only years
from 1900 to 2099 inclusive are matched.
</li></ul>

<p>The following give some obvious examples; users finding here
a format they like and not subject to vagaries of style may skip
the full description.  As dates and times are matched separately
(even though the time may be embedded in the date), any date format
may be mixed with any format for the time of day provide the
separators are clear (whitespace, colons, commas).
</p>
<div class="example">
<pre class="example">2007/04/03 13:13
2007/04/03:13:13
2007/04/03 1:13 pm
3rd April 2007, 13:13
April 3rd 2007 1:13 p.m.
Apr 3, 2007 13:13
Tue Apr 03 13:13:00 2007
13:13 2007/apr/3
</pre></div>

<p>More detailed rules follow.
</p>
<p>Times are parsed and extracted before dates.  They must use colons
to separate hours and minutes, though a dot is allowed before seconds
if they are present.  This limits time formats to the following:
</p>
<ul>
<li> <var>HH</var><tt>:</tt><var>MM</var>[<tt>:</tt><var>SS</var>[<tt>.</tt><var>FFFFF</var>]] [<tt>am</tt>|<tt>pm</tt>|<tt>a.m.</tt>|<tt>p.m.</tt>]
</li><li> <var>HH</var><tt>:</tt><var>MM</var><tt>.</tt><var>SS</var>[<tt>.</tt><var>FFFFF</var>] [<tt>am</tt>|<tt>pm</tt>|<tt>a.m.</tt>|<tt>p.m.</tt>]
</li></ul>

<p>Here, square brackets indicate optional elements, possibly with
alternatives.  Fractions of a second are recognised but ignored.  For
absolute times (the normal format require by the <tt>calendar</tt> file and the
<tt>age</tt>, <tt>before</tt> and <tt>after</tt> functions) a date is mandatory but a
time of day is not; the time returned is at the start of the date.  One
variation is allowed: if <tt>a.m.</tt> or <tt>p.m.</tt> or one of their variants
is present, an hour without a minute is allowed, e.g. <tt>3 p.m.</tt>.
</p>
<p>Time zones are not handled, though if one is matched following a time
specification it will be removed to allow a surrounding date to be
parsed.  This only happens if the format of the timezone is not too
unusual.  The following are examples of forms that are understood:
</p>
<div class="example">
<pre class="example">+0100
GMT
GMT-7
CET+1CDT
</pre></div>

<p>Any part of the timezone that is not numeric must have exactly three
capital letters in the name.
</p>
<p>Dates suffer from the ambiguity between <var>DD</var><tt>/</tt><var>MM</var><tt>/</tt><var>YYYY</var>
and <var>MM</var><tt>/</tt><var>DD</var><tt>/</tt><var>YYYY</var>.  It is recommended this form is
avoided with purely numeric dates, but use of ordinals,
eg. <tt>3rd/04/2007</tt>, will resolve the ambiguity as the ordinal is always
parsed as the day of the month.  Years must be four digits (and the first
two must be <tt>19</tt> or <tt>20</tt>); <tt>03/04/08</tt> is not recognised.  Other
numbers may have leading zeroes, but they are not required.  The following
are handled:
</p>
<ul>
<li> <var>YYYY</var><tt>/</tt><var>MM</var><tt>/</tt><var>DD</var>
</li><li> <var>YYYY</var><tt>-</tt><var>MM</var><tt>-</tt><var>DD</var>
</li><li> <var>YYYY</var><tt>/</tt><var>MNM</var><tt>/</tt><var>DD</var>
</li><li> <var>YYYY</var><tt>-</tt><var>MNM</var><tt>-</tt><var>DD</var>
</li><li> <var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>] <var>MNM</var>[<tt>,</tt>] [ <var>YYYY</var> ]
</li><li> <var>MNM</var> <var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>][<tt>,</tt>] [ <var>YYYY</var> ]
</li><li> <var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>]<tt>/</tt><var>MM</var>[<tt>,</tt>] <var>YYYY</var>
</li><li> <var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>]<tt>/</tt><var>MM</var><tt>/</tt><var>YYYY</var>
</li><li> <var>MM</var><tt>/</tt><var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>][<tt>,</tt>] <var>YYYY</var>
</li><li> <var>MM</var><tt>/</tt><var>DD</var>[<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>]<tt>/</tt><var>YYYY</var>
</li></ul>

<p>Here, <var>MNM</var> is at least the first three letters of a month name,
matched case-insensitively.  The remainder of the month name may appear but
its contents are irrelevant, so janissary, febrile, martial, apricot,
maybe, junta, etc. are happily handled.
</p>
<p>Where the year is shown as optional, the current year is assumed.  There
are only two such cases, the form <tt>Jun 20</tt> or <tt>14 September</tt> (the only
two commonly occurring forms, apart from a &quot;the&quot; in some forms of English,
which isn&rsquo;t currently supported).  Such dates will of course become
ambiguous in the future, so should ideally be avoided.
</p>
<p>Times may follow dates with a colon, e.g. <tt>1965/07/12:09:45</tt>; this is in
order to provide a format with no whitespace.  A comma and whitespace are
allowed, e.g. <tt>1965/07/12, 09:45</tt>.  Currently the order of these
separators is not checked, so illogical formats such as <tt>1965/07/12, :
,09:45</tt> will also be matched.  For simplicity such variations are not shown
in the list above.  Otherwise, a time is only recognised as being
associated with a date if there is only whitespace in between, or if the
time was embedded in the date.
</p>
<p>Days of the week are not normally scanned, but will be ignored if they
occur at the start of the date pattern only.  However, in contexts where it
is useful to specify dates relative to today, days of the week with no
other date specification may be given.  The day is assumed to be either
today or within the past week.  Likewise, the words <tt>yesterday</tt>,
<tt>today</tt> and <tt>tomorrow</tt> are handled.  All matches are case-insensitive.
Hence if today is Monday, then <tt>Sunday</tt> is equivalent to <tt>yesterday</tt>,
<tt>Monday</tt> is equivalent to <tt>today</tt>, but <tt>Tuesday</tt> gives a date six
days ago.  This is not generally useful within the calendar file.
Dates in this format may be combined with a time specification; for
example <tt>Tomorrow, 8 p.m.</tt>.
</p>
<p>For example, the standard date format:
</p>
<div class="example">
<pre class="example">Fri Aug 18 17:00:48 BST 2006
</pre></div>

<p>is handled by matching <var>HH</var><tt>:</tt><var>MM</var><tt>:</tt><var>SS</var> and removing it
together with the matched (but unused) time zone.  This leaves the following:
</p>
<div class="example">
<pre class="example">Fri Aug 18 2006
</pre></div>

<p><tt>Fri</tt> is ignored and the rest is matched according to the standard rules.
</p>

<hr>
<a name="Relative-Time-Format"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Date-Format" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Example-3" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.2.3 Relative Time Format</h3>

<p>In certain places relative times are handled.  Here, a date is not allowed;
instead a combination of various supported periods are allowed, together
with an optional time.  The periods must be in order from most to
least significant.
</p>
<p>In some cases, a more accurate calculation is possible when there is an
anchor date:  offsets of months or years pick the correct day, rather than
being rounded, and it is possible to pick a particular day in a month as
&lsquo;(1st Friday)&rsquo;, etc., as described in more detail below.
</p>
<p>Anchors are available in the following cases.  If one or two times are
passed to the function <tt>calendar</tt>, the start time acts an anchor for the
end time when the end time is relative (even if the start time is
implicit).  When examining calendar files, the scheduled event being
examined anchors the warning time when it is given explicitly by means of
the <tt>WARN</tt> keyword; likewise, the scheduled event anchors a repetition
period when given by the <tt>RPT</tt> keyword, so that specifications such as
<tt>RPT 2 months, 3rd Thursday</tt> are handled properly.  Finally, the <tt>-R</tt>
argument to <tt>calendar_scandate</tt> directly provides an anchor for relative
calculations.
</p>
<p>The periods handled, with possible abbreviations are:
</p>
<dl compact="compact">
<dt>Years</dt>
<dd><p><tt>years</tt>, <tt>yrs</tt>, <tt>ys</tt>, <tt>year</tt>, <tt>yr</tt>, <tt>y</tt>, <tt>yearly</tt>.
A year is 365.25 days unless there is an anchor.
</p>
</dd>
<dt>Months</dt>
<dd><p><tt>months</tt>, <tt>mons</tt>, <tt>mnths</tt>, <tt>mths</tt>, <tt>month</tt>, <tt>mon</tt>,
<tt>mnth</tt>, <tt>mth</tt>, <tt>monthly</tt>.  Note that <tt>m</tt>, <tt>ms</tt>, <tt>mn</tt>, <tt>mns</tt>
are ambiguous and are <em>not</em> handled.  A month is a period
of 30 days rather than a calendar month unless there is an anchor.
</p>
</dd>
<dt>Weeks</dt>
<dd><p><tt>weeks</tt>, <tt>wks</tt>, <tt>ws</tt>, <tt>week</tt>, <tt>wk</tt>, <tt>w</tt>, <tt>weekly</tt>
</p>
</dd>
<dt>Days</dt>
<dd><p><tt>days</tt>, <tt>dys</tt>, <tt>ds</tt>, <tt>day</tt>, <tt>dy</tt>, <tt>d</tt>, <tt>daily</tt>
</p>
</dd>
<dt>Hours</dt>
<dd><p><tt>hours</tt>, <tt>hrs</tt>, <tt>hs</tt>, <tt>hour</tt>, <tt>hr</tt>, <tt>h</tt>, <tt>hourly</tt>
</p>
</dd>
<dt>Minutes</dt>
<dd><p><tt>minutes</tt>, <tt>mins</tt>, <tt>minute</tt>, <tt>min</tt>, but <em>not</em> <tt>m</tt>,
<tt>ms</tt>, <tt>mn</tt> or <tt>mns</tt>
</p>
</dd>
<dt>Seconds</dt>
<dd><p><tt>seconds</tt>, <tt>secs</tt>, <tt>ss</tt>, <tt>second</tt>, <tt>sec</tt>, <tt>s</tt>
</p>
</dd>
</dl>

<p>Spaces between the numbers are optional, but are required between items,
although a comma may be used (with or without spaces).
</p>
<p>The forms <tt>yearly</tt> to <tt>hourly</tt> allow the number to be omitted; it is
assumed to be 1.  For example, <tt>1 d</tt> and <tt>daily</tt> are equivalent.  Note
that using those forms with plurals is confusing; <tt>2 yearly</tt> is the same
as <tt>2 years</tt>, <em>not</em> twice yearly, so it is recommended they only
be used without numbers.
</p>
<p>When an anchor time is present, there is an extension to handle regular
events in the form of the <var>n</var>th <var>some</var>day of the month.  Such a
specification must occur immediately after any year and month
specification, but before any time of day, and must be in the form
<var>n</var>(<tt>th</tt>|<tt>st</tt>|<tt>rd</tt>) <var>day</var>, for example <tt>1st Tuesday</tt> or
<tt>3rd Monday</tt>.  As in other places, days are matched case insensitively,
must be in English, and only the first three letters are significant except
that a form beginning &lsquo;month&rsquo; does not match &lsquo;Monday&rsquo;.  No attempt is made
to sanitize the resulting date; attempts to squeeze too many occurrences
into a month will push the day into the next month (but in the obvious
fashion, retaining the correct day of the week).
</p>
<p>Here are some examples:
</p>
<div class="example">
<pre class="example">30 years 3 months 4 days 3:42:41
14 days 5 hours
Monthly, 3rd Thursday
4d,10hr
</pre></div>


<hr>
<a name="Example-3"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Relative-Time-Format" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-File-and-Date-Formats" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-System-User-Functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.2.4 Example</h3>

<p>Here is an example calendar file.  It uses a consistent date format,
as recommended above.
</p>
<div class="example">
<pre class="example">Feb 1, 2006 14:30 Pointless bureaucratic meeting
Mar 27, 2006 11:00 Mutual recrimination and finger pointing
  Bring water pistol and waterproofs
Mar 31, 2006 14:00 Very serious managerial pontification
  # UID 12C7878A9A50
Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday
</pre></div>

<p>The second entry has a continuation line.  The third entry has a
continuation line that will not be shown when the entry is displayed, but
the unique identifier will be used by the <tt>calendar_add</tt> function when
updating the event.  The fourth entry will produce a warning 30 minutes
before the event (to allow you to equip yourself appropriately).  The fifth
entry repeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the
same time.
</p>
<hr>
<a name="Calendar-System-User-Functions"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Example-3" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-system-functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="User-Functions"></a>
<h2 class="section">23.3 User Functions</h2>

<p>This section describes functions that are designed to be called
directly by the user.  The first part describes those functions
associated with the user&rsquo;s calendar; the second part describes
the use in glob qualifiers.
</p>

<hr>
<a name="Calendar-system-functions"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-System-User-Functions" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-System-User-Functions" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Glob-qualifiers" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.3.1 Calendar system functions</h3>

<dl compact="compact">
<dd><a name="index-calendar"></a>

</dd>
<dt><tt>calendar </tt>[ <tt>-abdDsv</tt> ] [ <tt>-C</tt> <var>calfile</var> ] [ <tt>-n</tt> <var>num</var> ] [ <tt>-S</tt> <var>showprog</var> ]</dt>
<dt><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt>[ [ <var>start</var> ] <var>end</var> ]</dt>
<dt><tt>calendar -r</tt> [ <tt>-abdDrsv</tt> ] [ <tt>-C</tt> <var>calfile</var> ] [ <tt>-n</tt> <var>num</var> ] [ <tt>-S</tt> <var>showprog</var> ]</dt>
<dt><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt>[ <var>start</var> ]</dt>
<dd><p>Show events in the calendar.
</p>
<p>With no arguments, show events from the start of today until the end of
the next working day after today.  In other words, if today is Friday,
Saturday, or Sunday, show up to the end of the following Monday, otherwise
show today and tomorrow.
</p>
<p>If <var>end</var> is given, show events from the start of today up to the time
and date given, which is in the format described in the previous section.
Note that if this is a date the time is assumed to be midnight at the
start of the date, so that effectively this shows all events before
the given date.
</p>
<p><var>end</var> may start with a <tt>+</tt>, in which case the remainder of the
specification is a relative time format as described in the previous
section indicating the range of time from the start time that is to
be included.
</p>
<p>If <var>start</var> is also given, show events starting from that time and date.
The word <tt>now</tt> can be used to indicate the current time.
</p>
<p>To implement an alert when events are due, include <tt>calendar -s</tt> in your
<tt>~/.zshrc</tt> file.
</p>
<p>Options:
</p>
<dl compact="compact">
<dt><tt>-a</tt></dt>
<dd><p>Show all items in the calendar, regardless of the <tt>start</tt> and
<tt>end</tt>.
</p>
</dd>
<dt><tt>-b</tt></dt>
<dd><p>Brief:  don&rsquo;t display continuation lines (i.e. indented lines following
the line with the date/time), just the first line.
</p>
</dd>
<dt><tt>-B</tt> <var>lines</var></dt>
<dd><p>Brief: display at most the first <var>lines</var> lines of the calendar
entry.  &lsquo;<tt>-B 1</tt>&rsquo; is equivalent to &lsquo;<tt>-b</tt>&rsquo;.
</p>
</dd>
<dt><tt>-C</tt> <var>calfile</var></dt>
<dd><p>Explicitly specify a calendar file instead of the value of
the <tt>calendar-file</tt> style or the default <tt>~/calendar</tt>.
</p>
</dd>
<dt><tt>-d</tt></dt>
<dd><p>Move any events that have passed from the calendar file to the
&quot;done&quot; file, as given by the <tt>done-file</tt> style or the default
which is the calendar file with <tt>.done</tt> appended.  This option
is implied by the <tt>-s</tt> option.
</p>
</dd>
<dt><tt>-D</tt></dt>
<dd><p>Turns off the option <tt>-d</tt>, even if the <tt>-s</tt> option is also present.
</p>
</dd>
<dt><tt>-n</tt> <var>num</var>, <tt>-</tt><var>num</var></dt>
<dd><p>Show at least <var>num</var> events, if present in the calendar file, regardless
of the <tt>start</tt> and <tt>end</tt>.
</p>
</dd>
<dt><tt>-r</tt></dt>
<dd><p>Show all the remaining options in the calendar, ignoring the given <var>end</var>
time.  The <var>start</var> time is respected; any argument given is treated
as a <var>start</var> time.
</p>
</dd>
<dt><tt>-s</tt></dt>
<dd><p>Use the shell&rsquo;s <tt>sched</tt> command to schedule a timed event that
will warn the user when an event is due.  Note that the <tt>sched</tt> command
only runs if the shell is at an interactive prompt; a foreground task
blocks the scheduled task from running until it is finished.
</p>
<p>The timed event usually runs the programme <tt>calendar_show</tt> to show
the event, as described in
<a href="#Calendar-Utility-Functions">Utility functions</a>.
</p>
<p>By default, a warning of the event is shown five minutes before it is due.
The warning period can be configured by the style <tt>warn-time</tt> or
for a single calendar entry by including <tt>WARN</tt> <var>reltime</var> in the first
line of the entry, where <var>reltime</var> is one of the usual relative time
formats.
</p>
<p>A repeated event may be indicated by including <tt>RPT</tt> <var>reldate</var> in the
first line of the entry.  After the scheduled event has been displayed
it will be re-entered into the calendar file at a time <var>reldate</var>
after the existing event.  Note that this is currently the only use
made of the repeat count, so that it is not possible to query the schedule
for a recurrence of an event in the calendar until the previous event
has passed.
</p>
<p>If <tt>RPT</tt> is used, it is also possible to specify that certain
recurrences of an event are rescheduled or cancelled.  This is
done with the <tt>OCCURRENCE</tt> keyword, followed by whitespace and the
date and time of the occurrence in the regular sequence, followed by
whitespace and either the date and time of the rescheduled event or
the exact string <tt>CANCELLED</tt>.  In this case the date and time must
be in exactly the &quot;date with local time&quot; format used by the
<tt>text/calendar</tt> MIME type (RFC 2445),
<var>&lt;YYYY&gt;&lt;MM&gt;&lt;DD&gt;</var><tt>T</tt><var>&lt;hh&gt;&lt;mm&gt;&lt;ss&gt;</var> (note the presence of the literal
character <tt>T</tt>).  The first word (the regular recurrence) may be
something other than a proper date/time to indicate that the event
is additional to the normal sequence; a convention that retains
the formatting appearance is <tt>XXXXXXXXTXXXXXX</tt>.
</p>
<p>Furthermore, it is useful to record the next regular recurrence
(as then the displayed date may be for a rescheduled event so cannot
be used for calculating the regular sequence).  This is specified by
<tt>RECURRENCE</tt> and a time or date in the same format.  <tt>calendar_add</tt>
adds such an indication when it encounters a recurring event that does not
include one, based on the headline date/time.
</p>
<p>If <tt>calendar_add</tt> is used to update occurrences the <tt>UID</tt> keyword
described there should be present in both the existing entry and the added
occurrence in order to identify recurring event sequences.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">Thu May 6, 2010 11:00 Informal chat RPT 1 week
  # RECURRENCE 20100506T110000
  # OCCURRENCE 20100513T110000 20100513T120000
  # OCCURRENCE 20100520T110000 CANCELLED
</pre></div>

<p>The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour
later.  The event that occurs a week later is cancelled.  The occurrences
are given on a continuation line starting with a <tt>#</tt> character so will
not usually be displayed as part of the event.  As elsewhere, no account of
time zones is taken with the times. After the next event occurs the headline
date/time will be &lsquo;<tt>Thu May 13, 2010 12:00</tt>&rsquo; while the <tt>RECURRENCE</tt>
date/time will be &lsquo;<tt>20100513T110000</tt>&rsquo; (note that cancelled and
moved events are not taken account of in the <tt>RECURRENCE</tt>, which
records what the next regular recurrence is, but they are accounted for in
the headline date/time).
</p>
<p>It is safe to run <tt>calendar -s</tt> to reschedule an existing event
(if the calendar file has changed, for example), and also to have it
running in multiples instances of the shell since the calendar file
is locked when in use.
</p>
<p>By default, expired events are moved to the &quot;done&quot; file; see the <tt>-d</tt>
option.  Use <tt>-D</tt> to prevent this.
</p>
</dd>
<dt><tt>-S</tt> <var>showprog</var></dt>
<dd><p>Explicitly specify a programme to be used for showing events instead
of the value of the <tt>show-prog</tt> style or the default <tt>calendar_show</tt>.
</p>
</dd>
<dt><tt>-v</tt></dt>
<dd><p>Verbose:  show more information about stages of processing.  This
is useful for confirming that the function has successfully parsed
the dates in the calendar file.
</p>
</dd>
</dl>

<a name="index-calendar_005fadd"></a>
</dd>
<dt><tt>calendar_add</tt> [ <tt>-BL</tt> ] <var>event</var> ...</dt>
<dd><p>Adds a single event to the calendar in the appropriate location.
The event can contain multiple lines, as described in
<a href="#Calendar-File-and-Date-Formats">File and Date Formats</a>.
Using this function ensures that the calendar file is sorted in date
and time order.  It also makes special arrangements for locking
the file while it is altered.  The old calendar is left in a file
with the suffix <tt>.old</tt>.
</p>
<p>The option <tt>-B</tt> indicates that backing up the calendar file will be
handled by the caller and should not be performed by <tt>calendar_add</tt>.  The
option <tt>-L</tt> indicates that <tt>calendar_add</tt> does not need to lock the
calendar file as it is already locked.  These options will not usually be
needed by users.
</p>
<p>If the style <tt>reformat-date</tt> is true, the date and time of the
new entry will be rewritten into the standard date format:  see
the descriptions of this style and the style <tt>date-format</tt>.
</p>
<p>The function can use a unique identifier stored with each event to ensure
that updates to existing events are treated correctly.  The entry
should contain the word <tt>UID</tt>, followed by whitespace, followed by
a word consisting entirely of hexadecimal digits of arbitrary length
(all digits are significant, including leading zeroes).  As the UID
is not directly useful to the user, it is convenient to hide it on
an indented continuation line starting with a <tt>#</tt>, for example:
</p>
<div class="example">
<pre class="example">Aug 31, 2007 09:30  Celebrate the end of the holidays
  # UID 045B78A0
</pre></div>

<p>The second line will not be shown by the <tt>calendar</tt> function.
</p>
<p>It is possible to specify the <tt>RPT</tt> keyword followed by <tt>CANCELLED</tt>
instead of a relative time.  This causes any matched event or series
of events to be cancelled (the original event does not have to be marked
as recurring in order to be cancelled by this method).  A <tt>UID</tt> is
required in order to match an existing event in the calendar.
</p>
<p><tt>calendar_add</tt> will attempt to manage recurrences and occurrences of
repeating events as described for event scheduling by <tt>calendar -s</tt>
above.  To reschedule or cancel a single event <tt>calendar_add</tt> should be
called with an entry that includes the correct <tt>UID</tt> but does <em>not</em>
include the <tt>RPT</tt> keyword as this is taken to mean the entry applies to a
series of repeating events and hence replaces all existing information.
Each rescheduled or cancelled occurrence must have an <tt>OCCURRENCE</tt>
keyword in the entry passed to <tt>calendar_add</tt> which will be merged into
the calendar file.  Any existing reference to the occurrence is replaced.
An occurrence that does not refer to a valid existing event is added as a
one-off occurrence to the same calendar entry.
</p>
<a name="index-calendar_005fedit"></a>
</dd>
<dt><tt>calendar_edit</tt></dt>
<dd><p>This calls the user&rsquo;s editor to edit the calendar file.  If
there are arguments, they are taken as the editor to use (the file name
is appended to the commands); otherwise, the editor is given by the
variable <tt>VISUAL</tt>, if set, else the variable <tt>EDITOR</tt>.
</p>
<p>If the calendar scheduler was running, then after editing the file
<tt>calendar -s</tt> is called to update it.
</p>
<p>This function locks out the calendar system during the edit.
Hence it should be used to edit the calendar file if there is any
possibility of a calendar event occurring meanwhile.  Note this
can lead to another shell with calendar functions enabled hanging waiting
for a lock, so it is necessary to quit the editor as soon as possible.
</p>
<a name="index-calendar_005fparse"></a>
</dd>
<dt><tt>calendar_parse</tt> <var>calendar-entry</var></dt>
<dd><p>This is the internal function that analyses the parts of a calendar
entry, which is passed as the only argument.  The function returns
status 1 if the argument could not be parsed as a calendar entry
and status 2 if the wrong number of arguments were passed; it also sets the
parameter <tt>reply</tt> to an empty associative array.  Otherwise,
it returns status 0 and sets elements of the associative
array <tt>reply</tt> as follows:
</p>
<dl compact="compact">
<dt><tt>time</tt></dt>
<dd><p>The time as a string of digits in the same units as
<tt>$EPOCHSECONDS</tt>
</p></dd>
<dt><tt>schedtime</tt></dt>
<dd><p>The regularly scheduled time.  This may differ from
the actual event time <tt>time</tt> if this is a recurring event and the next
occurrence has been rescheduled.  Then <tt>time</tt> gives the actual time
and <tt>schedtime</tt> the time of the regular recurrence before modification.
</p></dd>
<dt><tt>text1</tt></dt>
<dd><p>The text from the line not including the date and time of the
event, but including any <tt>WARN</tt> or <tt>RPT</tt> keywords and values.
</p></dd>
<dt><tt>warntime</tt></dt>
<dd><p>Any warning time given by the <tt>WARN</tt> keyword as a string
of digits containing the time at which to warn in the same units as
<tt>$EPOCHSECONDS</tt>.  (Note this is an absolute time, not the relative time
passed down.)  Not set no <tt>WARN</tt> keyword and value were
matched.
</p></dd>
<dt><tt>warnstr</tt></dt>
<dd><p>The raw string matched after the <tt>WARN</tt> keyword, else unset.
</p></dd>
<dt><tt>rpttime</tt></dt>
<dd><p>Any recurrence time given by the <tt>RPT</tt> keyword as a string
of digits containing the time of the recurrence in the same units
as <tt>$EPOCHSECONDS</tt>.  (Note this is an absolute time.)  Not set if
no <tt>RPT</tt> keyword and value were matched.
</p></dd>
<dt><tt>schedrpttime</tt></dt>
<dd><p>The next regularly scheduled occurrence of a recurring
event before modification.  This may differ from <tt>rpttime</tt>, which is the
actual time of the event that may have been rescheduled from the regular
time.
</p></dd>
<dt><tt>rptstr</tt></dt>
<dd><p>The raw string matched after the <tt>RPT</tt> keyword, else unset.
</p></dd>
<dt><tt>text2</tt></dt>
<dd><p>The text from the line after removal of the date and any
keywords and values.
</p>
</dd>
</dl>

<a name="index-calendar_005fshowdate"></a>
</dd>
<dt><tt>calendar_showdate</tt> [ <tt>-r</tt> ] [ <tt>-f</tt> <var>fmt</var> ] <var>date-spec</var> ...</dt>
<dd><p>The given <var>date-spec</var> is interpreted and the corresponding date and
time printed.  If the initial <var>date-spec</var> begins with a <tt>+</tt> or
<tt>-</tt> it is treated as relative to the current time; <var>date-spec</var>s after
the first are treated as relative to the date calculated so far and
a leading <tt>+</tt> is optional in that case.  This allows one to
use the system as a date calculator.  For example, <tt>calendar_showdate '+1
month, 1st Friday'</tt> shows the date of the first Friday of next month.
</p>
<p>With the option <tt>-r</tt> nothing is printed but the value of the date and
time in seconds since the epoch is stored in the parameter <tt>REPLY</tt>.
</p>
<p>With the option <tt>-f</tt> <var>fmt</var> the given date/time conversion format
is passed to <tt>strftime</tt>; see notes on the <tt>date-format</tt> style below.
</p>
<p>In order to avoid ambiguity with negative relative date specifications,
options must occur in separate words; in other words, <tt>-r</tt> and <tt>-f</tt>
should not be combined in the same word.
</p>
<a name="index-calendar_005fsort"></a>
</dd>
<dt><tt>calendar_sort</tt></dt>
<dd><p>Sorts the calendar file into date and time order.    The old calendar is
left in a file with the suffix <tt>.old</tt>.
</p>
</dd>
</dl>


<hr>
<a name="Glob-qualifiers"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-system-functions" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-System-User-Functions" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Styles" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">23.3.2 Glob qualifiers</h3>

<dl compact="compact">
<dt><tt>age</tt></dt>
<dd><a name="index-age"></a>
<p>The function <tt>age</tt> can be autoloaded and use separately from
the calendar system, although it uses the function <tt>calendar_scandate</tt>
for date formatting.  It requires the <tt>zsh/stat</tt> builtin, but uses
only the builtin <tt>zstat</tt>.
</p>
<p><tt>age</tt> selects files having a given modification time for use
as a glob qualifier.  The format of the date is the same as that
understood by the calendar system, described in
<a href="#Calendar-File-and-Date-Formats">File and Date Formats</a>.
</p>
<p>The function can take one or two arguments, which can be supplied either
directly as command or arguments, or separately as shell parameters.
</p>
<div class="example">
<pre class="example">print *(e:age 2006/10/04 2006/10/09:)
</pre></div>

<p>The example above matches all files modified between the start of those
dates.  The second argument may alternatively be a relative time
introduced by a <tt>+</tt>:
</p>
<div class="example">
<pre class="example">print *(e:age 2006/10/04 +5d:)
</pre></div>

<p>The example above is equivalent to the previous example.
</p>
<p>In addition to the special use of days of the week, <tt>today</tt> and
<tt>yesterday</tt>, times with no date may be specified; these apply to today.
Obviously such uses become problematic around midnight.
</p>
<div class="example">
<pre class="example">print *(e-age 12:00 13:30-)
</pre></div>

<p>The example above shows files modified between 12:00 and 13:00 today.
</p>
<div class="example">
<pre class="example">print *(e:age 2006/10/04:)
</pre></div>

<p>The example above matches all files modified on that date.  If the second
argument is omitted it is taken to be exactly 24 hours after the first
argument (even if the first argument contains a time).
</p>
<div class="example">
<pre class="example">print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
</pre></div>

<p>The example above supplies times.  Note that whitespace within the time and
date specification must be quoted to ensure <tt>age</tt> receives the correct
arguments, hence the use of the additional colon to separate the date and
time.
</p>
<div class="example">
<pre class="example">AGEREF=2006/10/04:10:15
AGEREF2=2006/10/04:10:45
print *(+age)
</pre></div>

<p>This shows the same example before using another form of argument
passing.  The dates and times in the parameters <tt>AGEREF</tt> and <tt>AGEREF2</tt>
stay in effect until unset, but will be overridden if any argument is
passed as an explicit argument to age.  Any explicit argument
causes both parameters to be ignored.
</p>
<p>Instead of an explicit date and time, it&rsquo;s possible to use the
modification time of a file as the date and time for either argument
by introducing the file name with a colon:
</p>
<div class="example">
<pre class="example">print *(e-age :file1-)
</pre></div>

<p>matches all files created on the same day (24 hours starting from
midnight) as <tt>file1</tt>.
</p>
<div class="example">
<pre class="example">print *(e-age :file1 :file2-)
</pre></div>

<p>matches all files modified no earlier than <tt>file1</tt> and
no later than <tt>file2</tt>; precision here is to the nearest second.
</p>
</dd>
<dt><tt>after</tt></dt>
<dt><tt>before</tt></dt>
<dd><a name="index-after"></a>
<a name="index-before"></a>
<p>The functions <tt>after</tt> and <tt>before</tt> are simpler versions of <tt>age</tt>
that take just one argument.  The argument is parsed similarly to an
argument of <tt>age</tt>; if it is not given the variable <tt>AGEREF</tt> is
consulted.  As the names of the functions suggest, a file matches if its
modification time is after or before the time and date specified.  If
a time only is given the date is today.
</p>
<p>The two following examples are therefore equivalent:
</p><div class="example">
<pre class="example">print *(e-after 12:00-)
print *(e-after today:12:00-)
</pre></div>

</dd>
</dl>

<hr>
<a name="Calendar-Styles"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Glob-qualifiers" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Utility-Functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="Styles"></a>
<h2 class="section">23.4 Styles</h2>

<p>The zsh style mechanism using the <tt>zstyle</tt> command is describe in
<a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil Module</a>.  This is the same mechanism
used in the completion system.
</p>
<p>The styles below are all examined in the context
<tt>:datetime:</tt><var>function</var><tt>:</tt>, for example <tt>:datetime:calendar:</tt>.
</p>
<dl compact="compact">
<dd><a name="index-calendar_002dfile"></a>
</dd>
<dt><tt>calendar-file</tt></dt>
<dd><p>The location of the main calendar.  The default is <tt>~/calendar</tt>.
</p>
<a name="index-date_002dformat"></a>
</dd>
<dt><tt>date-format</tt></dt>
<dd><p>A <tt>strftime</tt> format string (see man page strftime(3)) with the zsh
extensions providing various numbers with no leading zero or space
if the number is a single digit as described for the
<tt>%D{</tt><var>string</var><tt>}</tt> prompt format in
<a href="Prompt-Expansion.html#Prompt-Expansion">Prompt Expansion</a>.
</p>
<p>This is used for outputting dates in <tt>calendar</tt>, both to support
the <tt>-v</tt> option and when adding recurring events back to the calendar
file, and in <tt>calendar_showdate</tt> as the final output format.
</p>
<p>If the style is not set, the default used is similar the standard system
format as output by the <tt>date</tt> command (also known as &lsquo;ctime format&rsquo;):
&lsquo;<tt>%a %b %d %H:%M:%S %Z %Y</tt>&rsquo;.
</p>
<a name="index-done_002dfile"></a>
</dd>
<dt><tt>done-file</tt></dt>
<dd><p>The location of the file to which events which have passed are appended.
The default is the calendar file location with the suffix <tt>.done</tt>.
The style may be set to an empty string in which case a &quot;done&quot; file
will not be maintained.
</p>
<a name="index-reformat_002ddate"></a>
</dd>
<dt><tt>reformat-date</tt></dt>
<dd><p>Boolean, used by <tt>calendar_add</tt>.  If it is true, the date and time
of new entries added to the calendar will be reformatted to the format
given by the style <tt>date-format</tt> or its default.  Only the date and
time of the event itself is reformatted; any subsidiary dates and times
such as those associated with repeat and warning times are left alone.
</p>
<a name="index-show_002dprog"></a>
</dd>
<dt><tt>show-prog</tt></dt>
<dd><p>The programme run by <tt>calendar</tt> for showing events.  It will
be passed the start time and stop time of the events requested in seconds
since the epoch followed by the event text.  Note that <tt>calendar -s</tt> uses
a start time and stop time equal to one another to indicate alerts
for specific events.
</p>
<p>The default is the function <tt>calendar_show</tt>.
</p>
<a name="index-warn_002dtime"></a>
</dd>
<dt><tt>warn-time</tt></dt>
<dd><p>The time before an event at which a warning will be displayed, if the
first line of the event does not include the text <tt>EVENT</tt> <var>reltime</var>.
The default is 5 minutes.
</p>
</dd>
</dl>

<hr>
<a name="Calendar-Utility-Functions"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Styles" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Bugs" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="Utility-functions"></a>
<h2 class="section">23.5 Utility functions</h2>

<dl compact="compact">
<dd><a name="index-calendar_005flockfiles"></a>
</dd>
<dt><tt>calendar_lockfiles</tt></dt>
<dd><p>Attempt to lock the files given in the argument.  To prevent
problems with network file locking this is done in an ad hoc fashion
by attempting to create a symbolic link to the file with the name
<var>file</var><tt>.lockfile</tt>.  No other system level functions are used
for locking, i.e. the file can be accessed and modified by any
utility that does not use this mechanism.  In particular, the user is not
prevented from editing the calendar file at the same time unless
<tt>calendar_edit</tt> is used.
</p>
<p>Three attempts are made to lock the file before giving up.  If the module
<tt>zsh/zselect</tt> is available, the times of the attempts are jittered so that
multiple instances of the calling function are unlikely to retry at the
same time.
</p>
<p>The files locked are appended to the array <tt>lockfiles</tt>, which should
be local to the caller.
</p>
<p>If all files were successfully locked, status zero is returned, else status one.
</p>
<p>This function may be used as a general file locking function, although
this will only work if only this mechanism is used to lock files.
</p>
<a name="index-calendar_005fread"></a>
</dd>
<dt><tt>calendar_read</tt></dt>
<dd><p>This is a backend used by various other functions to parse the
calendar file, which is passed as the only argument.  The array
<tt>calendar_entries</tt> is set to the list of events in the file; no
pruning is done except that ampersands are removed from the start of
the line.  Each entry may contain multiple lines.
</p>
<a name="index-calendar_005fscandate"></a>
</dd>
<dt><tt>calendar_scandate</tt></dt>
<dd><p>This is a generic function to parse dates and times that may be
used separately from the calendar system.  The argument is a date
or time specification as described in
<a href="#Calendar-File-and-Date-Formats">File and Date Formats</a>.  The parameter <tt>REPLY</tt>
is set to the number of seconds since the epoch corresponding to that date
or time.  By default, the date and time may occur anywhere within the given
argument.
</p>
<p>Returns status zero if the date and time were successfully parsed,
else one.
</p>
<p>Options:
</p><dl compact="compact">
<dt><tt>-a</tt></dt>
<dd><p>The date and time are anchored to the start of the argument; they
will not be matched if there is preceding text.
</p>
</dd>
<dt><tt>-A</tt></dt>
<dd><p>The date and time are anchored to both the start and end of the argument;
they will not be matched if the is any other text in the argument.
</p>
</dd>
<dt><tt>-d</tt></dt>
<dd><p>Enable additional debugging output.
</p>
</dd>
<dt><tt>-m</tt></dt>
<dd><p>Minus.  When <tt>-R</tt> <var>anchor_time</var> is also given the relative time is
calculated backwards from <var>anchor_time</var>.
</p>
</dd>
<dt><tt>-r</tt></dt>
<dd><p>The argument passed is to be parsed as a relative time.
</p>
</dd>
<dt><tt>-R</tt> <var>anchor_time</var></dt>
<dd><p>The argument passed is to be parsed as a relative time.  The time is
relative to <var>anchor_time</var>, a time in seconds since the epoch,
and the returned value is the absolute time corresponding to advancing
<var>anchor_time</var> by the relative time given.
This allows lengths of months to be correctly taken into account.  If
the final day does not exist in the given month, the last day of the
final month is given.  For example, if the anchor time is during 31st
January 2007 and the relative time is 1 month, the final time is the
same time of day during 28th February 2007.
</p>
</dd>
<dt><tt>-s</tt></dt>
<dd><p>In addition to setting <tt>REPLY</tt>, set <tt>REPLY2</tt> to the remainder of
the argument after the date and time have been stripped.  This is
empty if the option <tt>-A</tt> was given.
</p>
</dd>
<dt><tt>-t</tt></dt>
<dd><p>Allow a time with no date specification.  The date is assumed to be
today.  The behaviour is unspecified if the iron tongue of midnight
is tolling twelve.
</p>
</dd>
</dl>

<a name="index-calendar_005fshow"></a>
</dd>
<dt><tt>calendar_show</tt></dt>
<dd><p>The function used by default to display events.  It accepts a start time
and end time for events, both in epoch seconds, and an event description.
</p>
<p>The event is always printed to standard output.  If the command line editor
is active (which will usually be the case) the command line will be
redisplayed after the output.
</p>
<p>If the parameter <tt>DISPLAY</tt> is set and the start and end times are
the same (indicating a scheduled event), the function uses the
command <tt>xmessage</tt> to display a window with the event details.
</p>
</dd>
</dl>

<hr>
<a name="Calendar-Bugs"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Utility-Functions" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>

<a name="Bugs"></a>
<h2 class="section">23.6 Bugs</h2>

<p>As the system is based entirely on shell functions (with a little support
from the <tt>zsh/datetime</tt> module) the mechanisms used are not as robust as
those provided by a dedicated calendar utility.  Consequently the user
should not rely on the shell for vital alerts.
</p>
<p>There is no <tt>calendar_delete</tt> function.
</p>
<p>There is no localization support for dates and times, nor any support
for the use of time zones.
</p>
<p>Relative periods of months and years do not take into account the variable
number of days.
</p>
<p>The <tt>calendar_show</tt> function is currently hardwired to use <tt>xmessage</tt>
for displaying alerts on X Window System displays.  This should be
configurable and ideally integrate better with the desktop.
</p>
<p><tt>calendar_lockfiles</tt> hangs the shell while waiting for a lock on a file.
If called from a scheduled task, it should instead reschedule the event
that caused it.
</p><hr>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calendar-Function-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="TCP-Function-System.html#TCP-Function-System" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p><font size="-1">
  This document was generated on <em>February 7, 2016</em> using <a href="http://www.gnu.org/software/texinfo/"><em>texi2any</em></a>.
</font></p>

<font size="-1">Zsh version 5.1.1, released on September 11, 2015.</font>
</body>
</html>