commit f5d1ee290d79975e95c0aac26e38520df9c6e64d from: Sven M. Hallberg date: Sat Jun 08 13:16:41 2024 UTC move documentation to README commit - 156f6c0e5dbd2c8294d655e9629bf85d035a4167 commit + f5d1ee290d79975e95c0aac26e38520df9c6e64d blob - 0fae9824069d3b6061b1ca17f025fe3aa55a5959 blob + 5adffabe31c23a01307f347b9b2303ec9b58b3a8 --- painlist +++ painlist @@ -1,61 +1,7 @@ #!/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 @@ -0,0 +1,72 @@ +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/