97 The many uses of gcal
Friday 19th October, 2007
gcal is a remarkable console-based program.
- It can be used to print calendar information, much like
cal, but with much more flexibility. - It can display holiday information for over 300 different countries and states.
- It can display astronomical information such as sunrise, sunset, the current phase of the moon and much more.
- It can also be used as a diary or personal reminder.
- It can print the current date and time. (No, really! :) )
- It can be used to display the start and stop of daylight saving.
I'll be providing examples of how to use gcal in all these ways. Bear in mind that this article just scratches the surface with regard to what gcal can actually be used for. You are limited by your imagination!
- basic options
- holidays
- astronomical information
- resource files
- tidying up the output
- more resource file tips
- searching
- customisation
- useful links
basic options
gcal has many options. Here are a few of the basic ones.
$ gcal
October 2007
Su Mo Tu We Th Fr Sa
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
Just like cal, nothing special, however you can also display the week number:
$ gcal -K
October 2007
Su Mo Tu We Th Fr Sa CW
1 2 3 4 5 6 39
7 8 9 10 11 12 13 40
14 15 16 17 18 19 20 41
21 22 23 24 25 26 27 42
28 29 30 31 43
Or, instead of the day of the month, how about the day of the year?
$ gcal -j
October 2007
Sun Mon Tue Wed Thu Fri Sat
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
Or even both at once!
$ gcal -jb
October 2007
Sun Mon Tue Wed Thu Fri Sat
1(274) 2(275) 3(276) 4(277) 5(278) 6(279)
7(280) 8(281) 9(282) 10(283) 11(284) 12(285) 13(286)
14(287) 15(288) 16(289) 17(290) 18(291) 19(292) 20(293)
21(294) 22(295) 23(296) 24(297) 25(298) 26(299) 27(300)
28(301) 29(302) 30(303) 31(304)
cal -3 is a useful option which displays 3 months at a time, and there is a gcal equivalent:
$ gcal .
2007
September October November
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 1 2 3 4 5 6 1 2 3
2 3 4 5 6 7 8 7 8 9 10 11 12 13 4 5 6 7 8 9 10
9 10 11 12 13 14 15 14 15 16 17 18 19 20 11 12 13 14 15 16 17
16 17 18 19 20 21 22 21 22 23 24 25 26 27 18 19 20 21 22 23 24
23 24 25 26 27 28 29 28 29 30 31 25 26 27 28 29 30
30
You can also use the options used to show week numbers and day of the year too. (Apply the option before the full stop, e.g. gcal -K .)
When displaying years (equivalent to cal -y), you can choose the layout. The default is four rows (blocks) of three months, but you can change this with the -b flag, e.g:
$ gcal -b 6 2007
2007
January February
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 3 4 5 6 1 2 3
7 8 9 10 11 12 13 4 5 6 7 8 9 10
14 15 16 17 18 19 20 11 12 13 14 15 16 17
21 22 23 24 25 26 27 18 19 20 21 22 23 24
28 29 30 31 25 26 27 28
...
(output trimmed to save space)
...
September October
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 1 2 3 4 5 6
2 3 4 5 6 7 8 7 8 9 10 11 12 13
9 10 11 12 13 14 15 14 15 16 17 18 19 20
16 17 18 19 20 21 22 21 22 23 24 25 26 27
23 24 25 26 27 28 29 28 29 30 31
30
November December
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 3 1
4 5 6 7 8 9 10 2 3 4 5 6 7 8
11 12 13 14 15 16 17 9 10 11 12 13 14 15
18 19 20 21 22 23 24 16 17 18 19 20 21 22
25 26 27 28 29 30 23 24 25 26 27 28 29
30 31
holidays
To display the holidays for England, Wales and the Isle of Man for the whole of the current year, use:
$ gcal -q GB_EN -n
Eternal holiday list: The year 2007 is NO leap year New Year's Day (GB_EN) + Mon, 1st Jan 2007 = -290 days St David's Day (GB_EN) - Thu, 1st Mar 2007 = -231 days Mother's Day (GB_EN) - Sun, 18th Mar 2007 = -214 days Mary's Annunciation Day (GB_EN) - Sun, 25th Mar 2007 = -207 days Good Friday (GB_EN) + Fri, 6th Apr 2007 = -195 days Beginning of Financial Year (GB_EN) - Sat, 7th Apr 2007 = -194 days Easter Sunday (GB_EN) + Sun, 8th Apr 2007 = -193 days Easter Monday (GB_EN) + Mon, 9th Apr 2007 = -192 days Swallow Day (GB_EN) - Sun, 15th Apr 2007 = -186 days St George's Day (GB_EN) - Mon, 23rd Apr 2007 = -178 days May Day (GB_EN) + Mon, 7th May 2007 = -164 days Liberation Day (GB_EN) * Wed, 9th May 2007 = -162 days Bank Holiday (GB_EN) + Mon, 28th May 2007 = -143 days The Queen's Birthday (GB_EN) - Sat, 9th Jun 2007 = -131 days Father's Day (GB_EN) - Sun, 17th Jun 2007 = -123 days Tynwald Day (GB_EN) * Thu, 5th Jul 2007 = -105 days Grotto Day (GB_EN) - Wed, 25th Jul 2007 = -85 days Bank Holiday (GB_EN) + Mon, 27th Aug 2007 = -52 days St Edward's Day (GB_EN) - Sat, 13th Oct 2007 = -5 days Halloween (GB_EN) - Wed, 31st Oct 2007 = +13 days Guy Fawke's Day (GB_EN) - Mon, 5th Nov 2007 = +18 days Christmas Eve (GB_EN) - Mon, 24th Dec 2007 = +67 days Christmas Day (GB_EN) + Tue, 25th Dec 2007 = +68 days Boxing Day (GB_EN) + Wed, 26th Dec 2007 = +69 days Sylvester/New Year's Eve (GB_EN) - Mon, 31st Dec 2007 = +74 days
Bank Holidays are in bold.
If you want to display the holidays for your country, you can find a complete list of available country codes in the online gcal documentation.
If that is information overload, you can display a particular month (e.g. October 2007) like so:
$ gcal -q GB_EN -n 10 2007
October 2007
Su Mo Tu We Th Fr Sa
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
Eternal holiday list:
St Edward's Day (GB_EN) - Sat, 13th Oct 2007 = -5 days
Halloween (GB_EN) - Wed, 31st Oct 2007 = +13 days
And now let's go ethnic:
$ gcal --chinese-holidays -n
Eternal holiday list: The year 2007 is NO leap year Chinese New Year's Eve (Chi) - Sat, 17th Feb 2007 = -243 days Chinese New Year's Day 4644-0 (Chi) - Sun, 18th Feb 2007 = -242 days Cycle 78/24-00 Ding-Hai/Pig (Chi) - Sun, 18th Feb 2007 = -242 days Chinese New Year's Day (Chi) - Mon, 19th Feb 2007 = -241 days Chinese New Year's Day (Chi) - Tue, 20th Feb 2007 = -240 days Chinese New Year's Day (Chi) - Wed, 21st Feb 2007 = -239 days Chinese New Year's Day (Chi) - Thu, 22nd Feb 2007 = -238 days Chinese New Year's Day (Chi) - Fri, 23rd Feb 2007 = -237 days Chinese New Year's Day (Chi) - Sat, 24th Feb 2007 = -236 days Chinese New Year's Day (Chi) - Sun, 25th Feb 2007 = -235 days Chinese New Year's Day (Chi) - Mon, 26th Feb 2007 = -234 days Chinese New Year's Day (Chi) - Tue, 27th Feb 2007 = -233 days Chinese New Year's Day (Chi) - Wed, 28th Feb 2007 = -232 days Chinese New Year's Day (Chi) - Thu, 1st Mar 2007 = -231 days Chinese New Year's Day (Chi) - Fri, 2nd Mar 2007 = -230 days Chinese New Year's Day (Chi) - Sat, 3rd Mar 2007 = -229 days Chinese New Year's Day (Chi) - Sun, 4th Mar 2007 = -228 days Festival of Lanterns (Chi) - Sun, 4th Mar 2007 = -228 days Lao Tze's Birthday (Chi) - Mon, 2nd Apr 2007 = -199 days Tomb-Sweeping Day (Chi) - Thu, 5th Apr 2007 = -196 days Buddha's Birthday (Chi) - Thu, 24th May 2007 = -147 days Dragon Boat Festival (Chi) - Tue, 19th Jun 2007 = -121 days Star Festival (Chi) - Sun, 19th Aug 2007 = -60 days Mid-Autumn Festival (Chi) - Tue, 25th Sep 2007 = -23 days Confucius' Birthday (Chi) - Sun, 7th Oct 2007 = -11 days Double-9 Day (Chi) - Fri, 19th Oct 2007 = +1 day Bodhidharma's Birthday (Chi) - Thu, 15th Nov 2007 = +28 days Solstice Day (Chi) - Sat, 22nd Dec 2007 = +65 days
Note that you can combine lists, so gcal -q GB_EN --chinese-holidays -n would output a combined list (in proper date order) of UK holidays and Chinese festivals.
There are a bewildering amount of calendar options.
astronomical information
gcal even offers the ability to check sunrise, sunset, moonrise, moonset, even the current phase of the moon, and more, much, much more.
I'll demonstrate just a couple of these options, otherwise this article will never end. I'll also introduce a vital component of serious gcal use, a gcal resource file.
You'll need to know your location in latitude and longitude, plus your height above sea level in meters. You might have to google it. With the latitude and longitude, I have used degrees with decimal degrees as opposed to degrees, arcminutes, and arcseconds.
The default gcal resource file location is ~/.gcalrc, but this is a little limiting. Instead, create a directory named ~/.gcal and we'll put all our resource files in there.
After that, create a resource file named ~/.gcal/astronomical and edit it as follows.
; ~/.gcal/astronomical ; ;my latitude 51.7537N ;my longitude -0.4748E ;my height above sea level 60m (guesstimate) 0 Sunrise is at %25o+51.75-000.47+60 0 Sunset is at %25s+51.75-000.47+60 0 Moon phase %25O 0 %25Z ;
Save the file and run the following command:
$ gcal --resource-file=$HOME/.gcal/astronomical -H no -ox
Thu, 18th Oct 2007: ( @@@@@@@
( @@@@@@@@@@
( @@@@@@@@@@@@
( @@@@@@@@@@@@@
( @@@@@@@@@@@@@@
( @@@@@@@@@@@@@@@
( @@@@@@@@@@@@@@@
( @@@@@@@@@@@@@@
( @@@@@@@@@@@@@
( @@@@@@@@@@@@@
( @@@@@@@@@@
( @@@@@@@
Moon phase 43%25+
Sunrise is at 07:29
Sunset is at 18:01
Within ~/.gcal/astronomical, the lines beginning with a semicolon are comments, and the lines beginning with a 0 are actions for gcal. 0 is shorthand for 00000000 which stands for "run this action every day of every month of every year", in the format yyyymmdd. The "action" is the part of the entry which follows the 0; it may be just a text entry to be printed out, such as "check your e-mails", or it may contain more complex calulations for gcal to run, such as determining when sunrise is.
These functions may or may not be useful to you, however bear in mind that gcal was not designed as a high precision astronomical calculation tool.
resource files
For serious use of gcal, you need to use resource files.
Using a resource file to flag dates which repeat is "mostly easy". :) If you have a look at some of the examples below, you'll soon pick up how to easily set up both unique and repeat events. However, you should be aware that not all resource file entries are equal!
There are different 'levels' of resource file entry, which can be viewed in more detail in the coding scheme tables from the online documentation. These different levels allow you some flexibility in prioritising resource file entries, depending on how you use gcal.
What these differing means of making resource file entries allow you to do is to make entries which are either printed all the time, or only on certain occasions.
For example, if you have a weekly event, such as a regular meeting, you may not want to be reminded of it every time you consult your diary.
The way you enter the reminder into your resource file combined with the way you use gcal will allow you to just be reminded of your regular meeting on the day it occurs, or maybe also the day before.
I know this sounds confusing, so let me provide some examples to explain this further.
"low priority" resource file entries
For want of a better term, I'm going to call these "low priority" resource file entries.
In other words, these diary entries will only appear if gcal is invoked in a certain way, plus you have specify the resource file(s) you are querying (with the -f flag as we'll see later).
Create a new resource file, which we'll call ~/.gcal/low.
(This is as good a place as any to note that I've had issues with gcal resource file names which contain an underscore.
Don't use underscores in your gcal resource file names.)
; ~/.gcal/low ; ; comments begin with a semicolon ; 0 Print this message every day of every month of every year (low) 00000000 Something else which happens every day (low) ; 000000Thu Every Thursday (low) 000010Fri Every Friday in October (low) 200700Thu Every Thursday in 2007 (low) 200710Fri Every Friday in October 2007 (low) ;
The syntax is fairly simple. Dates are entered in a YYYYMMDD format, with a zeroed field representing all available years/months/days. Therefore 00000000 represents every day of every month of every year, with a single 0 being shorthand for the same.
"high priority" resource file entries
Now we'll create a seperate resource file for "high priority" entries. These diary entries will appear no matter how you invoke gcal, as long as you specify the resource file(s) concerned.
You can effectively query as many resource files as you want.
; ~/.gcal/high ; 0*d1#999 Every day of every year (high) 0*d1Fri#99Fri.7 %25i0000Oct#0000Nov Every Friday in October and November (high) 0*d1Thu#99Thu.7 %25i0000Oct#0000Nov Every Thursday in October and November (high) 000010thu3 3rd Thursday in Oct (high) 20071019 19th October 2007 (high) ;
The syntax here here is slightly more complex. 0*d1#999 literally means "days 1-999 of every year" which is effectively, every day of every year.
0*d1Fri#99Fri.7 literally means "The first Friday to the 99th Friday of every year" which is effectively, every Friday of every year. I'm not sure about the reasoning behind the .7 (forcing every seven days, maybe?), but it is required (you can try it without :) ).
%25i0000Oct#0000Nov qualifies the period acted upon by restricting the start year to any year, and the start month to Oct, and the end year to any year, and the end month to Nov.
You can read more about inclusive date periods in the gcal online documentation.
Now we'll print today's diary entries from ~/.gcal/low and ~/.gcal/high :
$ gcal -c -f /home/rob/.gcal/low+/home/rob/.gcal/high -u --date-format="gb"
Fixed date list: Thu, 18th Oct 2007: 3rd Thursday in Oct (high) Thu, 18th Oct 2007: Every Thursday (low) Thu, 18th Oct 2007: Every Thursday in 2007 (low) Thu, 18th Oct 2007: Every Thursday in October and November (high) Thu, 18th Oct 2007: Every day of every year (high) Thu, 18th Oct 2007: Print this message every day of every month of every year (low) Thu, 18th Oct 2007: Something else which happens every day (low)
The -c flag makes gcal display the fixed date messages for today.
And now tomorrow's entries (by way of comparison):
$ gcal -ct -f /home/rob/.gcal/low+/home/rob/.gcal/high -u --date-format="gb"
Fixed date list: Fri, 19th Oct 2007: 19th October 2007 (high) Fri, 19th Oct 2007: Every Friday in October (low) Fri, 19th Oct 2007: Every Friday in October 2007 (low) Fri, 19th Oct 2007: Every Friday in October and November (high) Fri, 19th Oct 2007: Every day of every year (high) Fri, 19th Oct 2007: Print this message every day of every month of every year (low) Fri, 19th Oct 2007: Something else which happens every day (low)
The -ct flag makes gcal display the fixed date messages for tomorrow. You can check for today and tomorrow with the flag -cdt.
Now we'll check a week ahead.
$ gcal -cdl@t7 -f /home/rob/.gcal/low+/home/rob/.gcal/high -u --date-format="gb"
Fixed date list: Thu, 18th Oct 2007: 3rd Thursday in Oct (high) Thu, 18th Oct 2007: Every Thursday in October and November (high) Thu, 18th Oct 2007: Every day of every year (high) Fri, 19th Oct 2007: 19th October 2007 (high) Fri, 19th Oct 2007: Every Friday in October and November (high) Fri, 19th Oct 2007: Every day of every year (high) Sat, 20th Oct 2007: Every day of every year (high) Sun, 21st Oct 2007: Every day of every year (high) Mon, 22nd Oct 2007: Every day of every year (high) Tue, 23rd Oct 2007: Every day of every year (high) Wed, 24th Oct 2007: Every day of every year (high) Thu, 25th Oct 2007: Every Thursday in October and November (high) Thu, 25th Oct 2007: Every day of every year (high)
The -cdl@txx flag makes gcal display the fixed date messages for today (-d), and a list of the fixed date messages starting from tomorrow (l@t), and ending xx days after today's date. There seems to be a limit of 83 days on lists of this sort.
You'll notice that in list mode (l@), where lists of periods are generated, seven days in this case, only the entries from ~/.gcal/high have been printed.
While it's possible to force gcal to print sequential single day entries without using list mode (you'd have to use a for loop), it's not really the way gcal was intended to be used, and is slower since you would be running multiple instances of gcal. Plus you're removing the option of prioritising resource file entries, just for the sake of slightly easier resource file syntax.
tidying up the output
fixed date list title
The line which says Fixed date list: can be edited (perhaps replaced with today's date) or removed completely.
To replace Fixed date list: with today's date, you could use the following flag:
--heading-text="%253%25>1*K , %25>02&*D %25U %25Y %254"
To remove Fixed date list: completely, place an x flag after the c flag, something like this:
$ gcal -cxdl@t7 -f /home/rob/.gcal/low+/home/rob/.gcal/high -u --date-format="gb"
You can find information on how to format the --heading-text field here.
highlight today's date
Notice is that today's entries have the date part "highlighted" in reverse video. It's useful, a bit untidy, but it can be modified to something more aesthetically pleasing. We'll need to change two settings, the date format, and the highlighting sequence.
The default date format for GB is:
%25<3#K, %251%25>2&*D%252 %25<3#U %25>04*Y
The parts I have in red, %251 and %252 determine where the highlighting begins and ends.
We can change the highlighting sequence with the -H flag. The filed which follows -H consists of 4 parts, seperated by colons. These are: actual_day_start:actual_day_end:holiday_start:holiday_end. I don't feel a particular need to highlight holidays, and I prefer bold/highlight to reverse video:
-H '^[[1m:^[[0m:^[[0m:^[[0m'
ANSI sequences work fine. Note that ^[ represents an ANSI escape sequence. Ctrl-v Esc should create this in bash or vim if you're writing a script for gcal.
So now if we add the relevant flags to our gcal command line, we get something which is becoming increasingly unwieldy:
gcal -cdl@t7 -f /home/rob/.gcal/low+/home/rob/.gcal/high -u --heading-text="%253%25>1*K , %25>02&*D %25U %25Y %254" --date-format='%251%25<3#K, %25>2&*D %25<3#U %25>04*Y%252' -H '^[[1m:^[[0m:^[[0m:^[[0m'
Scripts are definitely the way to go.
There are three default date format settings. These are: de, us, and gb. Unsurprisingly, the date format can be heavily personalised and you can read
more about the --date-format flag in the online docs.
remove repeating dates
Next, note how the same date is repeated for each diary entry which occurs on that day. This can be removed so that only one date is printed by using the -o option.
spacing out entries
We can also space out entries by grouping dates together with the -g flag.
add holiday entries
If we now add our holiday entries, we should have the beginnings of a useful command-line diary. I need to add the -e flag to enable holiday output, and -q GB_EN to specify my country code.
$ gcal -cdeol@t7 -f /home/rob/.gcal/low+/home/rob/.gcal/high -u -g -q GB_EN --heading-text="%253%25>1*K , %25>02&*D %25U %25Y %254" --date-format='%251%25<3#K, %25>2&*D %25<3#U %25>04*Y%252' -H '^[[1m:^[[0m:^[[0m:^[[0m'
Thursday, 18th October 2007
Thu, 18th Oct 2007: 3rd Thursday in Oct (high)
Every Thursday in October and November (high)
Every day of every year (high)
Fri, 19th Oct 2007: 19th October 2007 (high)
Every Friday in October and November (high)
Every day of every year (high)
Sat, 20th Oct 2007: Every day of every year (high)
Sun, 21st Oct 2007: Every day of every year (high)
Mon, 22nd Oct 2007: Every day of every year (high)
Tue, 23rd Oct 2007: Every day of every year (high)
Wed, 24th Oct 2007: Every day of every year (high)
Thu, 25th Oct 2007: Every Thursday in October and November (high)
Every day of every year (high)
more resource file tips
~/.gcal/low and ~/.gcal/high have served their purpose now. They aren't particularly intuitive names for resource files. The following examples will be using two new resource files, ~/.gcal/regular, for regularly repeating events such as birthdays, anniversaries and the like, and ~/.gcal/diary for one-off events such as appointments and other reminders.
In addition, having different levels of resource file entry can be confusing. Thankfully, my life isn't that complex that I can really make use of it, so for the remaining examples, I'll be using "high" priority examples only. If you're really interested in the different coding schemes for resource file entries, and which flags applied to gcal will display them, there is a section in the online gcal documentation which explains this in more detail.
Since you aren't restricted (within reason) as to the number of resource files you can query at any one time, you could create extra resource files, such as one for work or business-related matters, one (or more) for your getting things done reminders, one for friends, etc. You are limited by your imagination, and the number of resource files you actually want to maintain.
In the following examples, the command which I'll be running will be:
$ gcal -cdeol@t14 -f /home/rob/.gcal/diary+/home/rob/.gcal/regular -u -g -q GB_EN --heading-text="%251%25>1*K , %25>02&*D %25U %25Y %252" --date-format='%251%25<3#K, %25>2&*D %25<3#U %25>04*Y%252' -H '^[[1m:^[[0m:^[[0m:^[[0m'
So to recap, we'll now be listing entries
- for the next 14 days
- from the resource files
~/.gcal/diaryand~/.gcal/regular - we'll include GB_EN holidays
- we'll change the heading text to today's date, format weekday, date month year, which will be highlighted (everything between %251 and %252)
- the date format for entries will be weekday(first three chars), date month(first three chars) year:, and the whole date will be highlighted if it's today only.
(It's hard to see, but there are two spaces either side of %25U in the --heading-text flag. I found this was required, you may not.)
birthdays, anniversaries, etc
In addition to the usual entry for birthdays, you can add a little extra information. Let's assume our mutual friend Fred Bloggs (good old Fred) was born in 1964, on October 21st:
; ~/.gcal/regular ; ; birthdays 00001021 Fred's %25>1&*B1964 birthday
(I've found that two spaces are required after the birth year entry. ymmv.)
And I'll get the following output:
Thursday, 18th October 2007 Sun, 21st Oct 2007: Fred's 43rd birthday Wed, 31st Oct 2007: Halloween (GB_EN)
print the time
If we have to take the bicycle to be repaired at 11am on Friday 19th, it may be useful to print the current time:
; ~/.gcal/diary ; ; 2007 00001019 11:00 Bicycle to be repaired. Time now is %25t
Which produces:
Thursday, 18th October 2007 Fri, 19th Oct 2007: 11:00 Bicycle to be repaired. Time now is 21:57 Sun, 21st Oct 2007: Fred's 43rd birthday Wed, 31st Oct 2007: Halloween (GB_EN)
daylight saving
Daylight saving is easy to flag up using gcal:
; ~/.gcal/regular ; ; birthdays 00001021 Fred's %25>1&*B1964 birthday ; ; GMT/BST ; BST starts the last Sunday in March 000003Sun9 British Summer Time starts (clocks go forward) ; GMT starts the last Sunday in October 000010Sun9 British Summer Time ends (clocks go back)
which provides:
Thursday, 18th October 2007 Fri, 19th Oct 2007: 11:00 Bicycle to be repaired. Time now is 22:04 Sun, 21st Oct 2007: Fred's 43rd birthday Sun, 28th Oct 2007: British Summer Time ends (clocks go back) Wed, 31st Oct 2007: Halloween (GB_EN)
I understand that the EU has standardised it's daylight saving times, so the above should work throughout the EU. Visit Merlyn - Summer Time - J R Stockton for advice on calculating daylight saving for North America and other countries.
searching
You can also search your resource files for entries. To do so, use the -I <search_pattern> flag. To make the search case-insensitive, also use the --ignore-case flag. For instance, if I wanted to search for "bicycle" (how convenient) in the next 14 days' entries:
$ gcal -cdeol@t14 -f /home/rob/.gcal/diary+/home/rob/.gcal/regular -u -g -q GB_EN --heading-text="%251%25>1*K , %25>02&*D %25U %25Y %252" --date-format='%251%25<3#K, %25>2&*D %25<3#U %25>04*Y%252' -H '^[[1m:^[[0m:^[[0m:^[[0m' -I bicycle --ignore-case
Thursday, 18th October 2007 Fri, 19th Oct 2007: 11:00 Bicycle to be repaired. Time now is 22:16
This search facility will work for holiday entries too, so you could search for "halloween".
customisation
I do like to tinker with my scripts, customising the output (you've got to love sed!), and when I run my personal gcal diary script using the two resource files we've created above
(~/.gcal/diary and ~/.gcal/regular), I get the following (I prefer to use a term with a dark background):
Thursday, 18th October 2007 Tomorrow 11:00 Bicycle to be repaired. Time now is 22:24 Sun 21/10/2007 Fred's 43rd birthday Sun 28/10/2007 British Summer Time ends (clocks go back) Wed 31/10/2007 Halloween (GB_EN)
This script is provided under GPLv3. Its current incarnation (it changes every now and again) is available, for those who are interested, here. It's a little messy but you're welcome to have a look/borrow/use.
Currently, the script is invoked from ~/.bashrc the first time I open a terminal (i.e. opening subsequent terminals do not run the script), and each time I check my mail.
I hope this has been a helpful introduction to gcal. It's really just touching the surface of the program, there's so much depth to it. If you have your own tips, or different ways of using gcal, (particularly in a "getting things done" environment) I'd be interested to hear about them.
Useful links
Merlyn - Summer Time - J R Stockton (used to calculate BST/GMT/DST dates)