From 55030dd01039d4c76bdbbe1b1c9bf31b3dad422d Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Thu, 7 Apr 2016 08:00:01 -0400 Subject: [PATCH] Docs: Removed \define\ command --- doc/data.txt | 15 ++++++++------- doc/dom.txt | 8 ++++++-- doc/examples.txt | 50 ++++++++++++++++++------------------------------ doc/grammar.txt | 15 +++------------ doc/intro.txt | 19 +++++++++--------- doc/project.txt | 2 +- doc/rules.txt | 28 ++------------------------- 7 files changed, 49 insertions(+), 88 deletions(-) diff --git a/doc/data.txt b/doc/data.txt index 5d6ab1f4..4eb4925d 100644 --- a/doc/data.txt +++ b/doc/data.txt @@ -38,7 +38,7 @@ Exclusions Exclusions are stored as configuration, and there are several commands that allow easy manipulation of this. Whenever an exclusion changes, the set of all exclusions are written to the data file. This is because all subsequent -inclusions are to be resolved against the active set of exlcusions. +inclusions are to be resolved against the active set of exclusions. Inclusions @@ -70,23 +70,22 @@ An example file looks like this: inc 2016-02-28T08:00:00 - 2016-02-28T12:00:00 # Upgrade Planning inc 2016-02-28T13:00:00 # Upgrade Presentation "ABCD Inc" -White space is ignored. Here we see a sect of exlcusions that define a work week +White space is ignored. Here we see a sect of exclusions that define a work week and a two inclusions, the first of which represents a four hour block of time with two tags 'Upgrade' and 'Planning'. The second inclusion is open ended, having only a start time (1pm), but three tags 'Upgrade', 'Presentation' and 'ABCD Inc'. The third tag is a quoted string because of the embedded space. An open-ended inclusion like this means that the tracking continues, but the -exlcusions prevent an excess time buildup of the 63 hours that compries the +exclusions prevent an excess time buildup of the 63 hours that comprise the weekend (Friday 5:30pm until Monday 8:30am). Data File Names --------------- -The data file names will have the year and month embedded, which acts as a -heuristic for filtering, keeps the data files small and therefore quicker to -manipulate, and eliminates the need for any sophisticated archiving. For -example: +The data file names will have the year and month numbers, which keeps the data +files small and therefore quicker to manipulate, eliminating the need for any +sophisticated archiving. For example: ~/.timewarrior/data/2016-02.data ~/.timewarrior/data/2016-03.data @@ -101,3 +100,5 @@ The undo stack will be stored as: --- Raw Notes --- +- Recurring inclusions: meetings + diff --git a/doc/dom.txt b/doc/dom.txt index 74f34ee3..2163e018 100644 --- a/doc/dom.txt +++ b/doc/dom.txt @@ -1,7 +1,7 @@ DOM - Document Object Model =========================== -Timewarrior needs DOM support, so that it can operate a 'get' command, and also -provide data access to rules. +Timewarrior needs DOM support, so that it can service a 'get' command and +provide data access to rules. Bothare important for extensions. Data to be Accessed @@ -45,3 +45,7 @@ All DOM references have this form: dom.gap.today ... +- The above needs to support overlapping tags. + +- The above needs to support totals. + diff --git a/doc/examples.txt b/doc/examples.txt index 5cedb598..788c6bb4 100644 --- a/doc/examples.txt +++ b/doc/examples.txt @@ -53,24 +53,13 @@ If 'tag1' has a defined color, it is used here to color the 'tag1' string. There are several time-based default reports which summaries tracked time over preset periods: - $ timew report day - $ timew report week - $ timew report month - $ timew report quarter - $ timew report year - $ timew report - - -[3.1] Exclusions: Work Week --------------------------- - - $ timew define day monday 8am - 12pm, 12:45pm - 5:30pm - $ timew define day tuesday 8am - 12pm, 12:45pm - 6:30pm - $ timew define day wednesday 8am - 12pm, 1:30pm - 5:30pm - $ timew define day thursday 8am - 12pm, 12:45pm - 5:30pm - $ timew define day friday 8am - 12pm, 12:45pm - 5:30pm - $ timew define day on 2016-01-02 - $ timew define day off 2016-01-01 + $ timew report summary :day + $ timew report summary :week + $ timew report summary :month + $ timew report summary :quarter + $ timew report summary :year + $ timew report summary - + $ timew report summary [5.1] Fill: Backfill @@ -141,13 +130,12 @@ data: Will construct the rule like this: - define configuration: - one: - two: - three = four - five = six + one: + two: + three = four + five = six -The process of converting this rule structure to 'one.two.three four' is called +The process of converting this structure to 'one.two.three four' is called normalizing. @@ -224,13 +212,13 @@ The above examples simply use ad-hoc tags, which is an undefined tag. They are simply used as tags, and have no metadata. Defining a tag allows it to have associated metadata: - $ timew define tag "tag1" - $ timew define tag "tag1" description "Description of tag1" - $ timew define tag "tag1" start 2016-01-01 - $ timew define tag "tag1" end 2016-06-30 - $ timew define tag "tag1" budget 20 hours per week - $ timew define tag "tag1" budget 400 hours total - $ timew define tag "tag1" overlap + $ timew config tag "tag1" + $ timew config tag "tag1" description "Description of tag1" + $ timew config tag "tag1" start 2016-01-01 + $ timew config tag "tag1" end 2016-06-30 + $ timew config tag "tag1" budget 20 hours per week + $ timew config tag "tag1" budget 400 hours total + $ timew config tag "tag1" overlap - Need to break all these out into separate sections, where each is discussed in sufficient detail to then generate user docs and code. diff --git a/doc/grammar.txt b/doc/grammar.txt index 83d890fc..e91f56a4 100644 --- a/doc/grammar.txt +++ b/doc/grammar.txt @@ -2,24 +2,15 @@ CLI Syntax ---------- The CLI shall have a well-defined and unambiguous grammar. + timew timew start|stop [] timew track [] timew clear | timew continue - timew - timew [] report - - timew define day - [, - ...] - timew define day on|off - - timew define tag description - timew define tag start|end - timew define tag budget per - timew define tag budget total - timew define tag overlap - timew define tag color + timew report [] + timew config [ []] timew undo timew tags [] diff --git a/doc/intro.txt b/doc/intro.txt index 9fb30f89..4c858a10 100644 --- a/doc/intro.txt +++ b/doc/intro.txt @@ -32,13 +32,14 @@ Or if you forgot a whole activity: $ timew track 8:00am - 8:30am Exercise $ timew start 8:30am Home Cleaning -More sophisticated use is possible if you have defined your work week: +More sophisticated use is possible if you have defined your work week with: - $ timew define day monday 9am - 5pm - $ timew define day tuesday 9am - 6pm - $ timew define day wednesday 9am - 5pm - $ timew define day thursday 9am - 5pm - $ timew define day friday 9am - 5pm + define exclusions: + monday = 8:00:00-12:00:00 12:45:00-17:30:00 + tuesday = 8:00:00-12:00:00 12:45:00-18:30:00 + wednesday = 8:00:00-12:00:00 13:30:00-17:30:00 + thursday = 8:00:00-12:00:00 12:45:00-17:30:00 + friday = 8:00:00-12:00:00 12:45:00-17:30:00 $ timew track yesterday Home Painting @@ -46,7 +47,7 @@ Once the work week is recorded, vague terms like 'yesterday' can be resolved into actual start/stop timestamps. If you define holidays, then it knows not to track time on those days: - $ timew define holidays en-US + import /path/to/holidays/holidays.en-US Furthermore, Timewarrior can fill in gaps. For example: @@ -65,8 +66,8 @@ And the 'ProjectB' tagged interval will range from 2pm - 3pm. Tags can have their own metadata, for example you can make a tag valid for a given time range: - $ timew define tag ProjectA end 2016-06-30 - $ timew define tag ProjectA budget 400 hours total + $ timew config tag ProjectA end 2016-06-30 + $ timew config tag ProjectA budget '400 hours total' This is managed by a rules system that can impose constraints. diff --git a/doc/project.txt b/doc/project.txt index be516e6d..6a36f7f9 100644 --- a/doc/project.txt +++ b/doc/project.txt @@ -82,7 +82,7 @@ Commands -------- The command set will include: - define Modify configuration + config Modify configuration track Record tracked time report Run a report undo Undo a change diff --git a/doc/rules.txt b/doc/rules.txt index 44ee4b5f..43d1b922 100644 --- a/doc/rules.txt +++ b/doc/rules.txt @@ -74,31 +74,7 @@ There are rules that will serve as hooks: Rule Type: Exclusions --------------------- Because exclusions are resolved at run time, and only when needed, they should -be stored in a form very close to the command line syntax, with no expansion. -For example: - - $ timew define monday 8am - 12pm, 12:45pm - 5:30pm - $ timew define tuesday 8am - 12pm, 12:45pm - 6:30pm - $ timew define wednesday 8am - 12pm, 1:30pm - 5:30pm - $ timew define thursday 8am - 12pm, 12:45pm - 5:30pm - $ timew define friday 8am - 12pm, 12:45pm - 5:30pm - -Will be stored in a rule, whose purpose is to return a set of exclusion -intervals: - - define exclusions: - monday = 8:00:00-12:00:00 12:45:00-17:30:00 - tuesday = 8:00:00-12:00:00 12:45:00-18:30:00 - wednesday = 8:00:00-12:00:00 13:30:00-17:30:00 - thursday = 8:00:00-12:00:00 12:45:00-17:30:00 - friday = 8:00:00-12:00:00 12:45:00-17:30:00 - -Additional exclusions include: - - $ timew define day on 2016-01-02 - $ timew define day off 2016-01-01 - -Yielding: +be stored in a readily-interpreted form: define exclusions: monday = 8:00:00-12:00:00 12:45:00-17:30:00 @@ -107,7 +83,7 @@ Yielding: thursday = 8:00:00-12:00:00 12:45:00-17:30:00 friday = 8:00:00-12:00:00 12:45:00-17:30:00 days: - 2016_01_01 = On + 2016_01_01 = Working 2016_01_02 = Off If you want to track your lunch breaks, then you would make a tag for it, and