Commit d38ac995 authored by Lysander Trischler's avatar Lysander Trischler

Document configuration file settings

parent bd2859b9
......@@ -122,6 +122,8 @@ TODO
* Everything in twtxt's config file, not in code.
* Define more colors and key bindings.
* Match ``[nick-colors]]`` by feed URLs using the ``[following]`` mapping
internally, but still keep nicks as keys.
* Ability to show the txt's raw text.
* Manage subscriptions.
......@@ -203,3 +205,163 @@ to evolve into conversations. So why not only have a continuous thread view?
So I decided to make my own solution. And that's the rabbit hole you can see
here. Congratulations.
Configuration
=============
First of all, ``tt`` makes use of the `XDG Base Directory Standard
<https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
However, there's a catch, too, which will be covered later. Having said that,
the configuration file is at ``$XDG_CONFIG_HOME/twtxt/config``, often this
results in *~/.config/twtxt/config*. It's the `exact same configuration file
the official twtxt reference implementation uses
<https://twtxt.readthedocs.io/en/latest/user/configuration.html>`_, too.
Whenever possible, ``tt`` reuses the already existing settings. That's why some
setting names seem to be inconsistent. This INI file has a couple of sections:
* ``[twtxt]``: The behavior of ``twtxt`` and ``tt`` is configured there.
* ``[following]``: Your subscriptions to twtxt feeds.
* ``[colors]``: Coloring scheme for ``tt``.
* ``[nick-colors]``: Coloring scheme for mentions in ``tt``.
``[twtxt]``
-----------
This section controls the general behavior and basic settings of both ``twtxt``
and ``tt``.
``nick``
++++++++
Your nick name you will be known in the twxt universe. If absent, it defaults
to your system's username in lowercase, as defined by the ``twtxt`` reference
implementation.
``twtfile``
+++++++++++
Absolute path to your local twtxt feed file. If the path is relative, it will
be made absolute relative to the placement of your configuration file. If
absent, it defaults to ``$XDG_CONFIG_HOME/twtxt/twtxt.txt``. That's what the
``twtxt`` reference implementation did, too.
``twturl``
++++++++++
Fully qualified HTTP or HTTPS URL to your public twtxt feed. Similar to the
``twtxt`` reference implementation, it doesn't have a default.
``cachefile``
+++++++++++++
Absolute path to your ``twtxt`` cache file. The cache file holds all the
downloaded feeds of your subscription feeds. If the path is relative, it will
be made absolute relative to the placement of your configuration file. If
absent, it defaults to ``$XDG_CONFIG_HOME/twtxt/cache``. Unfortunately, this
default location is not correct according to the `XDG Base Directory
Specification
<https://twtxt.readthedocs.io/en/latest/user/configuration.html>`_. It should
rather go in ``$XDG_CACHE_HOME/twtxt/cache`` instead. However, the official
``twtxt`` reference implementation put it there, so to be backwards-compatible,
we sadly need to follow this wrong location by default. However, you can
configure this path explicitly to be correct.
Please note, the file will usually receive a ``.db`` extension automatically.
Unfortunately, `due to technical limitations
<https://docs.python.org/3/library/shelve.html#shelve.open>`_ the suffix cannot
be controlled explicitly. Just be aware, that the file is probably called
*~/.config/twxt/cache.db* but configured here only as
``~/.config/twtxt/cache``.
``datafile``
++++++++++++
Absolute path to your ``tt`` data file. The data file currently only records
the read statuses of twts. But it will probably be extended to also contain
other information in the future. If the path is relative, it will be made
absolute relative to the placement of your configuration file. If absent, it
defaults to ``$XDG_DATA_HOME/twtxt/data``, which on a lot of systems often
expands to *~/.local/share/twtxt/data*.
Please note again, the file will usually receive a ``.db`` extension
automatically. Unfortunately, `due to technical limitations
<https://docs.python.org/3/library/shelve.html#shelve.open>`_ the suffix cannot
be controlled explicitly. Just be aware, that the file is probably called
*~/.local/share/twxt/data.db* but configured here only as
``~/.local/share/twtxt/data``.
Historically, the data file was located next to the config and cache files,
simply as *~/.config/twtxt/cache2.db*. It was renamed and moved to reflect its
actual purpose. If you happen to run a ``tt`` version prior to 2021-09-19 and
don't want to move it after a ``tt`` upgrade, you need to explicitly configure
the old path in your config.
``[following]``
---------------
This sections manages your subscriptions. The format is pretty simple: It maps
nicks to feed URLs.
``[colors]``
------------
This section holds the main color theme information for ``tt``. Each value must
be a tuple of foreground and background color. Both colors are separated by a
semicolon (``;``). For color names and styles, please refer to the `urwid
documentation
<http://urwid.org/manual/displayattributes.html#foreground-and-background-settings>`_.
Currently, ``tt`` only supports the 16 standard foreground and 8 background
colors. More fancy color modes will be added soon.
Default configuration::
[colors]
header = yellow; light blue
footer = yellow; dark blue
unread-normal = brown; black
unread-focus = black; brown
read-normal = white; black
read-focus = black; white
unfollowed-nick-normal = white; light red
unfollowed-nick-focus = yellow; dark red
mentioned-nick-normal = light magenta; black
mentioned-nick-focus = black; light magenta
subject-normal = dark red; black
subject-focus = black; dark red
link-normal = light blue,underline; black
link-focus = light blue,underline; white
The ``-normal`` suffix indicates a list entry which doesn't have a focus, the
``-focus`` suffix on the other hand will be applied, when the list entry is
selected.
``[nick-colors]``
-----------------
In this section you can customize how certain mentions and twt authors should
be rendered. Those settings map a nick to a fore- and background color. In
contrast to the ``[colors]`` section above, the background here is optional.
When focusing a twt, the fore- and backgorund colors are swapped. There is no
separate mechanism to come up with a completely different color schemes for
normal and focus states.
When rendering a nick, it is first checked, whether this ``[nick-colors]``
section customizes the coloring for that nick. Those colors will be used then.
Otherwise the settings from ``[colors]`` take effect instead. If you're
following the nick in question, ``mentioned-nick-focus`` or
``mentioned-nick-normal`` from ``[colors]`` will be taken, depending on wether
the entry has the focus or not. Unfollowed authors and mentions will use the
``unfollowed-nick-focus`` resp. ``unfollowed-nick-normal`` settings.
Distinguishing between followed and unfollowed people helps disovery of new
feeds.
This section might look like this::
[nick-colors]
prologic = dark blue
movq = dark green
lysetestneu = light green; light magenta
lyse = light green,bold
In the future the mechanism will be changed to actually match the configured
feed URL instead of simply the nicks. This way ``tt`` users cannot be tricked
when malicious parties mention wrong nick URL combinations.
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