===================================== Pining for the Fjords -- Installation ===================================== Pftf uses setuptools. While you can of course play all the games with virtual packages that you want, given that pftf doesn't talk to the network and has rather minimal dependencies, I'd say on most boxes you can install it system-wide, which on modern boxes means something like (this is for Debian):: sudo apt install python3-setuptools python3-matplotlib sudo -H pip install --break-system-packages --no-build-isolation . Contrary to what the option says, nothing will break. If you do not have root access on your machine or don't want to mess around in directories that should be managed by your package manager, you probably want to look at pipx. Matplotlib has rather horrible dependencies. If you don't want nice plots, you don't have to install it. Finally, if you plan to hack on the thing, install using:: sudo -H pip install --break-system-packages --no-build-isolation -e . Whatever you edit in your source directory immediately becomes active. Configuration ------------- You will need to at least tell configure pftf what kind of labels you want to give to your work. pftf's configuration is in ~/.pftf/config [#moveConfig]_. It's INI-style, i.e., you have sections in square brackets and items as key-value pairs. Consider this example:: [general] wClasses = Vac, Sic, Tra, Qual, Dev, Data, Comm, Admin, Mail, Orga hoursPerDay = 6 [classCols] Orga: xkcd:orange Comm: xkcd:lilac Mail: xkcd:lavender Data: xkcd:aqua Admin: xkcd:sky blue Qual: xkcd:teal PR: xkcd:grey Sp: xkcd:bright purple Strk: xkcd:salmon Transfer: xkcd:white Vac: xkcd:pale blue In wClasses, you have a comma separated list of labels. Make them short, or your timetracker window will become uncomfortably large. No blanks are allowed in the labels unless you set the allowBlanksInLabels option **and** make sure you never convert the tabs in the WTF to blanks. You should at least adapt wClasses to your liking. If you want plots, you should assign colours to these labels in the classCols section as well. Another important setting is dayClasses. Theses are labels in wClasses that are ignored in the selection given to you in tkpftf. Use these for occupations that usually take a whole day (vacation, travel, sick leave; though these may, for you, not last a whole day, of course). In all likelihood, you will need to adapt your holidays as well (see the [general] holidays setting and ``pining --help-holidays``). Ask to get your holidays included into the list of supported holidays. Options Reference ----------------- Here is a complete list of sections and options supported by pftf. To review those (and possibly get a more complete list:-), say ``pining --help-config`` Section [general] ................. Setting work classes, holidays, and such * allowBlanksInLabels: boolean; defaults to 'False' -- Allow blanks in labels. If you enable this, you must never edit the WTF with an editor that converts tabs * dateformat: ASCII string; defaults to '%Y-%m-%d' -- Date format used. Do not change. * dayClasses: set of strings; defaults to 'Vac, Sic, Tra' -- Elements of wClasses that should not be shown in the timekeeping GUI (because the activities usually take an entire day and are handled trough pineday * holidays: set of strings; defaults to 'NewYear, Epiphany, GoodFriday,EasterMonday, RealLabourDay, AscensionChrist, CorpusChristi, PentecostMonday, LumpingFeast, AllSaints, Christmas1, Christmas2' -- Public holidays in effect in your jurisdiction, used for the computation of the work due. To see the available holidays, say 'pining holidays'. You may want to retrofit your holidays in pftf.due. Please feed back your patches. * hoursPerDay: floating point value; defaults to '8' -- Daily work time (usually computed as (weekly work time)/5 or so), in hours * isoformat: ASCII string; defaults to '%Y-%m-%dT%H:%M:%S' -- ISO time format. Do not change. * monthformat: ASCII string; defaults to '%Y-%m' -- Part of the date format covering year and month. Do not change. * wClasses: list of strings; defaults to 'Vac,Sic,Tra,Dev,Oth' -- List of the labels available for work time. Be short, these labels take up screen space in the timekeeping GUI * workDays: set of integers; defaults to '0, 1, 2, 3, 4' -- Indices of weekdays you are supposed to work on regularly, Monday=0. This is only used to compute your hours due. Magic Section [classCols] ......................... Assignment of colours to labels in graphs. Note that the colours here are from the X11 colour database (rgb.txt). To see what's available, say 'pining colours'. The items in this section are all of type string. You can add keys as required. * Dev: string; defaults to '' -- Undocumented * Oth: string; defaults to '' -- Undocumented * Sic: string; defaults to '' -- Undocumented * Tra: string; defaults to '' -- Undocumented * Vac: string; defaults to '' -- Undocumented Section [filenames] ................... File names (the base directory is in PFTFPATH) * archiveFile: string; defaults to 'pined.tsv' -- Name of the file containing archived time data. * piningFile: string; defaults to 'pining.tsv' -- Name of the file containing current time data. Section [gui] ............. Settings related to the timekeeping GUI; colours inhere are Tk colours, i.e., #rrggbb works. * background: string; defaults to '#a0ff8d' -- Background colour * highlight: string; defaults to '#ff0000' -- Colour of labels that are selected * hSpace: integer; defaults to '5' -- Pixels of horizontal space between two labels. * labelFont: string; defaults to 'Helvetica,8' -- Font to use for the work labels as face,size. Basically, we understand what tk understands. * pollInterval: integer; defaults to '1000' -- Interval UI should check for changes on WTF in milliseconds, 0 to turn off. * title: string; defaults to 'pftf' -- Window title * unselected: string; defaults to 'black' -- Colour of labels that are not selected * width: integer; defaults to '50' -- Width of the GUI window (the height will be computed from wClasses). Section [plot] .............. Settings related to work time plots * defaultOutputName: string; defaults to 'pined.pdf' -- Name of the graphics output, - for stdout .. [#moveConfig] If you do not like that location, you can change the base directory with the environment variable PFTFDATA. If you change it, all locations change accordingly. The config will always be called config, though.