From 0d56d1c7904f0df2a182329d09b617a3b575ebf6 Mon Sep 17 00:00:00 2001 From: Thomas Lauf Date: Mon, 17 Apr 2023 08:09:33 +0200 Subject: [PATCH] Apply 'one sentence, one line' Signed-off-by: Thomas Lauf --- doc/rules.txt | 85 +++++++++++++++++++-------------------------------- 1 file changed, 32 insertions(+), 53 deletions(-) diff --git a/doc/rules.txt b/doc/rules.txt index d9460068..6c3c3ce2 100644 --- a/doc/rules.txt +++ b/doc/rules.txt @@ -1,31 +1,26 @@ Rules System ============ -The Timewarrior rule system reads your timewarrior.cfg file and -uses the combination of configuration settings and logic within to: +The Timewarrior rule system reads your timewarrior.cfg file and uses the combination of configuration settings and logic within to: - Define configuration and customization details - Define tags, exclusions, constraints - Define various policies On non-Unix systems config file is expected in ~/.timewarrior directory. -On Unix systems, if legacy ~/.timewarrior directory doesn't exist, config is -read from $XDG_CONFIG_HOME/timewarrior directory (if not specified, -$XDG_CONFIG_HOME defaults to ~/.config). +On Unix systems, if legacy ~/.timewarrior directory doesn't exist, config is read from $XDG_CONFIG_HOME/timewarrior directory (if not specified, $XDG_CONFIG_HOME defaults to ~/.config). -The rules are a mechanism to apply late-bound logic and data to various -functions. Whenever data changes, the rule system is run, which will run each -rule in turn, if it applies, going from top to bottom in the rules file. There -are no chained rules, but errors will be able to terminate rule processing and -program execution. +The rules are a mechanism to apply late-bound logic and data to various functions. +Whenever data changes, the rule system is run, which will run each +rule in turn, if it applies, going from top to bottom in the rules file. +There are no chained rules, but errors will be able to terminate rule processing and program execution. -As much functionality as possible is to be deferred to the rules system, which -will initially be minimal, but grow to become more capable. +As much functionality as possible is to be deferred to the rules system, which will initially be minimal, but grow to become more capable. Format ------ -The rules are written as UTF8 text in the timewarrior.cfg text file. Other -rules files may be included: +The rules are written as UTF8 text in the timewarrior.cfg text file. +Other rules files may be included: import /path/to/other/rule/file @@ -34,8 +29,7 @@ The syntax of rules is Python-like, in that indentation is significant. Types of Rules -------------- -There are several different types of rules, for example there is the rule that -defines all exclusions: +There are several different types of rules, for example there is the rule that defines all exclusions: define exclusions: ... @@ -60,8 +54,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 readily-interpreted form: +Because exclusions are resolved at run time, and only when needed, they should be stored in a readily-interpreted form: define exclusions: monday = <8:00:00 12:00:00-12:45:00 >17:30:00 @@ -74,17 +67,15 @@ be stored in a readily-interpreted form: 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 -track it like any other project. If you do not want to track that time, add an -exclusion for it. +If you want to track your lunch breaks, then you would make a tag for it, and track it like any other project. +If you do not want to track that time, add an exclusion for it. Rule Type: General ------------------ -There are rules triggered by changes to the data. In this example, rule 'one' -is a constraint that prevents the value 'foo' from exceeding three. It is -triggered by a change to 'foo', which is a DOM reference, and can prevent the -update by failing: +There are rules triggered by changes to the data. +In this example, rule 'one' is a constraint that prevents the value 'foo' from exceeding three. +It is triggered by a change to 'foo', which is a DOM reference, and can prevent the update by failing: define rules: one: @@ -97,8 +88,7 @@ Note that this rule is defined as applying to the tagset 'tag1'. Rule Type: Tag -------------- -A defined tag is a way to associate metadata with a tag, such as a description -and start/end dates for use: +A defined tag is a way to associate metadata with a tag, such as a description and start/end dates for use: define tags: "tag1": @@ -112,8 +102,7 @@ and start/end dates for use: Rule Type: Theme ---------------- -A color theme is defined by a rule, and consists of color definitions for -various report and feedback elements: +A color theme is defined by a rule, and consists of color definitions for various report and feedback elements: define theme: description = "A monochrome, 256-color theme" @@ -125,20 +114,16 @@ various report and feedback elements: color2 = "white on blue" ... -The palette group is a list (more is better) of themed colors for use when auto- -coloring tags. +The palette group is a list (more is better) of themed colors for use when auto-coloring tags. -There is only one theme namespace, so if multiple themes are imported, the last -one can override all the prior theme settings. This means themes can be layered, -but they would need to be designed for this. +There is only one theme namespace, so if multiple themes are imported, the last one can override all the prior theme settings. +This means themes can be layered, but they would need to be designed for this. 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. +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] @@ -154,8 +139,7 @@ set of arguments. on_modify: ... -These rules can run an external script and provide arguments, based on rules -DOM access: +These rules can run an external script and provide arguments, based on rules DOM access: define rules: on_modify: @@ -164,8 +148,7 @@ DOM access: Rules Type: Hint ---------------- -Hints may be defined using the rules system, to augment the built-in hints that -are used by almost every command. +Hints may be defined using the rules system, to augment the built-in hints that are used by almost every command. define hints: staff: @@ -177,8 +160,7 @@ are used by almost every command. --- Raw Notes --- -- Need to distinguish between regular time and over time, with different rates - and limits. +- Need to distinguish between regular time and over time, with different rates and limits. - Policy support involves things like: - warn after 40 hrs/wk @@ -186,8 +168,7 @@ are used by almost every command. - auto-tag intervals that exceed 40 hrs/wk - auto-tag intervals during exclusion time -- Need to distinguish between rules that will be supported at 1.0.0, and the - long term enhancements. +- Need to distinguish between rules that will be supported at 1.0.0, and the long term enhancements. - There will need to be several built-in functions, for use by rules: @@ -198,12 +179,10 @@ are used by almost every command. These are not good examples. -- Need reports to help users doing fixed-rate work - finding the longest task - for example. +- Need reports to help users doing fixed-rate work - finding the longest task for example. -- If an interval has more than one tag with a defined color, and is being - rendered, then use the first tag color. It doesn't really matter which. - -- Use display granularity/resolution to see more or less details. This would - combine nicely with a tag hierarchy. (Tomas Babej) +- If an interval has more than one tag with a defined color, and is being rendered, then use the first tag color. + It doesn't really matter which. +- Use display granularity/resolution to see more or less details. + This would combine nicely with a tag hierarchy. (Tomas Babej)