diff --git a/README.rst b/README.rst index 3beb607..4691bd5 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ twtxt ~~~~~ -|pypi| |build| |coverage| |docs| |gitter| |license| +|pypi| |build| |coverage| |docs| |license| **twtxt** is a decentralised, minimalist microblogging service for hackers. @@ -59,10 +59,6 @@ twtxt is released under the MIT License. See the bundled LICENSE file for detail :target: https://coveralls.io/r/buckket/twtxt?branch=master :alt: Test coverage -.. |gitter| image:: https://img.shields.io/gitter/room/buckket/twtxt.svg?style=flat - :target: https://gitter.im/buckket/twtxt - :alt: Chat on gitter - .. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg?style=flat :target: https://raw.githubusercontent.com/buckket/twtxt/master/LICENSE :alt: Package license diff --git a/docs/index.rst b/docs/index.rst index ee1cd76..259403b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,11 +24,11 @@ User Guide user/configuration user/twtxtfile user/registry + user/discoverability Community --------- -- twtxt gitter chat: https://gitter.im/buckket/twtxt - twtxt IRC channel: **#twtxt** on `irc.freenode.net`_ API Reference diff --git a/docs/user/configuration.rst b/docs/user/configuration.rst index 78be395..43ee78a 100644 --- a/docs/user/configuration.rst +++ b/docs/user/configuration.rst @@ -3,7 +3,10 @@ Configuration ============= -twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it. On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration. OSX uses ``~/Library/Application Support/twtxt/config``. Consult :func:`click.get_app_dir` to find out the config directory for other operating systems. +twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it. +On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration. +On OSX it uses ``~/Library/Application Support/twtxt/config``. +Consult :func:`click.get_app_dir` to find out the config directory for other operating systems. Here’s an example ``conf`` file, showing every currently supported option: diff --git a/docs/user/discoverability.rst b/docs/user/discoverability.rst new file mode 100644 index 0000000..8166dfb --- /dev/null +++ b/docs/user/discoverability.rst @@ -0,0 +1,28 @@ +.. _discoverability: + +Discoverability +=============== + +Because of the decentral nature of twtxt it can be hard to find new peers to follow, or even know who is following one’s own feed. +The later being a problem because right now mentions only show up when you actively follow the feed the mention originated from. + +To solve this issue, besides the usage of :ref:`registries `, twtxt is using a specially crafted User-Agent string, when making outgoing HTTP requests. +This then allows other users to search their webserver’s log file for those strings and find out who is consuming their content. + +.. note:: + + Implementing a so called linkback mechanism to actively notify someone explicitly about incoming mentions is currently `being discussed on GitHub `_. + +The format twtxt is using is as follows: + +.. code:: + + twtxt/ (+; @) + +For example: + +.. code:: + + twtxt/1.2.3 (+https://example.com/twtxt.txt; @somebody) + +Other clients are encouraged to use the same format. diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index e2e1a93..236d07f 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -40,7 +40,7 @@ The quickstart wizard prompts for the following configuration values: - The desired location for your twtxt file (**) - The URL your twtxt file will be accessible from remotely (**) - If you want to disclose your identity. If True your nick and URL will be used in the User-Agent - header attribute when fetching other twtxt files via HTTP. + header attribute when fetching other twtxt files via HTTP, see :ref:`discoverability`. - If you want to follow the official twtxt news feed The configurations can easily be changed in the twtxt configuration file. See :ref:`configuration`. diff --git a/docs/user/registry.rst b/docs/user/registry.rst index 674cdb2..b8806fd 100644 --- a/docs/user/registry.rst +++ b/docs/user/registry.rst @@ -1,4 +1,4 @@ -.. registry: +.. _registry: Registry ======== diff --git a/docs/user/twtxtfile.rst b/docs/user/twtxtfile.rst index 2523c7a..5aeb73f 100644 --- a/docs/user/twtxtfile.rst +++ b/docs/user/twtxtfile.rst @@ -9,7 +9,7 @@ The location of the twtxt file is configured in the twtxt section in the configu Format specification -------------------- -The twtxt file contains one status per line, each of which is equipped with an RFC 3339 date-time string followed by a TAB character (\\t) to separate it from the actual text. A specific ordering of the statuses is not mandatory. +The twtxt file contains one status per line, each of which is equipped with an RFC 3339 date-time string (with or without UTC offset) followed by a TAB character (\\t) to separate it from the actual text. A specific ordering of the statuses is not mandatory. The file must be encoded with UTF-8 and must use LF (\\n) as line separators.