Imported Upstream version 1
[debian/gsimplecal.git] / doc / gsimplecal.1
1 .TH GSIMPLECAL 1 "2012\-03\-26"
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 force_lang = en_US.utf8
73 .br
74 mainwindow_decorated = 0
75 .br
76 mainwindow_keep_above = 1
77 .br
78 mainwindow_sticky = 0
79 .br
80 mainwindow_skip_taskbar = 1
81 .br
82 mainwindow_resizable = 0
83 .br
84 mainwindow_position = none
85 .br
86 mainwindow_xoffset = 0
87 .br
88 mainwindow_yoffset = 0
89 .br
90 clock_label = UTC
91 .br
92 clock_tz = :UTC
93 .br
94 clock_label = Local
95 .br
96 clock_tz = 
97
98 .PP
99 The options are pretty self explanatory, but here is detailed description:
100
101 .TP 5
102 \fBshow_calendar\fP: 1 or 0, defaults to 1.
103 Sets whether the calendar should be shown. Most users want this option to be 1.
104
105 .TP 5
106 \fBshow_timezones\fP: 1 or 0, defaults to 0.
107 Sets whether the different timezone clocks should be shown.
108
109 .TP 5
110 \fBmark_today\fP: 1 or 0, defaults to 1.
111 Sets whether today's date will be marked in the calendar (besides the default
112 selection, i.e. when you click on the other day, today will remain marked
113 somehow, e.g. in bold print).
114
115 .TP 5
116 \fBshow_week_numbers\fP: 1 or 0, defaults to 0.
117 Sets whether week numbers are shown in the calendar.
118
119 .TP 5
120 \fBclose_on_unfocus\fP: 1 or 0, defaults to 0.
121 Sets whether the calendar will close if the window loses focus. Note that if
122 mainwindow_skip_taskbar is set to 1 then the calendar window may not be given
123 focus upon creation
124
125 .TP 5
126 \fBexternal_viewer\fP: string, defaults to empty string.
127 Command line to run when doubleclicking a date. This string is strftime'd
128 (see \fIman strftime\fP for the possible substitutions)
129 and passed to the shell. Thus you can use pipes, redirections, and whatever,
130 I hope.
131 .br
132 Currently the shell is hardcoded to
133 .nh
134 /bin/sh
135 though. I hope that will do for all the users, but if you've got a trouble,
136 please file a ticket (see \fIREPORTING BUGS\fP).
137
138 .TP 5
139 \fBclock_format\fP: string
140 Sets the clocks format. Look \fIman strftime\fP for the possible formats.
141
142 .TP 5
143 \fBforce_lang\fP: string
144 Overrides the \fILANG\fP environment variable, thus making it possible to
145 change the first day of week, i.e. choose if Monday or Sunday goes first.
146 Basically it's the same as running gsimplecal as
147
148     LANG=en_GB.utf8 gsimplecal
149
150 Must be one of \fIlocale -a\fP output.
151
152 .TP 5
153 \fBmainwindow_decorated\fP: 1 or 0, defaults to 0.
154 Tells your window manager to decorate or not to decorate the main window.
155
156 .TP 5
157 \fBmainwindow_keep_above\fP: 1 or 0, defaults to 1.
158 Sets whether the main window should be placed on top of other windows by your
159 window manager.
160
161 .TP 5
162 \fBmainwindow_sticky\fP: 1 or 0, defaults to 0.
163 Tells your window manager to show gsimplecal on all desktops.
164
165 .TP 5
166 \fBmainwindow_skip_taskbar\fP: 1 or 0, defaults to 1.
167 Sets whether the main window should be shown in the task list by your panel or
168 window manager.
169
170 .TP 5
171 \fBmainwindow_resizable\fP: 1 or 0, defaults to 1.
172 Sets whether your window manager should allow the main window to be resized.
173 If you are using a tiling window manager which supports floating windows,
174 setting this options to 0 will most likely tell your WM not to tile the window.
175 (Tested with XMonad and Awesome).
176
177 .TP 5
178 \fBmainwindow_position\fP: mouse|center|none, defaults to mouse.
179 Tells your window manager where to place the gsimplecal window:
180 .TP 10
181      \fBmouse\fP
182 .br
183 close to the mouse cursor position (this one is useful when you bind gsimplecal
184 on some mouse click command);
185 .TP 10
186      \fBcenter\fP
187 .br
188 in the center of the screen;
189 .TP 10
190      \fBnone\fP
191 .br
192 it's up to your window manager to decide, where to place the window
193 (this one is useful when you bind gsimplecal invocation on some hotkey, so you
194 can configure your window manager to place gsimplecal in some predefined
195 position).
196
197 .TP 5
198 \fBmainwindow_xoffset\fP and \fBmainwindow_yoffset\fP: integer, default to 0.
199 Allow for main window position fine tuning. Throw an integer at these, and
200 it'll move the window by that number of pixels.
201
202 .TP 5
203 \fBclock_label\fP and \fBclock_tz\fP: string
204 These two options should go in pairs and \fBmust\fP be in the order given.
205 .br
206 Each pair creates new clock. The clock_label variable sets the string to be
207 displayed near the clock, the clock_tz sets the timezone.
208 .br
209 If you omit the value for clock_tz, local time will be shown.
210 .br
211 For a list of timezones see \fIman timezone\fP, or \fIls /usr/share/zoneinfo\fP
212
213
214 .SH KEYBOARD ACCELERATORS
215 .PP
216 You may use the following keyboard accelerators while gsimplecal window has a focus:
217
218 .IP
219 Escape, Ctrl+w, Ctrl+q: close the window
220 .br
221 j: switch to the next month
222 .br
223 k: switch to the previous month
224 .br
225 J: jump one year forward
226 .br
227 K: jump one year backward
228 .br
229 g, Home: jump to the current date
230
231 .PP
232 These are not yet configurable, but I'm working on it.
233
234
235 .SH REPORTING BUGS
236 .PP
237 Please, report any issues to the gsimplecal issue tracker, available at:
238 .nh
239 https://github.com/dmedvinsky/gsimplecal/issues
240
241
242 .SH AUTHOR
243 Created by Dmitry Medvinsky et al.
244
245
246 .SH SEE ALSO
247 tzset(3),
248 strftime(3)