Commit 971e9aa5 authored by Michał Góral's avatar Michał Góral

Update README.rst

parent 7709d7ff
Pipeline #56944222 passed with stage
in 1 minute and 19 seconds
......@@ -3,3 +3,98 @@ twc
TWC (TaskWarrior Curses) is curses frontend for task and TODO manager -
TaskWarrior.
Features
~~~~~~~~
* agendas - display several filters on a single screen simultaneously
(influenced by `org-mode <https:orgmode.org>`_)
* complex custom task presentation (HTML-like markup)
* tasks and sub-tasks grouping (influenced by
`taskwiki <https://github.com/tbabej/taskwiki>`_)
Introduction
~~~~~~~~~~~~
TWC works with a concept of "agendas" influenced and borrowed from the mighty
org-mode. Agenda is basically a complex view of several TaskWarrior filters
(called blocks) displayed on a single screen simultaneously. You can jump
between blocks and single tasks.
To add agenda, first create a configuration file inside
``~/.config/twc/config.py``. It is a regular Python file with exposed variable
``c`` which references a configuration object. You can add new blocks like that:
.. code:: python
c.add_block(
'My Agenda',
name='Next Tasks',
filter='status:pending'
sort='priority+,urgency-')
c.add_block(
'My Agenda',
name='Projects'
filter='-WAITING and (+BLOCKING or +BLOCKED) and -INSTANCE',
sort='project-,priority-,order+,urgency-'
fmt='* {description}<m name=info>{tags:>}</m>')
Task Format
~~~~~~~~~~~
Block's format is a mix of `Python's string format <https://docs.python.org/3/library/string.html#formatspec>`_
and HTML-like markup.
You can use any TaskWarrior's attribute name as format's placeholder and it will
be displayed if present.
Some additional markup can be added to the tasks. The following tags are
available:
* ``<m name="foo">``: changes foreground and background colors of surrounded
text. *name* is a name of color configuration, which can be changed in
config file via ``c.set_color(name, fg, bg)``.
* ``<sr left="[", right="]>``: surrounds text with *left* and *right*.
Keep in mind that no markup will be added if above tags surround empty text
(e.g. non-existent attribute).
Colors
~~~~~~
Colors of normal and focused items can be changed in config.py:
.. code:: python
c.set_color('name', fg, bg)
c.set_color('name-focus', fg, bg)
so focused items simply add ``-focus`` suffix to their color names.
Depending on your terminal capabilities, twc supports up to 256 colors palette.
Monochrome, 16-, 88- and 256-color terminals are supported. As a color name you
can use any of standard color values: *black, dark red, dark green, brown,
dark blue, dark magenta, dark cyan, light gray, dark gray, light red, light
green, yellow, light blue, light magenta, light cyan, white*. For terminals
which support that, you can also use other notations:
* #fcc: hex like HTML color;
* g40: decimal value: 40% of gray
* g#cc: hex value: 80% of gray
* h255: color number 255
Apart from color name, you can specify some text attributes, which should be
placed after comma. These attributes include *bold, underline, blink* and
*standout*. Color value can be omitted, in which case a default foreground or
background color for your terminal will be used.
License
~~~~~~~
TWC was created by Michał Góral.
TWC is free software, published under the terms of GNU GPL3 or any later
version. See LICENSE file for details.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment