README - calcurse_dmenu - A dmenu calendar.

README (5730B)
      1 calcurse_dmenu
      2 --------------
      3 dmenu ui for calcurse calendar program
      4 
      5 
      6 Usage
      7 -----
      8 
      9     $ sh calcurse_dmenu.sh
     10 
     11 WARNING - this program reads and writes to calcurse data files. If
     12 calcurse is installed, as a safety precaution please backup data files
     13 first before running this program.
     14 
     15 
     16 Description
     17 -----------
     18 A dmenu calendar.
     19 
     20 Reads and writes to calcurse data files and as such is fully compatible
     21 with calcurse (Note WARNING above). calcurse is not required to run a
     22 fully functioning calcurse_dmenu.
     23 
     24 The view and selection of calendar, todo, history, and alarm entries
     25 is a 100% dmenu experience. All entry functions are engaged by tagging
     26 the entry. By edit tagging an entry, the date, recurrance and
     27 description of the entry becomes editable in a dmenu interface. Tagging
     28 the entry for note editing employs the $EDITOR of your choice (see
     29 config.sh). A more complete view of entries is displayed by a pager of
     30 your choice (see config.sh).
     31 
     32 This is purely a dmenu/pager/editor experience. Not a single graphical
     33 representation of a calendar to be found. That's for the sake of
     34 efficiency. The entire goal of this is for speed of service and use.
     35 It provides a very fast access to your calcurse calendar and an equally
     36 swift interaction. If calcurse is installed, typing 'calcurse' into
     37 the dmenu prompt launches calcurse for the graphical experience.
     38 
     39 
     40 Add entry syntax
     41 ----------------
     42 date #recurrance :: description
     43 
     44 ### date (optional)
     45 
     46 The date is any human readable date string parsed by linux's coreutils
     47 'date' user command. See your date(1) man page for details.
     48 
     49 Note: For bsd/et al installs, you'll need to edit the entry_add.awk
     50 file to meet your needs. The easiest is to rewrite this using awk's
     51 builtin date functions, which will likely lead to stricter date entry
     52 when adding new calcurse_dmenu entries.
     53 
     54 The date may be a range, which is determined by a dash between two
     55 dates. If times are specified, entries are stored as calcurse apts,
     56 otherwise calendar entries are stored as calcurse events. See Examples
     57 below.
     58 
     59 ### recurrance (optional)
     60 
     61 A recurring entry is determined by deploying the '#' symbol after the
     62 date. A regex representation of the recurrance syntax is:
     63 
     64     #[0-9]+[dmyDMY] (end date)?
     65 
     66 In other words, pound symbol, following by lapse before next recurrance,
     67 followed by type of time lapse - day, week, month, or year, followed by
     68 the optional end date. Without the optional end date the recurrance is
     69 infinite; birthdays for example. See Examples below.
     70 
     71 ### description
     72 
     73 Description is the only required information to create a basic event
     74 entry. Without a date, the entry date is set for 'now' or rather today.
     75 Description can be almost anything, so long as it does not match the
     76 pattern of a note marker in the data files. So the following regex
     77 representation is not allowed in the description:
     78 
     79     >[a-f0-9]{40}
     80 
     81 Example:
     82 
     83     >123456789a123456789b123456789c123456789d
     84 
     85 Also wise to refrain from using '::' in description.
     86 
     87 
     88 Tag Commands
     89 ------------
     90 Tag commands are tags, set by default and configurable in config.sh.
     91 They comprise currently five functions:
     92 
     93 - :a - Show alarm entries
     94 - :e - Entry edit
     95 - :h - Show calendar history entries
     96 - :n - Entry note create/edit
     97 - :r - Entry remove
     98 - :t - Show todo entries
     99 
    100 The entry edit, remove and note tags work by tagging an entry's entire
    101 line. So for the following entry:
    102 
    103     Mon 29 > Work week begins {1W} <4
    104 
    105 The following returned selection initiates editing the entry in dmenu:
    106 
    107     Mon 29 > Work week begins {1W} <4:e
    108 
    109 And to open an $EDITOR for entry note creation/editing:
    110 
    111     Mon 29 > Work week begins {1W} <4:n
    112 
    113 And to remove/delete the entry:
    114 
    115     Mon 29 > Work week begins {1W} <4:r
    116 
    117 For todo, history, and alarm entries, simply return the tag in dmenu's
    118 prompt. eg:
    119 
    120     :h
    121 
    122 
    123 About Calendar Entry Types
    124 --------------------------
    125 Calcurse specifies two types of calendar entries.
    126 
    127 1. Apts - time specificion, one or more days.
    128 2. Events - no time specification, one day.
    129 
    130 Calcurse compliance dictates that if an event is to span more than one
    131 day, it must be recurred. So sticking to calcurse compliancy, a multi-
    132 day event would be enterred using recurrance in calcurse_dmenu by:
    133 
    134     today #3d :: Some three day event
    135 
    136 If a calendar entry begins with a specified time, it is considered an
    137 appointment (apt) and can last as many days as your system can handle.
    138 To set an apt in calcurse_dmenu, it could be as simple as:
    139 
    140     7:00 :: wake up
    141 
    142 Or something spanning several days:
    143 
    144     7:00 - 5 days 17:00 :: 5 day retreat
    145 
    146 Or the same retreat that recurs every year:
    147 
    148     7:00 - 5 days 17:00 #1y :: 5 day retreat
    149 
    150 
    151 Alarm
    152 -----
    153 Alarms are currently under development. The program is equiped to edit
    154 alarm entries (not a calcurse function by the way). The alarm
    155 implementation will be a stand alone process outside of calcurse_dmenu.
    156 It is safe to expect a functioning example of this in the future with
    157 documentation.
    158 
    159 
    160 Requirements
    161 ------------
    162 
    163 - linux (gnu coreutils date command)
    164 - dmenu
    165 - an $EDITOR
    166 - a pager, more or less
    167 - posix compliant shell tools: awk/sed/grep/sort
    168 
    169 
    170 Todo
    171 ----
    172 - Alarms
    173 
    174 
    175 Examples
    176 --------
    177 
    178     10 min :: Doing something in ten minutes from now
    179 
    180     thu 9:0 - 17:0 :: work on this thursday from 9a to 5p
    181 
    182     jan 12 #1y :: Important person's birthday
    183 
    184     sun #1w 10 years :: Day of rest, every Sunday, for ten years!
    185 
    186     5:00 #1d jun 12 2042 :: Wake up every day at 5am until 07/12/42
    187 
    188 Note on time: normally using the date command, you can specify time
    189 using am and pm, however due to calcurse_dmenu parsing of this line,
    190 the program looks for full-ish mil times, with a colon and at least a
    191 single digit on both sides of that colon. So specifying 5am time
    192 looks like: 5:0 or 5:00.
    193