Merge pull request newsboat#909 from newsboat/feature/44-paths-followup

Docs: stop listing full paths in files

Author: Minoru

Makefile

@@ -177,7 +177,8 @@ doc/xhtml/newsboat.html: doc/newsboat.asciidoc doc/chapter-firststeps.asciidoc \
 		doc/chapter-tagging.asciidoc doc/chapter-snownews.asciidoc \
 		doc/chapter-cmdline.asciidoc doc/chapter-podcasts.asciidoc \
 		doc/podboat-cmds-linked.dsv doc/chapter-password.asciidoc \
-		doc/chapter-environment-variables.asciidoc
+		doc/chapter-environment-variables.asciidoc \
+		doc/chapter-files.asciidoc
 	$(MKDIR) doc/xhtml
 	$(ASCIIDOCTOR) --backend=html5 --destination-dir=doc/xhtml doc/newsboat.asciidoc
 
@@ -201,15 +202,17 @@ doc/$(NEWSBOAT).1: doc/manpage-newsboat.asciidoc doc/chapter-firststeps.asciidoc
 		doc/newsboat-cfgcmds.asciidoc doc/newsboat-keycmds.asciidoc \
 		doc/chapter-tagging.asciidoc doc/chapter-snownews.asciidoc \
 		doc/chapter-cmdline.asciidoc \
-		doc/chapter-environment-variables.asciidoc
+		doc/chapter-environment-variables.asciidoc \
+		doc/chapter-files.asciidoc
 	$(ASCIIDOCTOR) --backend=manpage doc/manpage-newsboat.asciidoc
 
 doc/podboat-cfgcmds.asciidoc: doc/generate doc/podboat-cmds.dsv
 	doc/generate doc/podboat-cmds.dsv 'pb-' > doc/podboat-cfgcmds.asciidoc
 
 doc/$(PODBOAT).1: doc/manpage-podboat.asciidoc doc/chapter-podcasts.asciidoc \
 		doc/podboat-cfgcmds.asciidoc \
-		doc/chapter-environment-variables.asciidoc
+		doc/chapter-environment-variables.asciidoc \
+		doc/chapter-files.asciidoc
 	$(ASCIIDOCTOR) --backend=manpage doc/manpage-podboat.asciidoc
 
 doc/gen-example-config: doc/gen-example-config.cpp doc/split.h

doc/chapter-cmdline.asciidoc

@@ -8,9 +8,10 @@ the screen, similar to tools like vi(m) or mutt. You can now enter commands.
 Pressing the "Enter" key executes the command (possibly giving feedback to the
 user) and closes the commandline. You can cancel entering commands by pressing
 the "Esc" key. The history of all the commands that you enter will be saved to
-_~/.newsboat/history.cmdline_. The backlog is limited to 100 entries by default,
-but can be influenced by setting the <<history-limit,`history-limit`>> configuration variable.
-To disable history saving, set the `history-limit` to `0`.
+the _history.cmdline_ file, stored next to the _cache.db_ file. The backlog is
+limited to 100 entries by default, but can be influenced by setting the
+<<history-limit,`history-limit`>> configuration variable. To disable history
+saving, set the `history-limit` to `0`.
 
 The commandline provides you with some help if you can't remember the full
 names of commandline commands. By pressing the "Tab" key, newsboat will try to
@@ -26,11 +27,11 @@ clear the whole line) and "Ctrl-W" (to delete the word before the current cursor
 position) were added.
 
 Please be aware that the input history of both the command line and the search
-functions are saved to the filesystems, to the files
-_~/.newsboat/history.cmdline_ resp. _~/.newsboat/history.search_. By default,
-the last 100 entries are saved, but this can be configured (configuration
-variable <<history-limit,`history-limit`>>) and also totally disabled (by setting said variable to
-`0`).
+functions are saved to the filesystems, to the files _history.cmdline_ resp.
+_history.search_ (stored next to the _cache.db_ file). By default, the last 100
+entries are saved, but this can be configured (configuration variable
+<<history-limit,`history-limit`>>) and also totally disabled (by setting said
+variable to `0`).
 
 Currently, the following command line commands are available:
 

doc/chapter-files.asciidoc

@@ -0,0 +1,22 @@
+By default, Newsboat stores all the files in a traditional Unix fashion, i.e.
+in the "dotdir" located at _~/.newsboat_. However, it also supports a modern
+way,
+https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification],
+which splits the files between the following locations:
+
+- _~/.local/share/newsboat/_
+- _~/.config/newsboat/_
+
+If these directories exist or the environment variables `$XDG_CONFIG_HOME` and
+`$XDG_DATA_HOME` are set, newsboat will use these directories, otherwise it
+will default to _~/.newsboat_ as its configuration directory.
+
+If you're currently using _~/.newsboat/_ but wish to migrate to XDG
+directories, you should move the files as follows:
+
+_config_, _urls_::
+        to _$HOME/.config/newsboat/_
+
+_cache.db_, _history.search_, _history.cmdline_, _queue_::
+        to _$HOME/.local/share/newsboat/_
+

doc/chapter-firststeps.asciidoc

@@ -48,7 +48,7 @@ need to write it as _%40_ instead so that it can be distinguished from the _@_
 that separates the username/password part from the hostname part.
 
 You can also configure local files as feeds, by prefixing the local path with
-`file://` and adding it to the _$HOME/.newsboat/urls_ file:
+`file://` and adding it to the _urls_ file:
 
 	file:///var/log/rss_eventlog.xml
 
@@ -88,12 +88,12 @@ Conditional HTTP downloading can be optionally disabled per feed by using the
 <<always-download,`always-download`>> configuration command.
 
 Several aspects of newsboat's behaviour can be configured via a configuration
-file, by default _$HOME/.newsboat/config_. This configuration file contains
-lines in the form `<config-command> <arg1> ...`.  The configuration file can
-also contain comments, which start with the `+#+` character and go as far as
-the end of line. If you need to enter a configuration argument that contains
-spaces, use quotes (`"`) around the whole argument. It's even possible to
-integrate the output of external commands into the configuration. The text
+file _config_, which is stored next to the _urls_ file. This configuration file
+contains lines in the form `<config-command> <arg1> ...`.  The configuration
+file can also contain comments, which start with the `+#+` character and go as
+far as the end of line. If you need to enter a configuration argument that
+contains spaces, use quotes (`"`) around the whole argument. It's even possible
+to integrate the output of external commands into the configuration. The text
 between two backticks (`{backtick}`) is evaluated as shell command, and its
 output is put on its place instead. This works like backtick evaluation in
 Bourne-compatible shells and allows users to use external information from the
@@ -109,8 +109,8 @@ all feeds will be searched. When you do a search from the article list of a
 feed, only the articles of the currently viewed feed are searched. When opening
 an article from a search result dialog, the search phrase is highlighted.
 
-The history of all your searches is saved to the filesystem, to
-_~/.newsboat/history.search_. By default, the last 100 search phrases are
-stored, but this limited can be influenced through the <<history-limit,`history-limit`>>
-configuration variable. To disable search history saving, simply set the
-`history-limit` to `0`.
+The history of all your searches is saved to the filesystem, to the
+_history.search_ file (stored next to the _cache.db_ file). By default, the
+last 100 search phrases are stored, but this limited can be influenced through
+the <<history-limit,`history-limit`>> configuration variable. To disable search
+history saving, simply set the `history-limit` to `0`.

doc/chapter-podcasts.asciidoc

@@ -9,7 +9,7 @@ information for every podcast item it finds in an RSS feed. Since version 2.0,
 it also recognizes and handles the Yahoo Media RSS extensions. What the user
 then can do is to add the podcast download URL to a download queue.
 Alternatively, newsboat can be configured to automatically do that. This
-queue is stored in the file _$HOME/.newsboat/queue_.
+queue is stored in the _queue_ file next to the _cache.db_ file.
 
 The user can then use the download manager `podboat` to download these files
 to a directory on the local filesystem. Podboat comes with the newsboat

doc/chapter-snownews.asciidoc

@@ -7,8 +7,8 @@ An "execurl" script can be any program that gets executed and whose output is
 interpreted as RSS feed, while "filter" scripts are fed with the content of a
 configured URL and whose output is interpreted as RSS feed.
 
-The configuration is simple and straight-forward. Just add to your
-_~/.newsboat/urls_ file configuration lines like the following ones:
+The configuration is simple and straight-forward. Just add to your _urls_ file
+configuration lines like the following ones:
 
 	exec:~/bin/execurl-script
 	filter:~/bin/filter-script:https://some.test/url

doc/chapter-tagging.asciidoc

@@ -3,11 +3,10 @@ RSS feeds. Every RSS feed can be assigned 0 or more tags. Within newsboat, you
 can then select to only show RSS feeds that match a certain tag. That makes it
 easy to categorize your feeds in a flexible and powerful way.
 
-Usually, the _~/.newsboat/urls_ file contains one RSS feed URL per line. To
-assign a tag to an RSS feed, simply attach it as a single word, separated by
-blanks such as space or tab. If the tag needs to contain spaces, you must use
-quotes (`"`) around the tag (see example below). An example _~/.newsboat/urls_
-file may look like this:
+Usually, the _urls_ file contains one RSS feed URL per line. To assign a tag to
+an RSS feed, simply attach it as a single word, separated by blanks such as
+space or tab. If the tag needs to contain spaces, you must use quotes (`"`)
+around the tag (see example below). An example _urls_ file may look like this:
 
 	https://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff"
 	https://rss.orf.at/news.xml news orf

doc/configcommands.dsv

@@ -9,7 +9,7 @@ bookmark-autopilot||[yes/no]||no||If set to `yes`, the configured bookmark comma
 bookmark-cmd||<command>||""||If set, then <command> will be used as bookmarking plugin. See the documentation on bookmarking for further information.||bookmark-cmd "~/bin/delicious-bookmark.sh"
 bookmark-interactive||[yes/no]||no||If set to `yes`, then the configured bookmark command is an interactive program.||bookmark-interactive yes
 browser||<command>||%BROWSER, otherwise lynx||Set the browser command to use when opening an article in the browser. If BROWSER environment variable is set, it will be used as the default browser, otherwise lynx will be used. Any occurrences of `%u` in <command> will be replaced by a URL in single quotes.||browser "w3m %u"
-cache-file||<path>||"~/.newsboat/cache.db"||This configuration option sets the cache file. This is especially useful if the filesystem of your home directory doesn't support proper locking (e.g. NFS).||cache-file "/tmp/testcache.db"
+cache-file||<path>||"~/.newsboat/cache.db" or "~/.local/share/cache.db" (see "Files" section)||This configuration option sets the cache file. This is especially useful if the filesystem of your home directory doesn't support proper locking (e.g. NFS).||cache-file "/tmp/testcache.db"
 cleanup-on-quit||[yes/no]||yes||If set to `yes`, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can't be found in the urls configuration file anymore.||cleanup-on-quit no
 color||<element> <fgcolor> <bgcolor> [<attribute> ...]||n/a||Set the foreground color, background color and optional attributes for a certain element.||color background white black
 confirm-exit||[yes/no]||no||If set to `yes`, then newsboat will ask for confirmation whether the user really wants to quit newsboat.||confirm-exit yes
@@ -129,7 +129,7 @@ ttrss-passwordfile||<path>||""||A more secure alternative to the above, by stori
 ttrss-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||ttrss-passwordeval "gpg --decrypt ~/.newsboat/ttrss-password.gpg"
 ttrss-url||<url>||""||Configures the URL where the Tiny Tiny RSS installation you want to use resides.||ttrss-url "https://example.com/ttrss/"
 unbind-key||<key> [<dialog>]||n/a||Unbind key <key>. This means that no operation is called when <key> is pressed. If you provide "-a" as <key>, all currently bound keys will become unbound. Optionally, you can specify a dialog (for a list of available dialogs, see `bind-key` above). If you specify one, the key binding will only be unbound for the specified dialog.||unbind-key R
-urls-source||<source>||"local"||This configuration command sets the source where URLs shall be retrieved from. By default, this is ~/.newsboat/urls. Alternatively, you can set it to `opml`, which enables newsboat's OPML online subscription mode, to `ttrss` which enables newsboat's Tiny Tiny RSS support, to `oldreader`, which enables newsboat's The Old Reader support, to `newsblur`, which enables NewsBlur support, or `feedhq` for FeedHQ support, or `ocnews` for ownCloud News support, or `inoreader` for Inoreader support. Query feed specifications will be read from the local urls file regardless of this setting.||urls-source "oldreader"
+urls-source||<source>||"local"||This configuration command sets the source where URLs shall be retrieved from. By default, this is the _urls_ file. Alternatively, you can set it to `opml`, which enables newsboat's OPML online subscription mode, to `ttrss` which enables newsboat's Tiny Tiny RSS support, to `oldreader`, which enables newsboat's The Old Reader support, to `newsblur`, which enables NewsBlur support, or `feedhq` for FeedHQ support, or `ocnews` for ownCloud News support, or `inoreader` for Inoreader support. Query feed specifications will be read from the local urls file regardless of this setting.||urls-source "oldreader"
 urlview-title-format||<format>||"%N %V - URLs"||Format of the title in URL view. See "Format Strings" section of Newsboat manual for details on available formats.||urlview-title-format "URLs"
 use-proxy||[yes/no]||no||If set to `yes`, then the configured proxy will be used for downloading the RSS feeds.||use-proxy yes
 user-agent||<string>||""||If set to a non-zero-length string, this value will be used as HTTP User-Agent header for all HTTP requests.||user-agent "Lynx/2.8.5rel.1 libwww-FM/2.14"

doc/faq.asciidoc

@@ -17,7 +17,7 @@ Convert octal numbers to decimal, and drop the leading zero. For example,
 == I want to have a feed that contains all unread articles of all feeds
 
 This is supported since Newsbeuter 0.7. All you need to do is add the following
-line to your +~/.newsboat/urls+ file:
+line to your _urls_ file:
 
 	"query:Unread Articles:unread = \"yes\""
 

doc/manpage-newsboat.asciidoc

@@ -128,26 +128,10 @@ _<number>_::
         Jump to the <number>th entry in the current dialog
 
 
-== XDG Base Directory Support
-
-Newsboat defaults to storing everything in _$HOME/.newsboat_ directory. If
-you prefer XDG, create _$HOME/.config/newsboat_ and
-_$HOME/.local/share/newsboat_ directories, and Newsboat will use them
-from there on.
-
-If you already have some files in _$HOME/.newsboat/_, move them as follows:
-
-_config_, _urls_::
-        to _$HOME/.config/newsboat/_
-
-_cache.db_, _history.search_, _history.cmdline_::
-        to _$HOME/.local/share/newsboat/_
-
-See also a corresponding section in podboat(1).
-
-
 == FILES
 
+include::chapter-files.asciidoc[]
+
 dotfiles::
         _$HOME/.newsboat/config_
 +