Imported Upstream version 1
[debian/gsimplecal.git] / doc / gsimplecal.1
1 .TH GSIMPLECAL 1 "2012-02-18"
2 .SH NAME
3 gsimplecal \- lightweight calendar applet
4
5
6 .SH SYNOPSIS
7 .B gsimplecal [-h|--help|-v|--version|next_month|prev_month]
8
9
10 .SH DESCRIPTION
11 This manual page documents the usage of the
12 .B gsimplecal
13 command.
14
15 .PP
16 .B gsimplecal
17 is a lightweight calendar applet. When it is started, it first shows up, when
18 you run it again, it closes the running instance. It was intentionally made for
19 use with tint2 panel to be launched upon clock click, but of course it will
20 work without it, you can bind it to some hotkey in you window manager, for
21 example.
22
23 .PP
24 Also, you may configure gsimplecal to display different world timezones clocks.
25 See the \fICONFIGURATION\fP section to get to know how to.
26
27
28 .SH COMMANDS AND OPTIONS
29 .TP 5
30 \fB-v, --version\fP
31 Print the program name and version to stdout, then exit with code 0.
32
33 .TP 5
34 \fB-h, --help\fP
35 Print the short usage help to stderr, then exit with error code 2.
36
37 .TP 5
38 \fBprev_month, next_month\fP
39 If the program is not running, simply run it.
40 If the program is running, change currently displayed month.
41
42 .PP
43 If no options and commands are given, the program is toggled, i.e. if it is
44 running it stops, otherwise it starts.
45
46
47 .SH CONFIGURATION
48 .PP
49 To configure the application you should manually create the file
50 .nh
51 \fB$XDG_CONFIG_HOME/gsimplecal/config\fP
52 (usually it will be
53 .nh
54 ~/.config/gsimplecal/config)
55 with contents like this:
56
57 .IP
58 show_calendar = 1
59 .br
60 show_timezones = 1
61 .br
62 mark_today = 1
63 .br
64 show_week_numbers = 0
65 .br
66 close_on_unfocus = 0
67 .br
68 external_viewer = sunbird -showdate "%Y-%m-%d"
69 .br
70 clock_format = %a %d %b %H:%M
71 .br
72 mainwindow_decorated = 0
73 .br
74 mainwindow_keep_above = 1
75 .br
76 mainwindow_sticky = 0
77 .br
78 mainwindow_skip_taskbar = 1
79 .br
80 mainwindow_resizable = 0
81 .br
82 mainwindow_position = none
83 .br
84 mainwindow_xoffset = 0
85 .br
86 mainwindow_yoffset = 0
87 .br
88 clock_label = UTC
89 .br
90 clock_tz = :UTC
91 .br
92 clock_label = Local
93 .br
94 clock_tz = 
95
96 .PP
97 The options are pretty self explanatory, but here is detailed description:
98
99 .TP 5
100 \fBshow_calendar\fP: 1 or 0, defaults to 1.
101 Sets whether the calendar should be shown. Most users want this option to be 1.
102
103 .TP 5
104 \fBshow_timezones\fP: 1 or 0, defaults to 0.
105 Sets whether the different timezone clocks should be shown.
106
107 .TP 5
108 \fBmark_today\fP: 1 or 0, defaults to 1.
109 Sets whether today's date will be marked in the calendar (besides the default
110 selection, i.e. when you click on the other day, today will remain marked
111 somehow, e.g. in bold print).
112
113 .TP 5
114 \fBshow_week_numbers\fP: 1 or 0, defaults to 0.
115 Sets whether week numbers are shown in the calendar.
116
117 .TP 5
118 \fBclose_on_unfocus\fP: 1 or 0, defaults to 0.
119 Sets whether the calendar will close if the window loses focus. Note that if
120 mainwindow_skip_taskbar is set to 1 then the calendar window may not be given
121 focus upon creation
122
123 .TP 5
124 \fBexternal_viewer\fP: string, defaults to empty string.
125 Command line to run when doubleclicking a date. This string is strftime'd
126 (see \fIman strftime\fP for the possible substitutions)
127 and passed to the shell. Thus you can use pipes, redirections, and whatever,
128 I hope.
129 .br
130 Currently the shell is hardcoded to
131 .nh
132 /bin/sh
133 though. I hope that will do for all the users, but if you've got a trouble,
134 please file a ticket (see \fIREPORTING BUGS\fP).
135
136 .TP 5
137 \fBclock_format\fP: string
138 Sets the clocks format. Look \fIman strftime\fP for the possible formats.
139
140 .TP 5
141 \fBmainwindow_decorated\fP: 1 or 0, defaults to 0.
142 Tells your window manager to decorate or not to decorate the main window.
143
144 .TP 5
145 \fBmainwindow_keep_above\fP: 1 or 0, defaults to 1.
146 Sets whether the main window should be placed on top of other windows by your
147 window manager.
148
149 .TP 5
150 \fBmainwindow_sticky\fP: 1 or 0, defaults to 0.
151 Tells your window manager to show gsimplecal on all desktops.
152
153 .TP 5
154 \fBmainwindow_skip_taskbar\fP: 1 or 0, defaults to 1.
155 Sets whether the main window should be shown in the task list by your panel or
156 window manager.
157
158 .TP 5
159 \fBmainwindow_resizable\fP: 1 or 0, defaults to 1.
160 Sets whether your window manager should allow the main window to be resized.
161 If you are using a tiling window manager which supports floating windows,
162 setting this options to 0 will most likely tell your WM not to tile the window.
163 (Tested with XMonad and Awesome).
164
165 .TP 5
166 \fBmainwindow_position\fP: mouse|center|none, defaults to mouse.
167 Tells your window manager where to place the gsimplecal window:
168 .TP 10
169      \fBmouse\fP
170 .br
171 close to the mouse cursor position (this one is useful when you bind gsimplecal
172 on some mouse click command);
173 .TP 10
174      \fBcenter\fP
175 .br
176 in the center of the screen;
177 .TP 10
178      \fBnone\fP
179 .br
180 it's up to your window manager to decide, where to place the window
181 (this one is useful when you bind gsimplecal invocation on some hotkey, so you
182 can configure your window manager to place gsimplecal in some predefined
183 position).
184
185 .TP 5
186 \fBmainwindow_xoffset\fP and \fBmainwindow_yoffset\fP: integer, default to 0.
187 Allow for main window position fine tuning. Throw an integer at these, and
188 it'll move the window by that number of pixels.
189
190 .TP 5
191 \fBclock_label\fP and \fBclock_tz\fP: string
192 These two options should go in pairs and \fBmust\fP be in the order given.
193 .br
194 Each pair creates new clock. The clock_label variable sets the string to be
195 displayed near the clock, the clock_tz sets the timezone.
196 .br
197 If you omit the value for clock_tz, local time will be shown.
198 .br
199 For a list of timezones see \fIman timezone\fP, or \fIls /usr/share/zoneinfo\fP
200
201
202 .SH KEYBOARD ACCELERATORS
203 .PP
204 You may use the following keyboard accelerators while gsimplecal window has a focus:
205
206 .IP
207 Escape, Ctrl+w, Ctrl+q: close the window
208 .br
209 j: switch to the next month
210 .br
211 k: switch to the previous month
212 .br
213 J: jump one year forward
214 .br
215 K: jump one year backward
216 .br
217 g, Home: jump to the current date
218
219 .PP
220 These are not yet configurable, but I'm working on it.
221
222
223 .SH REPORTING BUGS
224 .PP
225 Please, report any issues to the gsimplecal issue tracker, available at:
226 .nh
227 https://github.com/dmedvinsky/gsimplecal/issues
228
229
230 .SH AUTHOR
231 Created by Dmitry Medvinsky et al.
232
233
234 .SH SEE ALSO
235 tzset(3),
236 strftime(3)