From f3930ae4c72c40df10de240990961b9c39659c5e Mon Sep 17 00:00:00 2001
From: Marty Oehme <contact@martyoeh.me>
Date: Mon, 7 Apr 2025 11:31:40 +0200
Subject: [PATCH] doc: Add configuration description

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 49 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index e8203f9..67a5e17 100644
--- a/README.md
+++ b/README.md
@@ -14,13 +14,6 @@ to let you see that there exists a note file next time you view the task.
 
 Should just work as-is without additional configuration in most modern taskwarrior setups.[^moderntw]
 
-[^moderntw]: The script assumes your taskwarrior setup follows the XDG base directory suggestions. That means,
-taskrc in `$XDG_CONFIG_HOME/task/taskrc`, usually `~/.config/task/taskrc`. Furthermore, at the moment it
-assumes the taskwarrior _data_ residing in the `$XDG_DATA_HOME/task` directory. This will diverge from
-many taskwarrior setups still and can be set through the cli option `--task-data`. The idea is for future
-`topen` versions to recognize the task data directory from the taskrc file itself but this has not been
-implemented.
-
 Can be configured through environment variables or cli options, see below.
 
 Can be used as-is with the `topen` command or directly from taskwarrior by being aliased in your `taskrc`:
@@ -59,22 +52,59 @@ Only has [tasklib](https://github.com/GothenburgBitFactory/tasklib) as a depende
 
 ## Configuration
 
-```python
-TASK_RC = os.getenv("TASKRC", "~/.config/task/taskrc") # not implemented yet
-TASK_DATA_DIR = os.getenv("TASKDATA", "~/.local/share/task")
-TOPEN_DIR = os.getenv("TOPEN_DIR", "~/.local/share/task/notes")
-TOPEN_EXT = os.getenv("TOPEN_EXT", "md")
-TOPEN_ANNOT = os.getenv("TOPEN_ANNOT", "Note")
-TOPEN_EDITOR = os.getenv("EDITOR") or os.getenv("VISUAL", "nano")
-TOPEN_QUIET = os.getenv("TOPEN_QUIET", False)
+By default the script generally assumes your taskwarrior setup follows the XDG
+base directory suggestions.
+
+That means, taskrc in `$XDG_CONFIG_HOME/task/taskrc`, usually
+`~/.config/task/taskrc`. Furthermore, at the moment it assumes the taskwarrior
+_data_ residing in the `$XDG_DATA_HOME/task` directory. This may diverge from
+taskwarrior setups still.
+
+This program can be configured in 3 different ways: options set in your regular taskwarrior `taskrc` file,
+environment variables or options given on the command line.
+
+### Taskrc configuration
+
+All options can be changed directly in your taskrc file.
+This may be most useful for settings which do not change often for you,
+such as the note extension or notes directory.
+
+The following settings are supported:
+
+```ini
+data.location # used for the taskwarrior data directory
+notes.dir # set the notes directory itself
+notes.ext # set the note file extension
+notes.annot # set the annotation added to tasks with notes
+notes.editor # set the editor used to open notes
+notes.quiet # set topen to hide all verbose information during use
 ```
 
-These are all environment variables offered, needs improved documentation.
 <!-- TODO: IMPROVE DOC -->
-
 Ultimately the goal would probably be to support reading from a taskwarrior 'taskrc' file,
 which can then be optionally overwritten with env variables,
 which can then be optionally overwritten with cli options.
 
-This is not fully implemented -- we support the above environment variables
-and cli options, that's it.
+### Environment variables
+
+Each option can be changed through setting the corresponding environment variable.
+
+These are the same as the `taskrc` file options with a prepended `TOPEN_` and dots turned to underscores.
+
+The following settings are supported:
+
+```bash
+TASKRC= # taskwarrior config file location
+TASKDATA= # taskwarrior data directory location
+TOPEN_NOTES_DIR= # set the notes directory itself
+TOPEN_NOTES_EXT= # set the note file extension
+TOPEN_NOTES_ANNOT= # set the annotation added to tasks with notes
+TOPEN_NOTES_EDITOR= notes.editor # set the editor used to open notes
+TOPEN_NOTES_QUIET= # set topen to hide all verbose information during use
+```
+
+### CLI options
+
+Finally, each option can be set through the cli itself.
+
+To find out all the available options use `topen --help`.