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 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)