diff options
| -rw-r--r-- | NEW_CLI.md | 123 | ||||
| -rw-r--r-- | NEXT_LEVEL.md | 130 | ||||
| -rw-r--r-- | USER_GUIDE.md | 158 |
3 files changed, 2 insertions, 409 deletions
@@ -1,122 +1 @@ -I'm currently working on a cal.py aka kal that eventually will replace calendar-cli.py. This is the long document with design thoughts, and it may not be completely in sync with what I'm actually implementing. You may want to read the shorter [USER_GUIDE](USER_GUIDE.md) for a more up-to-date and shorter document. - -## General thoughts - -* calendar-cli should be a simple command line wrapper over existing python libraries. It should not contain a lot of logic besides parsing command line options and arguments. Logic that may be useful for python programmers should be pushed to other libraries, like the caldav-library, or be split into a new library. -* Old calendar-cli stays for quite some time, for backward compatibility -* We'll split out a new command for the new interface, probably it will be `kal`. I considered a lot of different name options: - * cal ... but `cal(1)` - is a well-established command, so it's out of the question (unless we overload the command by making a wrapper calling `cal` if no subcommand is given ... that could be an idea). - * `calcli`, `cal-cli` and different variants of it. The dash already hurt me with calendar-cli, don't want to repeat that. And "cli" is a bit redundant, when typing a command on the command line it's reasonable to assume it's a cli. - * `cal-add`, or even `cal-add-todo` ... but modern cli frameworks are more often than not built over different variants of `command subcommand subsubcommand`. - * `kal` ... looks a bit like a silly misspelling or an attempt to localize it into some non-english language (which then will look even more silly when combined with english subcommands and english options). At the other hand, I do see that it's not entirely uncommon to use `klass` when putting a class into a variable in python, `kal` is short to type, easy to remember, and there aren't too many other projects utilizing the `kal`-name as far as I can see. -* We'll use click, which is supposed to support subcommands in an elegant way. -* I'm fairly happy with the todo interface for listing/editing/completing. First options to filter/sort/limit the todo item(s), then a subcommand for what to do on those items. -* Should consider that we at some point may want to support tools that doesn't support caldav. Should also consider that we may want to support tools that doesn't support icalendar. For instance, issue tracking through gitlab or github. -* Perhaps a new calendar-tui for increased interactivity? -* Some or all of the commands should be possible to iterate over several calendars. This is almost impossible with `calendar-cli` due to the way the configuration is made (perhaps we should require that connection parameters are given in a config file?) - -## Details - -### Add an event, task or journal entry: - -``` -kal --config-section=private_calendar add --set-location="Aker Brygge marina" event "new years party" 2032-12-31T20:00+5h -kal add todo "Buy food for the new years party" --set-due=2032-12-30T20:00 --set-duration=1h - -kal add journal "Captain's log" 2020-12-04 'Started from Świnoujście a bit after 03AM. Due to miscommunication, bad planning and language problems my crew member Bartek managed to throw the whole mooring rope to the sea (clearly the captains fault - I didnt explain the task "release one end of the rope, let it go into the sea and then pull it in" well enough, and he did ask multiple times "are you really sure about that?" before throwing both ends of the rope to the sea). Tail wind, between 8-16 knots relative windspeed, changed a bit between broad reach and butterfly. While going butterfly, due to a rather big wave we had an accidental jib, bad enough that the preventer rope broke off the cleat it was attached to (but luckily no damanges to the rig). There seems to be a minor salt water leakage by the rudder. Passed Falsterbo around 21, moored up in the guest harbour in Skanör around 22. Very quiet as it was way outside the season. Didnt find any obvious choice on the payment automat for harbor fee - eventually I payed SEK 100 for "tvättstuga". I got no access to the laundry room, so I decided that 100 SEK was an OK price for staying overnight with electricity off-season in Skanör.' -``` - -While the specification for journal, todo and event are fairly similar, the non-optional parameters will be different due to slightly different typical use-case scenarios: - -* All three should have a summary as the mandatory first parameter (deviation from calendar-cli which takes the timestamp as first parameter when creating an event) -* For making todos, that should be the only mandatory parameter (as with "calendar-cli todo add"). Not all tasks have a clear due-date. In accordance with my task management ideas above, all tasks should eventually have a due date set, but the idea is also to be able to quickly throw things on the list, and then consider an appropriate priority and due date later. -* dtstart is (If I read the rfc correctly) optional for all three classes, but it doesn't make much sense to have an event without a start time - and a journal entry should have a date. For events, the same timestamp format is used as in the existing calendar-cli - duration can be piggybacked in the timestamp. Change of parameter order, with "calendar-cli calendar add" the dtstart should come before the summary. This to make "summary first" consistent for all three calendar object resource classes. -* For journal entries (as they are intended), it doesn't make much sense to add an entry without a description, so it's the mandatory second parameter. - -The todo-item added above has both due timestamp and duration set, which is against the RFC. It will be converted to dtstart and due before it's pushed to the calendar. - -### Reading the calendar - -To get things out from the calendar, one can use the kal agenda command: - -``` -kal agenda --config-section=private --config-section=work --agenda-days=30 --event-template="{dtstart} {summary} UID={uid}" --todo-template="{due} {summary} UID={uid}" -``` - -kal agenda should first print out all events starting or ending within the next 30 days, then all tasks with dtstart or due within the next 30 days. (in my revised "task management" above, dtstart is defined as due minus estimated work time). The tasks should be "smart sorted", according to the algorithm given in the "Task management" section above ("based on the ratio between duration and available time until due date"). It should accept several --config-section, take out all it can find from those config sections and sort the things afterwards. Exceptions due to unreachable caldav servers or calendars not supporting tasks etc should be caught and presented nicely. - -The kal agenda is to be considered a convenience-command, it is slightly redundant. The output of the command should be considered to be for direct human consumption, no further processing of the output should be done. The kal select command is the ultimate tool for a lot of things: - -``` -kal select --timespan=2021-12-01+2w list -kal select --todo --nocategories --list -kal select --todo --nocategories -1 edit --add-category=keyboard -kal select --todo --due-before=2021-12-01 --categories=keyboard --smart-sort list -kal select --todo --due-before=2021-12-01 --categories=keyboard --smart-sort -1 complete -kal select --uid=e71a6180-45a2-11ec-9605-fa163e7cfdd5 delete -kal select --due-before=2021-12-24T15:00 --categories=housework calculate-panic-time --work-factor=0.125 -kal select --journal --dtstart-after=2021-10-01 --dtstart-before=2021-11-01 sum_hours -``` - -kal select should select objects based on some criterias and then perform some action (`list`, `edit`, `postpone`, `complete`, `delete`, `calculate-panic-time`, 'sum_hours' and some more - see further below) on the objects. - -The technical differences between tasks, events and journal entries are small - kal select should basically work on all three of them unless `--todo`, `--event` or `--journal` is epxlicitly given. If the action given does not match one or more of the objects selected (say, "completing" a journal does not make sense), the script should raise an exception before doing any modifications of the calendar. `--offset` and `--limit` may be used to specify a handful of objects. "-1" is shortform for "--limit 1", or typically "do this action with the top item at the list" - -`--smart-sort` will give the above mentioned sort algorithm for tasks, and regular sorting by dtstart for events and journals. - -The `calculate-panic-time` command will take out all planned events and todo items, count the duration of those and print out a timestamp for when you need to panic. If it shows a timestamp in the past one should either PANIC!!! or procrastinate some tasks and cancel some events. The command takes the `--work-factor` parameter which specifies how much of the time you will be able to concentrate on the selected tasks. For instance, an "ordinary" parent having kids to take care of, a daytime job, plus the need for sleeping every night may perhaps in average be able to spend 3 hours a day - or 12.5% of the full day - on house work. - -This should cover most regular needs for putting events on a calendar and managing tasks and todo-lists. It does not cover "pinning" tasks to a calendar nor tracking time spent on tasks. There may also be a need for a bit more interactivity. Sending invites and replying to invites is also not covered. - -Logical "and" should be assumed between filter selectors. I feel uncomfortable with implementing support for paranthesis and logical operators, but there could probably be a --union parameter working as a "logical or", and some syntax should be made for the individual filters (but `--limit`, `--offset` and `--sort` should be processed after the union). Perhaps `--categories=housework+gardenwork` should fetch everything with either "housework" or "gardenwork" as category, while `--categories=housework,kitchen` should fetch all housework to be done in the kitchen. Or maybe `--categories=housework&gardenwork` and `--categories=housework|gardenwork` is less ambiguous. It probably needs to be thought more through. - -sum_hours will sum the duration of all objects. For tasks and events in the future, it's supposed to be the amount of time "committed", for tasks and events in the past, it is supposed to be the amount of time actually worked. (Time tracking is tricky, the icalendar standard does not really support it, and journal entries cannot have duration, but I'll get back to that). - -### Pinning tasks to calendar - -The `pin` subcommand will "pin" one or more todo-items to some specific time on the calendar. Duration will be copied. The tasks will be serialized. If there are conflicting events in the same calendar, the tasks will be put after the conflicting events. No checks will be done to ensure that the tasks ends up within ordinary working hours, outside the night hours or before the due date. Or perhaps some sanity checks should be done ... it will be a lot of cleanup-work to be done if one accidentally forgets "-1" and adds some hundreds of items to the calendar ... - -```kal select --todo --categories=housework --smart-sort --limit=3 pin '2021-12-02 16:00'``` - -### Time tracking - -(see also [NEXT_LEVEL.md](NEXT_LEVEL.md)) - -The `complete` subcommand takes optional parameters `--spent=4h`, `--log="I just hammered on the keyboard all until eventually all the unit tests finally passed. yay!"`, `--start=2021-10-06T12:00` and `--end=2021-10-06T16:00`. - -Rules: - -* A new journal entry is created, and marked as the child of the completed task or event. -* Both events and tasks can be "completed". If an event is "completed", it is implicit that time was spent, and time will be tracked even without any extra parameters. -* If a task was completed and it has a child event ("pinned task"), it is to be considered as if the child event was completed. -* For an "ordinary" task (one that isn't pinned), time will only be tracked if at least one of the four options above is given. Meaning that if no such option was given, the rest of the logic is ignored. -* If all three time-related parameters are given, the duration should match dtend-dtstart, and this should be validated. -* If two of the three time-related parameters are given, the third will be calculated. -* If only `--spent` is given and it's an event, '--start' is considered to be the dtstart of the event, and `--end` can be calculated. -* If only `--spent` is given and it's an ordinary task, `--end` is considered to be the time the task was marked completed (which is "now") and `--start` can be calculated. -* If only start is given, the duration of the event/task is used to find `--spent`, and from there `--end` can be calculated. -* If no time parameters are given, and it's an event, use dtstart and due/dtend -* If no time parameters are given, and it's a task, set completed (and `--end`) to "now", consider the duration estimate as correct, and find `--start` from there. -* The new journal dtstart date should be set to the date of the `--start` timestamp -* For a pinned task having a child event without extra participants, we consider the event data as unimportant to keep. If the time parameters doesn't match the event dtstart/duration/dtend, then the event should simply be edited and saved back, and used as the parent for the new journal entry. -* For an ordinary event, if `--start` and `--end` doesn't match the dtstart and dtend, duplicate the event, prepend the summary with "Completed:" and let the new event be a parent of the new journal entry. -* For an ordinary task, if the duration matches, the journal entry will be a direct child of the task -* We don't want to edit the duration of a task - that's the original estimate and we may want to keep that information. If it's an ordinary task and the duration of the task does not match, then the task information should be duplicated in a new child event, this child event should be the parent of the journal entry, and the summary should be prepended with "Completed: " - -...clear as mud? :-) - -## Scheduling - -TODO - -## Interactivity - -Quite much can be gained by using any kind of desktop calendar application, mobile calendar app or caldav webui towards the calendar - though as per the cruft in the examples/task-management-examples it could probably be an idea to create some kind of a simple text UI allowing to interactively going through a list of tasks and do things on them, like: - -* Setting one or more categories on all tasks missing a category -* Setting due-date and priority on all tasks missing that -* Go through all overdue and neardue tasks and mark the completed ones as completed -* Go through all events that has just passed and mark up if one really attended or not, and time spent while doing so. -* Easily go through a list of tasks suggested to be postponed and interactively select/unselect tasks from there. - -In examples/task-management-examples I simply used the `list`-command combined with `--todo-template` to create new calendar-cli commands, those were sent to an editor for manual editing. The script looks horrible, but it kind of works. +This document has been moved into the kal project hosted at github. The new authorative version is available at https://github.com/tobixen/kal/blob/master/DESIGN.md diff --git a/NEXT_LEVEL.md b/NEXT_LEVEL.md index 00f4282..f36d9fe 100644 --- a/NEXT_LEVEL.md +++ b/NEXT_LEVEL.md @@ -1,131 +1,3 @@ # On the "next level" calendar-cli - a full-featured tool for calendar management, project management and time tracking -This document is dedicated to my rubber ducky - but if anyone else has the patience to read through it, feedback is appreciated. - -## Tasks vs events vs journals - -In my paradigm, a task is a planned activity that should be done, but not at a specific time (but possibly it should be done within a specific time interval). When it's done - or when it is deemed irrelevant to do it - it can be striken out from the list. An event is something that should be done at a relatively well-defined time. While you may come an hour early or late to the Saturday night party and still have a lot of fun - if you come at the wrong date, then there won't be a party. - -It's not always black and white - events may be task-alike (like an appointment that will have to be rescheduled if you miss it) and tasks may be event-alike (i.e. with a very hard due-time and that cannot be done long time before the due date). - -Both events and tasks generally contain infomration about future plans, journals contain information about the past. - -## Some potential requirements from a good calendaring system: - -* 100% of all calendar users wants the possibility to "strike out" a thing from a calendar (I heard it at the CalendarFest event, so it must be true - though it does break with my paradigm). - -* It may be useful to take meeting notes directly from a calendar application (it was also said at the CalendarFest). - -* Project management and accounting systems needs information on time estimates and tracking the time spent working on a task (this is a matter of fact). Project management and accounting systems ought to be tightly coupled with the calendar system (that's my opinion). How much time does one expect a task to take, and how much was spent on the task? How many of the hours spent on the tasks should be billed (and how many of those should be billed at over-time rates?). Should the employee get paid at normal rates or overtime rates for the working hours spent? - -* Recurring tasks is a very useful thing! (this is my personal opinion, also ref the [TASK_MANAGEMENT document](TASK_MANAGEMENT.md)) Some of them should be done at a fixed time, no matter when it was done previous time, i.e. "prepare gym bag for my sons gym class" should be done every Tuesday, with deadline Wednesday morning. At the other hand, the task "clean the floor" should typically be done one week after it was done previous time. - -* In my opinion (ref TASK_MANAGEMENT), it makes sense on a daily basis to take out relatively short sorted list of tasks, look through it and keep the list short by procrastinating the things that seems less urgent. I've been using the DTSTART attribute for such procrastination, but it feels a bit wrong. - -* For collaboration, it's important to check when participants have available time, as well as to be able to invite participants to calendar entries, and to be able to reply to invitations in such a manner that the event both appears on the personal calendar and that the organizer gets notified on whom will participate. - -## Standards as they are now: - -### Calendar resource object types - -The RFC specifies three different kind of calendar resource object types, it's the VJOURNAL, VTODO and VEVENT. From a technical point of view, the differences are mostly in what timestamps the object holds. The VEVENT has a DTEND, the VTODO has a DUE, and the VJOURNAL ... has neither. The VEVENT is generally expected to have a DTSTART. The VJOURNAL is generally expected to have a DTSTART set to a date. A VTODO need not have a DTSTART. There is also the STATE field that can have different values depending on the object type. I think all other differences enforced by the RFC is minor. - -Calendaring systems usually have very different user interfaces for tasks and events (and journals are generally not used). Generally, tasks can be "striked out", but they don't stick very well to the calendar. None of the three types are well-suited for tracking the time spent working on a task or attending to a meeting. - -VJOURNAL entries on a calendar is the correct place to store meeting notes ... probably as well as recording things like who was really participating in an event. It can also be used for recording a diary or make other notes on what one has done during the day. - -VEVENT and VTODO is generally optimized for keeping information about the future - while VJOURNAL is supposed to be used for keeping information about the past. However, the RFC is not explicit on this, and I haven't heard of any implementations that denies one creating tasks/events with timestamps in the past nor journals with DTSTART in the future. - -### More on timestamps - -A VJOURNAL can only contain a DTSTART, and no DURATION or DTEND. This makes it impossible to use the VJOURNAL to track how much time has been spent. I think this is stupid - as written above, time tracking is something we would like to do at the calendar level, and since it's information on things that has already happened, VJOURNAL is the only logic place to put it. - -A VTODO may have a DTSTART and a DUE. I think the DUE timestamp is relatively easy to define, it's the time you, your leader, your customer and/or your significant other and/or other relevant parties expects the task to be completed. It may be a hard deadline, or it may be a "soft" target that may be pushed on later. The DTSTART is however a bit more tricky, I can see the field being used for quite different purposes: - -* The earliest possible time one can start working with a task (or the earliest possible time one expects to be able to start working with it) -* The time one is actually planning to start working with it -* The latest possible time one can start working with it, and still be done before the due time. -* The time one actually started working with the task - -As an example, consider a tax report to be filled out and sent to the authorities, the latest at the end of April. Consider that one will have to pay fines if it is not delivered before midnight the night before 1st of May. One cannot start with it before all the data one needs is available, perhaps 1st of April is the earliest one can start. One may plan to work with during a specific Sunday in the middle of April. If it takes three hours to complete the report, the very latest one can start is at 21:00 night before the 1st of May, but it would be very silly to actually start at that time. And perhaps one actually got started with it at noon at the 25th of April. - -A VEVENT and a VTODO may take a DURATION, but it cannot be combined with DTEND or DUE. While the RFC is not explicit on it, it is my understanding that DURATION and DTEND/DUE is interchangable - if DTSTART and DTEND/DUE is set, the DURATION is implicitly the difference between those two - an object with DTSTART and DURATION set is equivalent with an object with DTSTART and DTEND/DUE set. For the rest of the document, DURATION is understood to be the difference between DTSTART and DTEND/DUE. In my head, tasks have a DUE and a DURATION while the DTSTART is a bit more abstranct. Hence, setting or changing the DURATION of a task may efficiently mean "setting the DTSTART" - and the definition of DTSTART depends on the definition of DURATION. Is the DURATION the time estimate for completing the task? Then DTSTART will have to be the very latest one can start with the task and still complete before the DUE. - -Other observations: - -* It is possible to specify that a task should be a recurring task, but there is no explicit support in the RFC of completing an occurrence. In the existing version of calendar-cli, a new "historic" task instance is created and marked complete, while dtstart is bumped in the "open" task. (there is an alternative interpretation of "recurring task", it could mean "let's work on project A every Tuesday after lunch, all until it's completed"). - -* Calendar components can be linked through the RELATED-TO-attribute. Valid relationship types are "CHILD", "PARENT" and "SIBLING". I suppose it is intended for direct asyclic graphs, where a calendar component preferably should have only one PARENT, and where there shouldn't be loops (my grandchild cannot possibly also be my grandparent) - and that two SIBLINGs have the same PARENT. - -* RFC6638 gives a framework for inviting and replying to calendar events ("scheduling"), but few calendar servers supports it fully. - -## Suggestion for work flow and use (or abuse?) of the icalendar standard: - -### Sticking a task to the calendar - -One may have an agenda with lots of events and some "unallocated" time in between, and one may want to try to plan getting specific tasks done at specific times. It may be nice to get this into the calendar. - -If a task has a DTSTART set, it may be interpreted as the time one actually plan to start working with the task - but it's non-ideal, for one thing most calendaring user interfaces will not "stick" the task to the calendar on that, and the DTSTART attribute may be used for other purposes. - -It may make sense to make a VTOOD stick to the calendar by making up a VEVENT and letting that VEVENT be a child of the VTODO. - -Similarly, for calendar items that "needs" to be "striken out" (say, some course you need to take - if you miss the scheduled course time then you need to take it at a later time), it may make sense to create a "parent task" for it. - -Perhaps even make it to a general rule that all activities should be registered on the calendar as a VTODO/VEVENT parent/child pair, where the VTODO contains time estimates and the VEVENT contains planned time for doing the VTODO. - -### Time tracking - -When marking a task (VTODO) as completed, it ought to be possible to mark up how much time was spent on it (i.e. "2 hours"), optionally when it was done (default, worked on it until just now), optionally a description of what was done. Similarly, for a VEVENT it should be possible to write up i.e. meeting notes and record that one actually spent time being in a meeting. - -VTODO tasks are non-ideal for holding information on time spent while doing the task. While DTSTART and DURATION, or DTSTART with COMPLETED can be used in the VTODO for marking out how much time is actually used, this will efficiently overwrite other information stored in those attributes. I.e., DURATION may be used for time estimate, DUE may be used for indicating when the task needs to be done, this is information it may be important to keep (but to make things more difficult, DUE and DURATION are mutually exlusive). - -If one always ensures to "stick" tasks to the calendar, time tracking can be done in the DTSTART/DTEND of the VEVENT. However, event objects are also not really designed for keeping time tracking information. As said, the primary purpose is to contain information about the future - not the past. There is no participant state for "participated" in the event, the nearest is "accepted". "Accepted" means "I was planning to attend to this event", it doesn't mean "I actually participated in this event". It could also cause extra noise if one is to actively reject a calendar event after the event happened, as it may cause notifications to be sent to the organizer. To make it even more complicated, the time spent on the event may be different than planned (i.e. a meeting dragging out in time or being cut short), it doesn't always make sense to edit the DTSTART/DTEND of a meeting to indicate how much time was actually spent on the meeting. - -A VJOURNAL entry is (the only entry) supposed to describe the past, and could be a good place to store such data. Unfortunately VJOURNAL entries cannot have DURATION nor DTEND (and it's recommended to put a date rather than a timestamp into DTSTART). - -It is a great mess - the designers of the calendar standards absolutely didn't consider the need of tracking time spent. - -While working with code for completion of a reccurrence of a recurring tasks, I realized that we're actually storing information on *what has happened* when we're changing the status to "completed" and adding a timestamp for when it was completed. For a recurring task we're also duplicating the information in the task. Hence we can keep the original time information in the original recurring task but store actual time spent in the recurrence. The time spent may *either* be stored in the DURATION or through the difference between DTSTART and COMPLETED timestamp. To avoid any kind of confusion, I propose to set DUE and COMPLETED to the same timestamp, and let the DURATION indicate the time spent. Non-recurring tasks may be hand-crafted into recurring tasks with COUNT set to one. That does feel like a rather dirty workaround though. - -One idea may be to always make a VJOURNAL, a child of a VEVENT or VTODO, to mark either that the VEVENT took place and that one participated in it, or that one did spend time working on a task. For a VEVENT, if things went as planned, it's straight forward - the DURATION of said event marks the time spent on it. If things didn't go as planned, then ... either one may need to edit the VEVENT or create a separate VEVENT (which may be a child of the original VEVENT) containing the correct timestamps. If it was a VTODO and it wasn't "stuck" to the calendar, then it's trivial to make an after-the-fact VEVENT (just be careful that no calendar invites are sent out). For a VTODO one may hack up something by considering the difference between the journal DTSTART and the task COMPLETION timestamp to be the actual time worked on the task. Or it's possible to track the time by retroactively "stick the task to the calendar", and let the VJOURNAL be a child of a VEVENT which is a child of the VTODO. - -So I haven't concluded yet on how it is best to do time tracking on tasks, but there are some options. In any case, I think that consistently using a VJOURNAL entry to mark that one has actually participated in an event or spent time working on a task is a good idea. - -There is additional complexity that the time spent may be flagged as overtime, and that there may be billing information as well. I'm considering it to be site-specific and outside the scope. It may be possible to squeeze this information in somewhere, maybe in the CATEGORIES field, or maybe in some X-NONSTANDARD attributes. - -### Striking out something from the calendar - -The considerations above sort of leaves us with two ways of "striking out" something. There is the traditional way of marking the task as COMPLETED. Now if the task is connected to a VEVENT, the calendar item should also be striken out. - -The second way is to make sure there is a VJOURNAL attached as a child of the VEVENT or a (grand)grandchild of the VTODO. - -Those two ways of striking out things have fundamentally different meanings - the first is to mark that a task is done and closed and does not need to be revisited, the second is to mark that work time was spent on the task or event. This may be combined in different ways; - -* If one did some work and completed a tas, one would typically want to use both kind of "strikes". -* Sometimes one may want to mark a task as "completed" or "cancelled" even if one hasn't spent time on it - maybe because it has become irrelevant or because it has already been done (by someone else, or the work has been "piggybacked" in another task, time consumption counted for in another project, etc) -* Sometimes one has spent time on a task without completing it (maybe partly completed, maybe wasted some time on it before marking it as "cancelled", etc), then one would like to create the journal entry but without marking it as complete. - -### Task management - -* A VEVENT linked up as a child to a VTODO means we've (tried to) allocate some time for doing the VTODO (hence "sticking" the task to the calendar). If the task isn't marked completed by the end of the event, the calendar system should point it out. The user should then either reschedule, procrastinate, cancel, mark it as completed, or mark it as partially done. - -* A VEVENT linked up as a parent to a VTODO means the VTODO needs to be completed before the event. Once the event has passed, the VTODO should probably be cancelled if it wasn't done yet. - -* A VTODO (A) linked up as a parent to another VTODO (B) means either that B is a subtask of A or that A depends on B. In either case, B needs to be completed before A can be completed. - -* DURATION (efficiently meaning DTSTART, when DUE is set) should be used for time estimates (this breaks with my previous usage of DTSTART as the earliest time I would expect starting to work on the task). In the case of child/parent tasks, DURATION should (probably?) only indicate the "independent" time usage - so the full estimate of the time consumption for the whole project is the sum of the duration of all the VTODOs in the project. This may be a bit silly, as it either means the DUE for the "root task" must be set almost at project start (though, it may make sense if planning things in a top-down fashion), or that the DTSTART for the "root task" must be set almost at the project end (may make sense when considering dependencies - the subtasks needs to be done first). - -* PRIORITY should indicate how important it is to do the task by the indicated DUE date/timestamp. If PRIORITY=1, then the task is extremely important AND the DUE is a hard deadline. PRIORITY=9 may mean either that DUE is a "fanciful wish" OR that the task should simply be cancelled if it's difficult to get it done prior to the DUE date. - -* The calendaring system should make it possible to sort tasks based on the ratio between duration and available time until due date, and show tasks that ought to be prioritized during the next few days. - -* The calendaring system should make some simple-stupid algorithm to predict the "load", how likely one is to manage the upcoming due dates. Some parameters can be given, i.e. that one expects to be able to spend 2 hours a day for this category of tasks during the next 30 days and that tasks with priority 7 or higher can be ignored. - -* If the upcoming task list is too daunting, it should be possible to semiautomatically procrastinate (move the due) upcoming items based on their priority. - -* Recurring tasks is still a potential problem. - -## New calendar-cli interface - -This section has been moved to a separate document, [NEW_CLI.md](NEW_CLI.md) - +This document has been moved into the kal project hosted at github. The new authorative version is available at https://github.com/tobixen/kal/blob/master/NEXT_LEVEL.md diff --git a/USER_GUIDE.md b/USER_GUIDE.md deleted file mode 100644 index b9dfd93..0000000 --- a/USER_GUIDE.md +++ /dev/null @@ -1,158 +0,0 @@ -# User guide for calendar-cli v1.0 - -The `kal` command is under heavy development, this document may not always be up-to-date. As of 2022-11, `kal` can do nearly all the things the old command `calendar-cli` can do. In the upcoming release 1.0 one is supposed to use `kal`, with `calendar-cli` being a deprecated legacy interface retained only for backward-compatibility. - -## Command structure - -Commands are on this format: - -```bash -kal --global-options command --command-options subcommand --subcommand-options -``` - -The most up-to-date documentation can always be found through `--help`, and it's outside the scope of this document to list all the options. - -```bash -kal --help -kal command --help -kal command subcommand --help -``` - -## Main commands - -* list-calendars - verify that it's possible to connect to the server(s) and show the calendar(s) selected -* add - for adding things to the calendar(s) -* select - for selecting, viewing, editing and deleting things from the calendar(s). - -## Convenience commands - -Those commands are made mostly for making `kal` more convenient to use. Many of the commands are optimized for the work flows of the primary author. I may eventually decide to "hide" the more obscure commands from the `--help` overview. (TODO: figure out if subcommands can be grouped in the help printed by click) - -* interactive set-task-attribs - go through all tasks that are missing categories, due date, priority, duration (technically, DTSTART) and ask interactively for values. -* interactive update-config - (TODO: NOT IMPLEMENTED YET). This one is not used by the primary author and is probably under-tested. Its primary intention is to make it easy for others to use the tool. -* agenda - list up some of the upcoming events plus some of the upcoming tasks - -## Global options - -The global options are for setting the connection parameters to the server and choosing what calendar(s) to operate at. Connection parameters may be typed in directly: - -* `--caldav-*` to set the server connection parameters -* `--calendar-*` to choose a calendar. If nothing is specified, the first calendar found will be utilized (on some calendar servers, this will be the default calendar). It's possible to specify those parameters multiple times. - -It's recommended to rather use a config file (though not yet supported as of 2022-10-09). Those options can be used for specifying a config file: - -* `--config-file` -* `--config-section` - -The default is to utilize the `default` section under `$HOME/.config/calendar.conf` Here is an example configuration file: - -```yaml ---- -work-calendar: - caldav_url: "http://acme.example.com/caldav/" - caldav_user: drjekyll - caldav_pass: pencilin - calendar_url: mycalendar -work-appointments: - inherits: work-calendar - calendar_url: mypatients -private-calendar: - caldav_url: "https://ecloud.global/remote.php/dav/" - caldav_user: myhyde - caldav_pass: hunter2 - calendar_name: goodgames -sinuous-deeds: - inherits: private-calendar - calendar_name: badgames -work: - contains: [ 'work-calendar', 'work-appointments' ] -private: - contains: [ 'privat-calendar', 'sinous-deeds' ] -``` - -(TODO: the example above haven't been tested) - -Multiple config sections can be specified, which may be useful for selecting things from multiple calendars. - -## Adding things to the calendar - -Generally it should be done like this: - -``` -kal add ical --ical-file=some_calendar_data.ics -kal add event --event-options 'New years party' '2022-12-31T17:00+8h' -kal add todo --todo-options 'Prepare for the new years party' -kal add journal --journal-options "Resume from the new years party" 2022-12-31 "It was awesome. Lots of delicous food and drinks. Lots of firework." -``` - -(journals not supported yet as of 2022-10-09) - -Most often, no options should be given to the command `add` - with the exception if one wants to add things to multiple calendars in one command. - -Most of the options given after the subcommand are for populating object properties like location, categories, geo, class, etc. - -## Selecting things from the calendar - -``` -kal select --selection-parameters select-command -``` - -It's usually a good idea to start with the select-command `list`, for instance: - -``` -kal select --todo --category computer-work list -``` - -Some calendar server implementations require `--todo` or `--event` to always be given when doing selects, others not. - -### Listing objects - -Events can either be output as ics, or through a template. - -The templating engine is built on top of the python `string.format()`. To learn the basics of `string.format()`, w3schools has some nice interactive thing on the web, https://www.w3schools.com/python/ref_string_format.asp - -Text fields can be accessed directly i.e. like this: - -``` -kal select --todo list --template='{SUMMARY} {DESCRIPTION} {LOCATION}' -``` - -Dates can be accessed through the dt property, and can be formatted using strftime format, like this: - -``` -kal select --event list --template='{DTSTART.dt:%F %H:%M:%S}: {SUMMARY}' -``` - -If a property is missing, the default is to insert an empty string - but it's also possible to put a default value like this: - -``` -kal select --event list --template='{DTSTART.dt:%F %H:%M:%S}: {SUMMARY:?(no summary given)?}' -``` - -It's even possible to make compounded defaults, like this: - -``` -kal select --todo list --template='{DUE:?{DTSTART.dt:?(Best effort)?}?:%F %H:%M:%S}: {SUMMARY:?(no summary given)?}' -``` - -One thing that may be particularly useful is to take out the UID fields. With UID one can be sure to delete exactly the right row: - -``` -kal select --todo list --template='{UID} {SUMMARY}' -``` - -### Printing a UID - -The subcommand `print-uid` will print out an UID. It's for convenience, the same can be achieved by doing a `select (...) --limit 1 list --template='{UID}'` - -### Editing and deleting objects - -``` -kal select --todo --uid=1234-5678-9abc delete -kal select --todo --category computer-work --start=2022-04-04 --end=2022-05-05 edit --complete ## not supported yet -kal select --todo --category computer-work --overdue edit --postpone=5d ## not supported yet - -## See also - -[NEW_CLI.md](NEW_CLI.md) is a longer, but possibly less up-to-date document containing some visions of the new `kal`-command. -[NEXT_LEVEL.md](NEXT_LEVEL.md) describes some of my visions on what a good calendaring system should be capable of, and does an attempt on mapping this down to the icalendar standard. |