Use Cases ========= This document contains a set of use cases and expected behavior. This will gradually change into a feature spec. The use cases are grouped functionally: [1] Basic Usage [2] Reports [3] Exclusions [4] Tags [5] Fill [6] Configuration [1.1] Basic Usage: clock ------------------------ Using the 'start' and 'stop' commands without tags just records time intervals: $ timew start ... $ timew stop This results in a recorded interval with the 'default' tag. [1.2] Basic Usage: clock + tags ------------------------------- Using the 'start' and 'stop' commands with tags just records time intervals: $ timew start tag1 ... $ timew start tag2 ... $ timew stop This results in the 'tag1' interval being automatically stopped, and the new 'tag2' interval starting. The 'stop' command stops all tracking. As these tags are not defined, there is no additional metadata. [1.3] Basic Usage: no arguments ------------------------------- Simply running the command with no arguments will show any currently tracking interval, with associated tags: $ timew 2016-02-29 8:00:00 - now, 3:11:24 total, using 'tag1' If 'tag1' has a defined color, it is used here to color the 'tag1' string. [2.1] Reports: Summaries ------------------------ There are several time-based default reports which summarizes tracked time over preset periods: $ timew summary :day $ timew summary :week $ timew summary :month $ timew summary :quarter $ timew summary :year $ timew summary - $ timew summary [4.1] Tags: Non-overlapping --------------------------- With non-overlapping tags, starting an interval closeѕ and existing interval: $ timew start tag1 ... $ timew start tag2 The second command automatically stops tracking 'tag1'. [4.2] Tags: Combining --------------------- With non-overlapping tags, intervals can be controlled by adding and removing tags: $ timew start tag1 tag2 ... $ timew stop tag1 ... $ timew stop The 'stop' command subtracts tags, and subtracts all tags if none are specified which makes the above equivalent to: $ timew start tag1 tag2 ... $ tiemw start tag2 ... $ tiemw stop [5.1] Fill: Backfill -------------------- If the time is 12:13pm, the workday starts at 8:00am, and you have already tracked a 9am-10am meeting, then this command will automatically backfill the 8am-9am interval only: $ timew track 8am "Reading email" Similarly, this command will do the same thing: $ timew track 8:23am "Reading email" :backfill These two examples assume that there is no empty slot at the end of yesterday, because it would also be filled. Backfill involves looking backwards from the stated date/time, looking for an interval to define the start. Only when a range is bounded can :fill and :backfill determine the interval. [5.2] Fill: Fill (forwards) --------------------------- If a time range is bounded, then :fill can determine an end point, and fill the gap. For example: $ timew track today tag1 The 'today' is a bounded range, and this command will use 'tag1' for an interval that extends all day today. Similarly 'tomorrow', 'next week' are bounded. [5.3] Fill: Autofill -------------------- Given an exclusion that ends at 8am, and another that begins at 5pm (defining a work day), then the following commands need to be explained: $ timew track today ... This will create an open tracking interval starting at 8am, because of the lack of a specific start time, and the presence of configured exclusions. $ timew track 7:45am ... This will create an open tracking interval starting at 7:45am, because of the specific start time, which always overrides exclusions. This means is possible to track time that exists entirely within an exclusion, provided there is a specific start and stop time. [6.1] Configuration: Storing/accessing settings ----------------------------------------------- With a 'config' command, all configuration data will be accessible. The command: $ timew config name value Will result in an update to the configuration file: name = value Using the '.' character allows the rule to reflect hierarchical configuration data: $ timew config one.two.three four $ timew config one.two.five six Will construct the rule like this: one: two: three = four five = six The process of converting this structure to 'one.two.three four' is called normalizing. [6.2] Configuration: Running in debug mode ------------------------------------------ Running in debug mode reveals internal details that aid troubleshooting. To run in debug mode, add the ':debug' hint to the command line: $ timew ... :debug [6.3] Configuration: Running without generating output ------------------------------------------------------ Running in quiet mode prevents all feedback. This is useful for automation scripts. To run un quiet mode, add the ':quiet' hint to the command line: $ timew ... :quiet --- Raw Notes --- - Outline case for double-tracking, perhaps where a manager tracks the time of several employees. This would require that tracked time for a single tag has no overlaps, but allowing overlapping intervals might need configuration to allow this. - Suppose "last week" is 39 hours of nothing, and 1 hour of a meeting. The question becomes what do the following do: [1] $ timew track last week "paint the thing" [2] $ timew track last week "paint the thing" :fill Our choices are: [a] 39 hours of "paint the thing" filled around the 1 hour "meeting". [b] 40 hours of "paint the thing" overlapping with 1 hour "meeting" [c] 40 hours of "paint the thing", and the meeting is gone Consensus: [b], but configurable. - Given this scenario: Exclusion: ------) Exclusion: [---------- Inclusion: [-) Now: | Timeline: >--o---o---o---o---o---o---o---o---o---o---o---o---o--> 7 8 9 10 11 12 1 2 3 4 5 6 7 am pm $ timew track this morning :fill tag inc 8am - 9am # tag $ timew track this morning :fill :active tag inc 8am - 9am # tag inc 9:30am - # tag $ timew track today tag inc 8am - 9am # tag inc 9:30am - # tag $ timew track 8am - 9am tag inc 8am - 9am # tag $ timew start tag1 :fill inc 9:30am - # tag - Need example and handling for people with exclusions that are not based on a seven-day cycle. Example, I have have every other friday off. This should be a supported exclusion, not 26 exceptions.