GothenburgBitFactory/timewarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/timewarrior.git synced 2025-07-07 20:06:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs: Removed \define\ command

Browse source
This commit is contained in:
Paul Beckingham 2016-04-07 08:00:01 -04:00
parent aed0d02c64
commit 55030dd010
7 changed files with 49 additions and 88 deletions
Download patch file Download diff file Expand all files Collapse all files

15
doc/data.txt
View file

@ -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

8
doc/dom.txt
View file

@ -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.

50
doc/examples.txt
View file

@ -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 <from> - <to>
$ 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.

15
doc/grammar.txt
View file

@ -2,24 +2,15 @@ CLI Syntax
----------
The CLI shall have a well-defined and unambiguous grammar.
timew
timew start|stop [<tagset>]
timew track <interval> [<tagset>]
timew clear <tagset>|<interval>
timew continue
timew
timew [<filter>] report <report>
timew define day <day> <start> - <end> [, <start> - <end> ...]
timew define day on|off <date>
timew define tag <tag> description <string>
timew define tag <tag> start|end <date>
timew define tag <tag> budget <number> <units> per <unit>
timew define tag <tag> budget <number> <units> total
timew define tag <tag> overlap
timew define tag <tag> color <color>
timew report <report> [<filter>]
timew config [<name> [<value>]]
timew undo
timew tags [<filter>]

19
doc/intro.txt
View file

@ -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.

2
doc/project.txt
View file

@ -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

28
doc/rules.txt
View file

@ -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