Welcome to cahier’s documentation!¶
One-directory-a-day calendar management
Note
I am no longer using this software, so it will not be improved. Feel free to ask questions and to submit bugs anyway, but this will not be my priority.
– Louis
Rationale¶
Note that althougt I wrote this program for this particular purpose, I had extensibility in mind. Please read on the usage and configuration sections before deciding that this program does not fit your needs.
As a part of my job as a teacher, I have to log my work on a daily basis
(cahier de textes in French, hence the name). To do so, I use IkiWiki. Each entry is stored in a markdown file named
YYYYMMDD.mdwn, and each attached document is located in the YYYYMMDD
directory. So, after a few days, an ls
gives:
$ ls
20130906 20130927.mdwn 20131018b 20131122 20131217.mdwn
20130906.mdwn 20130930.mdwn 20131018b.mdwn 20131122.mdwn 20131218.mdwn
20130909.mdwn 20131001.mdwn 20131104.mdwn 20131125.mdwn 20131220
20130910.mdwn 20131002 20131105 20131126.mdwn 20131220.mdwn
20130911.mdwn 20131002.mdwn 20131105.mdwn 20131127.mdwn 20140107.mdwn
20130913.mdwn 20131004.mdwn 20131106.mdwn 20131129a.mdwn 20140108.mdwn
20130916.mdwn 20131007.mdwn 20131108 20131129b.mdwn 20140110
20130917 20131008 20131108.mdwn 20131202.mdwn 20140110.mdwn
20130917.mdwn 20131008.mdwn 20131112 20131203 20140113.mdwn
20130918 20131009.mdwn 20131112.mdwn 20131203.mdwn 20140114.mdwn
20130918.mdwn 20131011 20131113a.mdwn 20131204.mdwn 20140115
20130920 20131011.mdwn 20131113b.mdwn 20131206.mdwn 20140115.mdwn
20130920.mdwn 20131014.mdwn 20131115 20131209.mdwn 20140117
20130923.mdwn 20131015.mdwn 20131115.mdwn 20131210.mdwn 20140117.mdwn
20130924 20131016 20131118.mdwn 20131211 20140120.mdwn
20130924.mdwn 20131016.mdwn 20131119.mdwn 20131211.mdwn 20140121.mdwn
20130925.mdwn 20131018a 20131120 20131213.mdwn 20140122
20130927 20131018a.mdwn 20131120.mdwn 20131216.mdwn 20140122.mdwn
There are several problems.
Command line completion is broken: file names are so close that it is almost useless:
typing in the file name to edit it is frustrating;
typing in the directory name to create it is frustrating;
typing in the directory name to move a file to it is frustrating.
When editing the file, I have to fill the date and time of the calendar entry, although this information is contained in the file name, and could be guessed (my timetable does not change from one week to another).
I have different classes, with different calendar, and I want the right class to be automatically taken into account.
I wrote this program to automate this task.
Download and install¶
See the main project page for instructions, and changelog.
Usage and configuration¶
Base commands¶
The base commands operate on the right calendar, with the right date.
The right calendar is determined using profiles (more information in section Profiles). In this configuration, you can associate several directories to one calendar. For instance, if I associate directory
~/courses/cs
with calendar~/calendars/cs101
, acahier
command run in~/courses/cs
(or any of its subdirectories) will consider the associated calendar. This is useful if you have several calendars.The right date is also configured in the profiles. You can register a simplified version of your time table, so that when editing a new entry, its date is calculated using this time table, and the appropriate date and time is filled in the template.
The base commands are (a full list of commands is available in section Full command line options).
cahier new
Create a new entry, at the right place, with the right date, and start editing it.cahier edit
Edit the last created entry.cahier attach
Attach a file to the last entry, that is:create the directory if necessary;
proprocess files if relevant: for instance, I want command
cahier attach foo.tex
to compilefoo.tex
as a pdf, and attach the resulting pdf;copy the files in this directory.
cahier cd
Start a shell in the calendar directorycahier wiki
Arguments to this command are passed toikiwiki
, in the calendar directory. More options are available as well, likecahier refresh
which compile the wiki (whatever the working directory is).cahier git
Arguments to this command are passed togit
, called in the calendar directory.
Configuration¶
String formatting¶
Strings of configuration files are formatted in two ways.
They are formatted according to the rules of the configparser module.
They are formatted, using the
{key}
format, with the following values:basename
: basename of the edited file (without directory nor extension);configdir
:cahier
configuration directory;dirname
: directory of edited file;filename
: like basename, with the extension.
General configuration¶
General configuration is set in file .cahier/cahier.cfg
. Example:
[options]
casesensitive: no
[bin]
editor: screen -t "$EDITOR" sh -c "(cd {dirname} && $EDITOR {filename})"
shell: screen
[wiki]
options: --verbose --no-rcs
fileformat: %%Y%%m%%d
fileformat-length: 8
template: {configdir}/templates/template.mdwn
options
:casesensitive
: Set whether profile names are case sensitive or not.
bin
:editor
: Command to call to edit files.shell
: Shell to invoke withcahier cd
.
wiki
:options
: Options used when callingikiwiki
.fileformat-length
: Length of date in the file names (e.g. if your file names are YYYYMMDD-foo,fileformat-length
will be 8; if your file names are MMDD-foo,fileformat-length
will be 4).fileformat
: Date format of files, as recognized by the datetime.strptime() function.template
: Template to use for newly created files.
Profiles¶
Profile configuration is set in .cahier/profiles/NAME.cfg
. Example:
[DEFAULT]
ikiwiki: ~/prof/1S3/cahier
[options]
workdays: monday:08 tuesday:09 wednesday:08 friday:15:30
[config]
setup: %(ikiwiki)s/wiki.setup
[directories]
calendar: %(ikiwiki)s/seances
sources: ~/prof/1S-math ~/prof/1S3
DEFAULT
: Default values for all sections.ikiwiki
: This is an example of a trick taking advantage of string formatting to factorize configuration: the%(ikiwiki)s
part in following options are replaced by value of this string.
options
:workdays
: Timetable, with times. This is a space separated list of DAY:HOUR. If this option is set, when editing a new file, the following date corresponding to one of those work days is used as the date. Otherwise, the current date and time is used.
config
:setup
: Path to the IkiWiki setup file.
directories
:calendar
: Path to the directory containing the calendar files.sources
: Paths associated to this profile. When callingcahier
in one of those directory, the corresponding profile is used.
File plugins¶
File plugins are configured in files .cahier/ftplugins/EXTENSION.cfg
(where EXTENSION is the extension of files impacted by this particular
configuration file).
[preprocess]
cmd: pdflatex {basename}
name: {basename}.pdf
preprocess
: Commands to preprocess files before attaching them. For instance, with this example, LaTeX files are compiled, and their compiled version is attached to the current date.cmd*
: Values of keys starting withcmd
are executed before attaching files.name
: Name of the file to attach, if different from the base file name.
File templates¶
Files .cahier/templates/template.foo
are used as templates when editing
a new file of type foo
. Type is the extension of the file.
Template content is formatted as a Python string, with only one variable:
date
: the date and time of the log of the created file.
Full command line options¶
Here are the command line options for cahier.