commit - 156f6c0e5dbd2c8294d655e9629bf85d035a4167
commit + f5d1ee290d79975e95c0aac26e38520df9c6e64d
blob - 0fae9824069d3b6061b1ca17f025fe3aa55a5959
blob + 5adffabe31c23a01307f347b9b2303ec9b58b3a8
--- painlist
+++ painlist
#!/bin/sh
# simplistic pain list printer
# pesco 2016-2020, 2024; isc license
-#
-# reads issue items on stdin, one per line, not indented. items are arbitrary
-# text, rated by adding ">AxBxC<" anywhere on the line, where A,B,C,... are
-# rating numbers in arbitrary categories. any number of categories can be used.
-#
-# if a pattern argument is given, it is interpreted as an extended regular
-# expression to filter for. the -v option inverts the filter.
-#
-# empty lines and those containing only a shell-style comment (#) are ignored.
-# in-line comments are not recognized; this allows the use of hash-tags.
-#
-# the rating scale is always 1-9; 9 should always be used for the highest level.
-# coarser scales should be mapped to 1-9 by ignoring some levels; for instance,
-# use 1,3,5,7,9 for a 5-level scale. it is recommended to document a clear
-# meaning for each level to make rating easy and unambiguous.
-#
-# the value of a pain tag (">...<") is the geometric mean of the ratings.
-# an item can have multiple pain tags which are summed.
-#
-# the output sorts items by pain value. a solid line visualizes a configurable
-# threshold (default -t 6). a dotted line shows the weighted median (half of
-# total pain). higher-value items are shown in a brighter shade.
-#
-#
-# == EXTRA FEATURES ==
-#
-# it is suggested to use the following features only in specific circumstances
-# as indicated.
-#
-# - text in square brackets [...] at the beginning of a line is highlighted in
-# the output. this can be used for example to mark items with a planned time.
-#
-# - items can be marked for urgency after time T by adding a tag of the form "!T"
-# where T is given in (fractional) megaseconds after the Unix epoch. yes, it is
-# awkward, but also simple. how to convert using GNU date:
-#
-# $ when() { echo $(($(date +%s -d "$1") / 1e6)); }
-# $ when tomorrow
-# 1459.43703
-#
-# (hint: round to the first decimal, a day is 86.4ks)
-#
-# urgent items are displayed in red. use this feature to flag items before it
-# becomes too late to act on them.
-#
-# - items marked with a tag of the form "^T" will be ignored until time T. use
-# this for items that cannot or should not be acted on before the given time.
-#
-# - indented (non-comment) lines below an item are interpreted as items pending
-# completion of their parent. for each child, a green plus sign is appended
-# to the parent item. pending items are not shown themselves but count toward
-# the pain value of their parent. use this to account for but otherwise hide
-# items that strictly depend on the completion of another.
-
theta=6
nocolor=1
maxitems=0 # infinite
blob - /dev/null
blob + 82a1b1cf05812bd348ef2d9be44dc13e588c3cb3 (mode 644)
--- /dev/null
+++ README
+Handling TODO items with "pain lists"
+=======================================
+
+The 'painlist' program reads items (tasks/bugs/issues/...) on stdin,
+one per line, not indented. Items are arbitrary text, rated by
+adding ">AxBxC<" anywhere on the line, where A,B,C,... are rating
+numbers in arbitrary categories. Any number of categories can be
+used.
+
+If a non-option argument is given, it is interpreted as an extended
+regular expression to filter for. The -v option inverts the filter.
+
+Empty lines and those containing only a shell-style comment (#) are
+ignored. In-line comments are not recognized; this allows the use
+of hash-tags.
+
+the rating scale is always 1-9; 9 should always be used for the
+highest level. Coarser scales should be mapped to 1-9 by ignoring
+some levels; for instance, use 1,3,5,7,9 for a 5-level scale. It
+is recommended to document a clear meaning for each level to make
+rating easy and unambiguous.
+
+the value of a pain tag (">...<") is the geometric mean of the
+ratings. An item can have multiple pain tags which are summed.
+
+the output sorts items by pain value. A solid line visualizes a
+configurable threshold (default -t 6). A dotted line shows the
+weighted median (half of total pain). Higher-value items are shown
+in a brighter shade.
+
+
+EXTRA FEATURES
+----------------
+
+It is suggested to use the following features only in specific
+circumstances as indicated.
+
+- Text in square brackets [...] at the beginning of a line is
+ highlighted in the output. This can be used for example to mark
+ items with a planned time.
+
+- Items can be marked for urgency after time T by adding a tag of
+ the form "!T" where T is given in (fractional) megaseconds after
+ the Unix epoch. Yes, it is awkward, but also simple. How to
+ convert using GNU date:
+
+ $ when() { echo $(($(date +%s -d "$1") / 1e6)); }
+ $ when tomorrow
+ 1459.43703
+
+ (Hint: Round to the first decimal place, a day is 86.4ks.)
+
+ Urgent items are displayed in red. Use this feature to flag items
+ before it becomes too late to act on them.
+
+- Items marked with a tag of the form "^T" will be ignored until
+ time T. Use this for items that cannot or should not be acted
+ on before the given time.
+
+- Indented (non-comment) lines below an item are interpreted as
+ items pending completion of their parent. For each child, a green
+ plus sign is appended to the parent item. Pending items are not
+ shown themselves but count toward the pain value of their parent.
+ Use this to account for but otherwise hide items that strictly
+ depend on the completion of another.
+
+
+REFERENCES
+------------
+
+Daniel Cook, "Improving Bug Triage with User Pain", 2008
+https://lostgarden.home.blog/2008/05/20/improving-bug-triage-with-user-pain/
