1This is README for the GNU Gcal package.
2
3The Name of the Game
4====================
5
6This file briefly informs about the major features of Gcal, the GNU
7Gregorian calendar program. Gcal is a program for calculating and
8printing calendars. Gcal displays hybrid and proleptic Julian and
9Gregorian calendar sheets, respectively, for one month, three months or
10a whole year. It also displays eternal holiday lists for many
11countries around the globe, and features a very powerful creation of
12fixed date lists that can be used for reminding purposes. Gcal can
13calculate various astronomical data and times of the Sun and the Moon
14for at pleasure any location, precisely enough for most civil purposes.
15Gcal supports some other calendar systems, for example the Chinese and
16Japanese calendar, the Hebrew calendar and the civil Islamic calendar,
17too.
18
19The Advantages of `gcal'
20========================
21
22Its main advantages over BSD-`cal' and `calendar' are:
23
24 * Some special calendar sheet formats.
25
26 * Calendar sheets can be provided with week numbers.
27
28 * Variable number of year calendar sheet blocks.
29
30 * Adjustable ordering of displayed dates.
31
32 * Adjustable period of Gregorian Reformation.
33
34 * Proleptic Julian and Gregorian calendars.
35
36 * Adjustable highlighting of holidays and actual day.
37
38 * Variable starting day of week.
39
40 * Output of day-of-year numbers and concatenated day and day-of-year
41 numbers.
42
43 * Allows user-defined ordering of the date elements.
44
45 * Output of fiscal years.
46
47 * Output of lists or ranges of months or years.
48
49 * Sorted output of selectable country/territory specific eternal
50 holiday lists (mostly complete) for nearly *all* countries around
51 the globe, which are generated automatically.
52
53 * Sorted output of Christian Western churches calendar holidays,
54 Orthodox Christian Eastern churches old and new calendar holidays,
55 Hebrew calendar holidays, Islamic civil calendar holidays (since
56 AD 622), Persian "Jalaali" calendar holidays, Chinese and Japanese
57 calendar holidays (since AD 1645), more "other" calendar system
58 holidays, multicultural New Year's Days, and start of "other"
59 calendar system months, which are also generated automatically.
60
61 * Sorted output of fixed date lists which can be defined and created
62 in a highly flexible manner.
63
64 * Allows filtration of fixed dates by using regular expressions and
65 other built-in methods.
66
67 * Allows the use of date and text variables and basic operations on
68 them.
69
70 * Some gimmicks like solar and lunar eclipse time, sunrise/sunset
71 plus a lot of other Sun based data and times, Moon phase, Full and
72 New Moon time, moonrise/moonset plus a lot of other Moon based
73 data and times, zodiacal markers, equinox and solstice, air line
74 distance between two geographic point locations plus course
75 angles, biorhythm et cetera...
76
77 * Fixed dates can be stored in several files.
78
79 * Nearly unlimited nesting level of include files.
80
81 * Nearly unlimited internal text and table lengths.
82
83 * Default options can be stored in the `GCAL' environment variable.
84
85 * Options and commands stored in response files can be preloaded.
86
87 * Uses either an external pager or a simple built-in pager.
88
89 * Detailed Texinfo reference manual.
90
91 * German, English and American program version by default.
92
93 * Supports various computer platforms.
94
95 * GNU `gettext' internationalization technology, which allows the
96 use of message catalogs for most native languages.
97
98 * GNU `autoconf'(iguration) installation technology.
99
100 * Supports both UN*X short-style options and GNU long-style options.
101
102System Requirements
103===================
104
105Computer:
106 MS-DOS PC, OS/2 PC, Linux PC, Acorn, Atari ST, Amiga, Vax, most
107 UN*X Workstations, perhaps some Mainframes
108
109Compiler:
110 Any? [ANSI] C compiler (GCC, TCC, BCC, MSC, ZTC, WCC, XLC, []CC...)
111
112RAM:
113 Depending on compilation flags, operating system and compiler used,
114 either less than 480 KByte load size or more than this value.
115
116Hard disk:
117 None
118
119Graphics adapter:
120 None
121
122Device driver:
123 [n]`ansi.sys'/ansi-terminal recommended, but not essential
124
125Files you might look into
126=========================
127
128 * Read the `ATTENTION' file! It informs about all changed `%?'...
129 special texts processed by Gcal in the text part of a Gcal
130 resource file line and about other incompatibilities to previous
131 Gcal versions. Keep in mind that this Gcal is designed to
132 (inter)act on the recent data base (resource, response and shell
133 script files) as distributed here, and that it probably fails if it
134 accesses such a data base of former versions that is still not
135 updated.
136
137 * Some planned features which are not supported yet are listed in the
138 `TODO' file. Here is a blurb from it:
139
140 I'm looking for volunteers who create a graphical front end
141 to the `gcal' back end. If you are interested in working out
142 such a front end or you have already created one (native X11
143 and/or Tcl/Tk, Motif, DOZE-Win [NT], WIN 95 or 98 or 2000,
144 OS/2 PM, Apple...), please contact me!
145
146 Some extended ideas could be part of such a user surface,
147 like formatting of output for different printers, output
148 converted to Postscript/[La]TeX, better time management of
149 fixed dates...
150
151 * See `NEWS' for a summary of user-visible changes since version
152 0.28.
153
154 * See `HISTORY' for a complete summary of changes.
155
156 * See `INSTALL' for compilation and installation instructions.
157 Some answers to frequently asked questions are given in the
158 file `INSTALL', please read it!
159
160 * And see the file `systems/README' for some hints how to compile
161 Gcal on some special machines and operating systems.
162
163 * A list of all known bugs can be found in the `BUGS' file.
164
165 * And a list of internal limitations can be found in the
166 `LIMITATIONS' file.
167
168 * See the file `data/README' for some details to the enclosed
169 reminder respectively appointment files and how to install them.
170
171 * Inspect `MANIFEST' for a list of all files which are part of this
172 distribution.
173
174 * Many thanks to those who provided me with bug reports and feedback.
175 See the `THANKS' and `HISTORY' files for more details.
176
177 * See `ABOUT-NLS' for notes on the Free Translation Project. Some
178 parts of this file which are important for a proper installation
179 of Gcal are cited in one of the next sections.
180
181 * You can find some useful wrapper scripts in the `misc/'
182 subdirectory, see `misc/README' for more details. By the way, if
183 you have designed useful wrapper scripts which solve tasks of your
184 personal interest, and you think they could also be useful to
185 others, feel free to share them with the rest of the world.
186 Simply send your files to my eMail address and I will add them to
187 the next release of Gcal.
188
189 * The ISO 3166 country code table, the ISO 639 language code table
190 and the ISO 6709 standard representation for geographic point
191 locations can be found in the `doc/' subdirectory.
192
193 * And see the `doc/GREG-REFORM' file, which shows a chronology of
194 introduction of the Gregorian calendar (some selected countries
195 only).
196
197 * I also recommend to have a look into the `doc/calendar.faq' text
198 worked out by Claus Tondering <claus@tondering.dk>, which is a
199 very good summary of the most common calendar algorithms and
200 principles.
201
202 * You can find all example resource files from the Gcal Texinfo
203 reference manual in the `doc/LL/examples/' subdirectories, where LL
204 is the ISO 639 two-letter code of your native language.
205
206Please read Gcal's Texinfo reference manual first for getting a deeper
207impression of the defaults and modes of operation of Gcal before you
208bomb me with questions which I have already answered there! Your
209native language Texinfo documentation (if already worked out) can be
210found in the `doc/LL/' subdirectory, where LL is the ISO 639 two-letter
211code of your native language. Thank you!
212
213How to get Termcap or Ncurses
214=============================
215
216This program does not require Termcap or Ncurses, but takes advantage
217of it when it is available. You may want to get and install GNU
218`termcap' (still? `termcap-1.3.tar.gz') first from
219<ftp://ftp.gnu.org/gnu/termcap/> -- respectively `ncurses' (still?
220`ncurses-4.2.tar.gz') first from <ftp://ftp.gnu.org/gnu/ncurses/>.
221
222Configuration Options
223=====================
224
225If you use the GNU `autoconf' technology, you can enable/disable some
226Gcal specific package options. Simply run the `configure' script with
227one or more of these arguments:
228
229 `--enable-easc'
230 Use extended ASCII character set.
231
232 `--disable-cc-holidays'
233 Do not use all available country specific holidays, only use
234 the top 20 countries instead.
235
236 `--disable-hls'
237 Do not use highlighting sequences respectively marking
238 characters.
239
240 `--disable-pager'
241 Do not use external or simple internal pager feature.
242
243 `--disable-rc'
244 Do not use fixed date feature.
245
246 `--disable-term'
247 Do not use `libncurses.a', `libtermcap.a' respectively
248 `libtermlib.a'.
249
250 `--with-included-regexps'
251 Use the V8 regular expression functions included here.
252
253 IMPORTANT:
254
255 `--enable-de'
256 Generates and installs the German documentation files instead
257 of their English equivalents.
258
259Native Language Support
260=======================
261
262The `configure' script provides three more non-standard options. These
263will also be available in other packages if they use the functionality
264of GNU `gettext'. Use
265
266 `--disable-nls'
267
268if you absolutely don't want to have messages handling code. You will
269always get the original messages (mostly English). You could consider
270using NLS support even when you do not need other tongues. If you do
271not install any messages catalogs or do not specify to use another but
272the C locale you will not get translations.
273
274The set of languages for which catalogs should be installed can also be
275specified while configuring. Of course they must be available but the
276intersection of these two sets are computed automatically. You could
277once and for all define in your `profile'/`cshrc' the variable
278`LINGUAS':
279
280 (Bourne Shell) LINGUAS="de fr nl"; export LINGUAS
281
282 (C Shell) setenv LINGUAS "de fr nl"
283
284or specify it directly while configuring
285
286 env LINGUAS="de fr nl" ./configure
287
288Consult the manual for more information on language names.
289
290The second configure option is
291
292 `--with-included-gettext'
293
294This forces to use the GNU implementing the message handling library
295regardless what the local C library provides. This possibility is much
296less error prone because possible unreliable effects of the local
297message handling system are avoided. And perhaps more important: many
298useful features can only be exploited with this library. The reason is
299obvious: we cannot dig in the internals of other implementations. It
300is likely that the discrepancy between the GNU implementation and
301others will get bigger in the time coming. So better change now!
302
303The third option is:
304
305 `--with-catgets'
306
307The X/Open catgets functions which might be found in the local C
308library are not used by default. The reason is already described
309above: the GNU `gettext' library provides many useful extension which
310cannot be emulated with `catgets()'. Beside this the utility programs
311for generating the catalog used by `catgets()' vary heavily between
312different systems. You should select this feature only if you really
313don't want to use the GNU `gettext' library and do not want to extended
314functionality (but I do not see any good reason for such a choice).
315
316As a user, if your language has been installed for this package, you
317only have to set the `LANG' environment variable to the appropriate ISO
318639 LL two-letter code prior to using the programs in the package. For
319example, let's suppose that you speak German. At the shell prompt,
320merely execute `setenv LANG de' (in `csh'), `export LANG; LANG=de' (in
321`sh') or `export LANG=de' (in `bash'). This can be done from your
322`.login' or `.profile' file, once and for all.
323
324An operating system might already offer message localization for many of
325its programs, while other programs have been installed locally with the
326full capabilities of GNU `gettext'. Just using `gettext' extended
327syntax for `LANG' would break proper localization of already available
328operating system programs. In this case, users should set both
329`LANGUAGE' and `LANG' variables in their environment, as programs using
330GNU `gettext' give preference to `LANGUAGE'. For example, some Swedish
331users would rather read translations in German than English for when
332Swedish is not available. This is easily accomplished by setting
333`LANGUAGE' to `sv:de' while leaving `LANG' to `sv'.
334
335Some Installation Hints
336=======================
337
338Some points you might be interested in before installing the package:
339
340 1. If you run `make' with a distribution target, the Makefile rules
341 will schedule a recompution of the `gcal.pot' file. But this is
342 not possible without the GNU `gettext' package already installed.
343 If you don't have this package already installed and modified any
344 of the files build the package first with
345
346 `--disable-nls'
347
348 When this is done you will get a runnable `xgettext' program which
349 can be used to recompute `gcal.pot'.
350
351 2. The package contains a file `misc/magic.add'. This is intended to
352 be added to your `/etc/magic' file. After adding this the `file'
353 command will recognize GNU message catalog files (`.mo' files).
354
355 3. The locale name alias scheme implemented here is in a similar form
356 implemented in the X Windows Systems. Especially the alias data
357 base file can be shared. Normally this file is found at something
358 like `/usr/lib/X11/locale/locale.alias'.
359
360 If you have the X Windows System installed try to find this file
361 and specify the path at the make run:
362
363 make aliaspath='/usr/lib/X11/locale/locale.alias:/usr/local/lib/locale'
364
365 (or whatever is appropriate for you).
366 In the `misc/' subdirectory you find an example for a alias
367 database file.
368
369 4. On some systems it will not be possible to compile this package.
370 It is not only this package but any other GNU package, too. These
371 systems do not provide the simplest functionality to run configure.
372 Today are known the following systems:
373
374 configure name description
375 -------------- -----------
376 mips-mips-riscos 2.1.1AC RISCos
377
378Reporting Bugs
379==============
380
381Please send all comments and bug reports via electronic mail either to:
382
383 Thomas Esken <esken@gmx.net> (preferred and always available)
384
385or
386
387 Thomas Esken <esken@uni-muenster.de>
388
389or
390
391 Thomas Esken <esken@abacus.informatik.fh-dortmund.de>
392
393Actually, I do not know for how long the last two eMail addresses will
394remain valid. At any case, you can contact me via <esken@gmx.net>. If
395you want to write and you want be on the `safe side', CC your eMail to
396all above addresses.
397
398If all above actions have failed, eMail to <bug-gcal@gnu.org>.
399
400Bug reports should ideally include (if necessary in your opinion):
401
402 1. A detailed description of the bug behavior, not just
403 interpretations
404
405 2. The complete output of `gcal --version' (or the contents of
406 `defines.h' and the `src/Makefile' if you can't get `gcal' to
407 compile)
408
409 3. The hardware and operating system (try `uname -a')
410
411 4. The compiler used to compile (if it is `gcc', use `gcc -v')
412
413 5. All the system specific files which are automatically created
414 during the configuration phase (`config.h', `config.cache',
415 `config.log', `config.status') and if necessary also the
416 temporarily created files used for building them (`confdefs.h',
417 `confcache', `conftest.vals', `conftest.h'...)
418
419 6. The shell environment (try `set')
420
421 7. The complete `termcap' entry for your terminal if the bug occurs
422 while highlighting of text
423
424 8. The command line given to `gcal', that triggered the bug
425
426Copyright
427=========
428
429Gcal Copyright (C) 1994, 95, 96, 1997, 2000 by Thomas Esken is free
430software. You can redistribute it and/or modify it under the terms of
431the `GNU General Public License' as published by the `Free Software
432Foundation'; either version 3, or (at your option) any later version.
433A copy of this license is provided under the name `COPYING', see it for
434more details.
435
436How to get `gcal'
437=================
438
439The latest official version of Gcal is always available by anonymous
440ftp from <ftp://ftp.gnu.org>, or from any of the `gnu' mirror sites:
441
442 * gnu/gcal/gcal-*[.tar or .tar.Z or .tar.gz or .zip or .shar].
443
444Some ftp servers can automatically make a `tar.Z' or a `tar.gz' from a
445`tar' file. If you are getting Gcal for the first time, you can ask
446for a `tar.Z' or `tar.gz' file instead of the much larger `tar' file.
447