Gocal is a simple clone of pcal.
gocalendar 2024 # Create a 12-page calendar for YEAR, e.g. 2024
gocalendar 5 2025 # Create a 1-page calendar for the MONTH in YEAR, e.g. 5 2025
gocalendar 5 7 2026 # Create a sequence from BEGIN to END in YEAR
The project includes a cli tool and a library to create
monthly calendars in PDF. By default it creates a
12-page PDF with one month per page for the current year.
The library is called gocal, while the standalone tool is named gocalendar.
Gocalendar can be built with go build in the gocalendar folder.
There is a year mode that shows the entire year on one page. Have a look at the examples to get an idea of Gocal's capabilities.
Gocal was built because of pcal's lack of support for UTF-8 and because I feel that Postscript is obsolete.
- PDF generation
- Week number on every Monday
- Day of year
- Moon phases
- Events in XML configuration file
- Several languages
- Wallpaper option
- Photo calendar option (from single image or directory)
- Page orientation and paper size option
- Font selection
- Year calendar (two layouts)
- Import of ICS files (local file or URL)
The main design goal of gocal is simplicity. While it is absolutely possible to create an application where every single stroke is configurable, I believe that most of you are too busy to play around with lots of options and want a pleasant calendar out-of-the-box. That's what gocal provides.
The power of gocal is based on the cool libraries that it includes. This implies that several of the options are actually options of the libraries, e.g. the paper format (gofpdf) or the supported languages (goodsign/monday).
It is suggested to hide some of the optional fields or the cells will look crowded.
Run
go install github.com/StefanSchroeder/Gocal/gocalendar@latest
This will install the gocalendar executable in your go-bin folder.
Or the long haul:
Run
go get github.com/StefanSchroeder/Gocal
Gocal has a quite a few dependencies that go should resolve automatically.
To build the standalone tool, change into the gocalendar directory and run
go build
You create a bunch of sample files (and in passing test gocal) by running
go test
package main
import (
"github.com/StefanSchroeder/gocal"
)
func main() {
g := gocal.New(1,12,2010)
g.CreateCalendar("test-example01.pdf")
}
The license is in the LICENSE file. (It's MIT.)
For the API documentation of gocal the library visit the auto-generated docs on godoc.org.
-h Help: Summarizes the options.
-f="Gocal": Footer note
Change the string at the bottom of the page. To disable the footer, simply set it to the empty string.
-margin="Some string": A margin note on the right margin.
A note that that can easily be read when flipping through pages. E.g. when you have a lot of calendars for staff in a binder.
-font="": font
-font serif (Times lookalike)
-font mono (Courier lookalike)
-font sans (Arial lookalike)
-font path/to/font.ttf (your favorite font)
Set the font. Only truetype fonts are supported. Look into c:\Windows\Fonts on Windows and /usr/share/fonts to see what fonts you have. Gocal comes with three fonts built-in: The Gnu FreeMonoBold, FreeSerifBold and FreeSansBold. They look pretty similar to (in that order) Courier, Times and Arial and should meet all your standard font needs. These fonts are licensed under the Gnu FreeFont License which accompanies this README.txt. Read more about them at https://www.gnu.org/software/freefont. Auxiliary files are created in a temporary directory.
The Borel-font in the sample directory is licensed under the OPL and contained here only for testing purposes. It was downloaded from https://fontesk.com/borel-font/.
In addition you can provide your own TTF on the commandline if you prefer something fancy.
Font sizes relative to the default size can be set with
-fontscale floatingpoint number
The default is 1.0 and typically you shouldn't need to change the font size drastically. But since weekday names in some languages might be a lot longer than in other languages, ugly collisions may occur. To avoid that you can rescale the fonts a little by setting -fontscale to 0.9. There is a shortcut to reduce the fontsizes globally to 75% of the default size to gain more room for manual notes.
-small
-lang="": Language
Gocal reads the LANG environment variable. If it matches one of
"ca_ES" "da_DK" "de_DE" "en_GB" "en_US" "es_ES" "fi_FI" "fr_CA" "fr_FR"
"fr_GF" "fr_GP" "fr_LU" "fr_MQ" "fr_RE" "hu_HU" "id_ID" "it_IT" "nb_NO" "nl_BE"
"nl_NL" "nn_NO" "pt_BR" "pt_PT" "sv_SE" "uz_UZ"
the library goodsign/monday is used to translate the weekday names and month names. Although this library supports a few other languages, I found that some of the languages do not work with the fonts I tried. The language from the environment can be overridden with this parameter. If your LANG is not recognized, we default to en_US.
-nodoy: Hide day of year
-nomoon: Hide moon phases
-noweek: Hide week number
The week number according to ISO-8601 is added on every Monday by default.
-noother: Hide neighbormonth days
This option hides the leading and trailing days of the neighbor months. By default these days are printed in light grey.
-plain This will hide everything that can be hidden (but not neighbormonth days).
-o="output.pdf": Output filename
-p="L": Orientation (L)andscape/(P)ortrait
Typically you want landscape for calendars without image and portrait for calendars with image.
-paper="A4": Paper format (A3 A4 A5 Letter Legal)
-fill configure filled grid
Can be any combination of:
X even columns filled gray
x odd columns filled gray
Y even rows filled gray
y odd rows filled gray
S Sundays filled gray
s Saturdays filled gray
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
7 Sunday
Example:
-fill "x3Y"
The gray boxes are not transparent; therefore it doesn't make a lot of sense to combine gray boxes with a wallpaper image.
-photo=filename: Show single photo (single image in PNG JPG GIF)
This option will add this image to every month. The filename can be a URL, qualified with http:// and it must have a valid image extension.
-photos=directory: Show multiple photos (directory with PNG JPG GIF)
e.g. gocal -photos images/
This option will add the twelve first files as images to the twelve month. If less than twelve files are found, the sequence will re-start after the last image. This will not work if there are non-image files in the directory (among the first twelve). The directory option does NOT support URLs.
-wall=filename: Show wallpaper PNG JPG GIF
e.g. gocal -wall gopher.png
This option will add this image to every month as a background. You should only use images with a bright tone so that you do not obstruct the usefulness of the calendar. The filename can be a URL, and must start with http:// and must have a valid image extension.
-yearA
-yearB
Two different layouts are available. One with the months on the top and the days on the left and vice versa. Obviously there is less space for the individual day in this mode. Still, many of the options are available here.
-spread NUMBER
In the year calendars, the entire calendar is put on one page. Using the spread option, you can spread the year across NUMBER pages. Valid values are 1 (default), 2, 3, 4, 6 and 12. Using 12 is essentially the same as not using the year mode, because it will put every month on its own page.
Example:
-yearB -spread 4
This will put three months on each page.
This is a sample file event configuration file. Image can be a URL, which must start with http://
Load the file with
`-config myfile.xml`
<Gocal>
<Gocaldate date="1/15" text="Alice" />
<Gocaldate date="2/15" text="Bob" />
<Gocaldate date="3/15" text="Charles" />
<Gocaldate date="4/15" text="Daisy" />
<Gocaldate date="5/15" text="Æþelbryht" />
<Gocaldate date="6/15" text="Frank" />
<Gocaldate date="6/15" text="\nGeorge" />
<Gocaldate date="7/15" text="Henry" />
<Gocaldate date="8/15" text="Isildur" />
<Gocaldate date="9/15" text="Ethelbert" />
<Gocaldate date="10/15" text="Æþelbyrht" image="golang-gopher.png" />
<Gocaldate date="11/15" text="Eðilberht" />
<Gocaldate date="Monday" text="Run Marathon" />
<Gocaldate date="*/20" text="Pay rent" />
</Gocal>
Please note the cool Anglo-Saxon/Scandinavian letters, thanks to UTF-8 support.
This is a sample of the configuration file for gocal. It has all the supported features. date is in MONTH/DAY format. The text may contain a literal \n newline. For the month a * is permitted and it obviously means 'every month'. You can use a leading newline symbol to make the text wrap to the next line in case of overlap. THe optional image tag will put an image into the cell.
For the day an English Weekday name is permitted. It means: Every matching weekday.
I was considering to allow to configure all the options from the command line also as parameters in the XML, but I think it's not really that important.
The image can also be URL, but keep in mind, that every image will be downloaded every time, because the files are downloaded to a temporary folder which is deleted after gocalendar is done.
Using
-ics filename or URL
you can provide one or more ICS calendar objects. The events in the calendar will be added on matching dates.
Timezones are ignored. There is still no automatic linebreaking and no prevention of overlap with other configuration event entries.
From the ICS file, the SUMMARY attribute is added as text to the calendar.
Example:
gocalendar -ics http://www.google.com/calendar/ical/de.german%23holiday%40group.v.calendar.google.com/public/basic.ics
# Add German holidays to your calendar (because why wouldn't you).
Example:
gocalendar -ics my.ics
# Add your own local ICS file.
There is more than one way to create some example calendars.
You can use go test to validate that the library works
or you can run make after compilation to check that the standalone
tool works. Both procedures provide ample suggestions what you can do.
The blue frames are not part of the Gocal output, but have been added for these screenshots.
gocalendar -o example01.pdf -p P -photos pics 1 2026
gocalendar -o example02.pdf -lang fr_FR -font sans 2027
gocalendar -o example03.pdf -wall golang-gopher.png -lang de_DE -font data/Borel-Regular.ttf 2028
gocalendar -o example04.pdf -lang de_DE -font mono 2 2029
gocalendar -o example05.pdf -lang nl_NL -plain 3 2030
gocalendar -o example06.pdf -font data/Borel-Regular.ttf -lang en_US 4 2031
gocalendar -o example07.pdf -p P -lang fr_FR -photo pics\taxi.JPG 4 2032
gocalendar -o example08.pdf -lang fr_FR -photo golang-gopher.png 4 2033
gocalendar -o example09.pdf -lang fi_FI -font serif -p L 4 2034
gocalendar -o example10.pdf -lang fi_FI -font serif -p L 12 2035
gocalendar -o example11.pdf -lang de_DE -font sans -p L 6 9 2036
gocalendar -o example12.pdf -p P -photo http://golang.org/doc/gopher/frontpage.png 7 2037
gocalendar -o example13.pdf -font sans -noother 7 2038
gocalendar -o example14.pdf -small 2 2039
gocalendar -o example15.pdf -yearA 2040
gocalendar -o example16.pdf -yearB 2041
gocalendar -o example17.pdf -yearA -fill "c" 2042
gocalendar -o example18.pdf -yearB -fill "sS" 2043
gocalendar -o example19.pdf -ics data/german.ics 12 2023
This is a mature application that I use regularly and that meets all my needs. If you are looking for a fancy option, let me know by writing an issue. I will consider adding it.
- When you have multiple events on the same date, they are overlapping. I don't intend to fix that. Use the Newline to arrange your stuff.
- Not all text will fit into the cells with some settings, because the font size is not adapted dynamically to the paper format. It's a feature, not a bug.
- When using the A5 paper size, the last row of a page wraps to the next page.
- Some warnings in libraries might irritate the user.
- The dates and months are not validated. Nothing prevents you from trying to generate a calendar for "13 2014", which will panic.
I'd like to thank the developers who wrote the great libraries that gocal is relying on, especially Sonia Keys and Kurt Jung and Йордан Пулов.
(C) Copyright Stefan Schröder