diff --git a/doc/examples.txt b/doc/examples.txt deleted file mode 100644 index 10a61cb3..00000000 --- a/doc/examples.txt +++ /dev/null @@ -1,235 +0,0 @@ -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. -