From 80c169c4cc898684a9cee6a332ab5714de39049a Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Sun, 3 Apr 2016 17:29:26 -0400 Subject: [PATCH] Docs: Replaced 'keyword' with 'hint' --- doc/grammar.txt | 11 ++++++----- doc/project.txt | 16 +++++++++------- doc/rules.txt | 45 ++++++++++++++++++++++++++++++++------------- 3 files changed, 47 insertions(+), 25 deletions(-) diff --git a/doc/grammar.txt b/doc/grammar.txt index 86a1f7bf..567b2f5a 100644 --- a/doc/grammar.txt +++ b/doc/grammar.txt @@ -100,16 +100,15 @@ entity, for example: Tags must be quoted if they contains spaces. -Keywords --------- -There are built-in and custom keywords, that look like this: +Hints +----- +There are built-in and custom hints, that look like this: :fill - :quiet They begin with a colon, and are heuristics for Timewarrior. They can override feedback (:quiet) or offer guidance on how to create an interval (:fill). The -supported keywords are: +supported hints are: :fill Fill in gap :backfill Fill in gap, backwards only @@ -117,6 +116,8 @@ supported keywords are: :noreport Prevent the interval being reported :quiet No feedback :x User defined + :week Macro that means 'this week' + :debug Turns on debugging mode --- Raw Notes --- diff --git a/doc/project.txt b/doc/project.txt index b5863576..919fa877 100644 --- a/doc/project.txt +++ b/doc/project.txt @@ -65,13 +65,15 @@ however, both 'tag1' and 'tag2' are defined with the 'overlap' metadata, then there will not be an automatic stop for 'tag1'. -Macros ------- -A macro is a keyword that can take arguments, and expands to a set of one or -more other timew commands, with some dynamic aspect. For example, the macro -named 'staff meeting' could be an interval that is on Wednesdays at 10:00, and -has a set of associated tags. This would then create an appropriately tagged -interval. +Hints +----- +There are built-in hints, that influence processing. For example, ':debug' puts +the program in debug mode, and ':fill' indicates to a 'track' command that you +wish to fill in the available time. Another hint, ':week' means that a command +should only affect the last week. + +There are user-defined hints, that can act as macros⁄aliases, for example the +':staff' hint could mean a 'Staff Meeting' and 'Admin' tag set. Commands diff --git a/doc/rules.txt b/doc/rules.txt index f3f4a993..7d24c010 100644 --- a/doc/rules.txt +++ b/doc/rules.txt @@ -169,7 +169,7 @@ The hierarchy and 'configuration' rule will suupercede these. Rule Type: Theme ----------------------- +---------------- A color theme is defined by a rule, and consists of color definitions for various report and feedback elements: @@ -187,6 +187,37 @@ The palette group is a list (more is better) of themed colors for use when auto- coloring tags. +Rule Type: Hook +--------------- +While there may not be hooks in the traditional sense, with fixed arguments, +there will be rules that have the same role. Hook rules will allow an internal +event to trigger a rule that calls an external script, and passes an arbitrary +set of arguments. + +[Mechanism TBD] + + define rule hook on_start: + ... + + define rule hook on_stop: + ... + + define rule hook on_modify: + ... + + +Rules Type: Hint +---------------- +Hints may be defined using the rules system, to augment the built-in hints that +are used by almost every command. + + define hint staff: + tag 'Staff Meeting' + tag 'Admin' + +[More TBD] + + Built-in Functions ------------------ There are several built-in functions, which may be used by rules: @@ -203,18 +234,6 @@ There are several built-in functions, which may be used by rules: - Need to distinguish between regular time and over time, with different rates and limits. -- A nice feature would be to define a ':keyword' using the rules, which would - replace the notion of macros/aliases. - -- While there are no plans to add hooks, there could be rules that are triggered - by events in a similar manner: - - define rule on_start: - ... - - define rule on_stop: - ... - - Policy support involves things like: - warn after 40 hrs/wk - cut off tracking a tag at x hrs/wk