Merge pull request #27 from der-lyse/hyperlinks

Add anchors and links to different parts of docs

Closes #10

.gitignore

@@ -20,6 +20,9 @@ doc/example-config
 doc/gen-example-config
 doc/generate
 doc/generate2
+doc/configcommands-linked.dsv
+doc/podboat-cmds-linked.dsv
+doc/keycmds-linked.dsv
 *.gcov
 *.gcno
 *.gcda

Makefile

@@ -132,7 +132,9 @@ clean-libfilter:
 clean-doc:
 	$(RM) -r doc/xhtml 
 	$(RM) doc/*.xml doc/*.1 doc/newsboat-cfgcmds.txt doc/podboat-cfgcmds.txt \
-		doc/newsboat-keycmds.txt doc/gen-example-config doc/generate doc/generate2
+		doc/newsboat-keycmds.txt doc/configcommands-linked.dsv \
+		doc/podboat-cmds-linked.dsv doc/keycmds-linked.dsv \
+		doc/gen-example-config doc/generate doc/generate2
 
 clean: clean-newsboat clean-podboat clean-libboat clean-libfilter clean-doc clean-librsspp
 	$(RM) $(STFLHDRS) xlicense.h
@@ -142,17 +144,28 @@ distclean: clean clean-mo test-clean profclean
 
 doc: doc/xhtml/newsboat.html doc/xhtml/faq.html doc/newsboat.1 doc/podboat.1
 
-doc/xhtml/newsboat.html: doc/newsboat.txt
+doc/xhtml/newsboat.html: doc/newsboat.txt doc/chapter-firststeps.txt doc/configcommands-linked.dsv \
+		doc/keycmds-linked.dsv doc/chapter-tagging.txt doc/chapter-snownews.txt \
+		doc/chapter-cmdline.txt doc/chapter-podcasts.txt doc/podboat-cmds-linked.dsv \
+		doc/chapter-password.txt
 	$(MKDIR) doc/xhtml
 	$(A2X) -f xhtml -D doc/xhtml doc/newsboat.txt
 	$(CHMOD) u+w doc/xhtml/docbook-xsl.css
+	echo "/* AsciiDoc's new tables have <p> inside <td> which wastes vertical space, so fix it */" >> doc/xhtml/docbook-xsl.css
+	echo "td > p { margin: 0; }" >> doc/xhtml/docbook-xsl.css
+	echo "td > p + p { margin-top: 0.5em; }" >> doc/xhtml/docbook-xsl.css
+	echo "td > pre { margin: 0; white-space: pre-wrap; }" >> doc/xhtml/docbook-xsl.css
 
 doc/xhtml/faq.html: doc/faq.txt
 	$(MKDIR) doc/xhtml
 	$(A2X) -f xhtml -D doc/xhtml doc/faq.txt
 	$(CHMOD) u+w doc/xhtml/docbook-xsl.css
+	echo "/* AsciiDoc's new tables have <p> inside <td> which wastes vertical space, so fix it */" >> doc/xhtml/docbook-xsl.css
+	echo "td > p { margin: 0; }" >> doc/xhtml/docbook-xsl.css
+	echo "td > p + p { margin-top: 0.5em; }" >> doc/xhtml/docbook-xsl.css
+	echo "td > pre { margin: 0; white-space: pre-wrap; }" >> doc/xhtml/docbook-xsl.css
 
-doc/generate: doc/generate.cpp
+doc/generate: doc/generate.cpp doc/split.h
 	$(CXX) $(CXXFLAGS) -o doc/generate doc/generate.cpp
 
 doc/newsboat-cfgcmds.txt: doc/generate doc/configcommands.dsv
@@ -164,21 +177,34 @@ doc/generate2: doc/generate2.cpp
 doc/newsboat-keycmds.txt: doc/generate2 doc/keycmds.dsv
 	doc/generate2 doc/keycmds.dsv > doc/newsboat-keycmds.txt
 
-doc/newsboat.1: doc/manpage-newsboat.txt doc/newsboat-cfgcmds.txt doc/newsboat-keycmds.txt
+doc/newsboat.1: doc/manpage-newsboat.txt doc/chapter-firststeps.txt doc/newsboat-cfgcmds.txt \
+		doc/newsboat-keycmds.txt doc/chapter-tagging.txt doc/chapter-snownews.txt \
+		doc/chapter-cmdline.txt
 	$(A2X) -f manpage doc/manpage-newsboat.txt
 
 doc/podboat-cfgcmds.txt: doc/generate doc/podboat-cmds.dsv
-	doc/generate doc/podboat-cmds.dsv > doc/podboat-cfgcmds.txt
+	doc/generate doc/podboat-cmds.dsv 'pb-' > doc/podboat-cfgcmds.txt
 
-doc/podboat.1: doc/manpage-podboat.txt doc/podboat-cfgcmds.txt
+doc/podboat.1: doc/manpage-podboat.txt doc/chapter-podcasts.txt doc/podboat-cfgcmds.txt
 	$(A2X) -f manpage doc/manpage-podboat.txt
 
-doc/gen-example-config: doc/gen-example-config.cpp
+doc/gen-example-config: doc/gen-example-config.cpp doc/split.h
 	$(CXX) $(CXXFLAGS) -o doc/gen-example-config doc/gen-example-config.cpp
 
 doc/example-config: doc/gen-example-config doc/configcommands.dsv
 	cat doc/configcommands.dsv | doc/gen-example-config > doc/example-config
 
+# add hyperlinks for every configuration command
+doc/configcommands-linked.dsv: doc/configcommands.dsv
+	sed -e 's/^\([^|]\+\)/[[\1]]<<\1,`\1`>>/' doc/configcommands.dsv > doc/configcommands-linked.dsv
+
+# add hyperlinks for every configuration command
+doc/podboat-cmds-linked.dsv: doc/podboat-cmds.dsv
+	sed -e 's/^\([^|]\+\)/[[\1]]<<\1,`\1`>>/' doc/podboat-cmds.dsv > doc/podboat-cmds-linked.dsv
+
+doc/keycmds-linked.dsv: doc/keycmds.dsv
+	sed -e 's/^\([^:]\+\)/[[\1]]<<\1,`\1`>>/' doc/keycmds.dsv > doc/keycmds-linked.dsv
+
 fmt:
 	astyle --suffix=none --style=java --indent=tab --indent-classes *.cpp include/*.h src/*.cpp rss/*.{cpp,h} test/*.cpp
 

doc/chapter-cmdline.txt

@@ -5,32 +5,32 @@ advanced users.
 
 To start the commandline, type ":". You will see a ":" prompt at the bottom of
 the screen, similar to tools like vi(m) or mutt. You can now enter commands.
-Pressing the return key executes the command (possibly giving feedback to the
+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" configuration variable.
-To disable history saving, set the history-limit to 0.
+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 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
+names of commandline commands. By pressing the "Tab" key, newsboat will try to
 automatically complete your command. If there is more than one possible
-completion, you can subsequently press the TAB key to cycle through all
+completion, you can subsequently press the "Tab" key to cycle through all
 results. If no match is found, no suggestion will be inserted into the
-commandline. For the "set" command, the completion also works for configuration
+commandline. For the <<cmd-set,`set`>> command, the completion also works for configuration
 variable names.
 
-In addition, some common key combination such as Ctrl-G (to cancel input),
-Ctrl-K (to delete text from the cursor position to the end of line), Ctrl-U (to
-clear the whole line) and Ctrl-W (to delete the word before the current cursor
+In addition, some common key combination such as "Ctrl-G" (to cancel input),
+"Ctrl-K" (to delete text from the cursor position to the end of line), "Ctrl-U" (to
+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,
+'\~/.newsboat/history.cmdline' resp. '~/.newsboat/history.search'. By default,
 the last 100 entries are saved, but this can be configured (configuration
-variable history-limit) and also totally disabled (by setting said variable to
-0).
+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-firststeps.txt

@@ -1,5 +1,5 @@
 After you've installed newsboat, you can run it for the first time by typing
-"newsboat" on your command prompt. This will bring you the following message:
+`newsboat` on your command prompt. This will bring you the following message:
 
 	Error: no URLs configured. Please fill the file /home/ak/.newsboat/urls with RSS feed URLs or import an OPML file.
 
@@ -23,8 +23,8 @@ After you've installed newsboat, you can run it for the first time by typing
 
 This means that newsboat can't start without any configured feeds. To add
 feeds to newsboat, you can either add URLs to the configuration file
-$HOME/.newsboat/urls or you can import an OPML file by running "newsboat -i
-blogroll.opml". To manually add URLs, open the file with your favorite text
+'$HOME/.newsboat/urls' or you can import an OPML file by running `newsboat -i
+blogroll.opml`. To manually add URLs, open the file with your favorite text
 editor and add the URLs, one per line:
 
 	http://rss.cnn.com/rss/cnn_topstories.rss
@@ -36,14 +36,14 @@ provide the username/password in the following way:
 	http://username:password@hostname.domain.tld/feed.rss
 
 In order to protect username and password, make sure that
-$HOME/.newsboat/urls has the appropriate permissions. Newsboat also makes
+'$HOME/.newsboat/urls' has the appropriate permissions. Newsboat also makes
 sure that usernames and passwords within URLs aren't displayed in its user
 interface. In case there is a '@' in the username, you 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 '$HOME/.newsboat/urls' file:
 
 	file:///var/log/rss_eventlog.xml
 
@@ -54,7 +54,7 @@ download the currently selected feed. You can then select a feed you want to
 read, and by pressing "Enter", you can go to the article list for this feed.
 This works even while the downloading is still in progress.  You can now see
 the list of available articles by their title. A "N" on the left indicates that
-an article wasn't read yet. Pressing Enter brings you to the content of the
+an article wasn't read yet. Pressing "Enter" brings you to the content of the
 article. You can scroll through this text, and also run a browser (default:
 lynx) to view the complete article if the content is empty or just an abstract
 or a short description. Pressing "q" brings you back to the article list, and
@@ -65,7 +65,7 @@ Newsboat caches the article that it downloads. This means that when you start
 newsboat again and reload a feed, the old articles can still be read even if
 they aren't in the current RSS feeds anymore. Optionally you can configure how
 many articles shall be preserved by feed so that the article backlog doesn't
-grow endlessly (see "max-items" below).
+grow endlessly (see <<max-items,`max-items`>> below).
 
 Newsboat also uses a number of measures to preserve the users' and feed
 providers' bandwidth, by trying to avoid unnecessary feed downloads through the
@@ -75,20 +75,20 @@ to only send data if the feed has been updated by modification date/time or
 "ETag" header. This doesn't only make feed downloads for RSS feeds with no new
 updates faster, it also reduces the amount of transferred data per request.
 Conditional HTTP downloading can be optionally disabled per feed by using the
-"always-download" configuration command.
+<<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
+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
+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 ("\`") is evaluated as shell command, and its output is
+between two backticks (+\`+) 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
 system within the configuration. Backticks can be escaped with a backslash
-("\`"); in that case, they'll be replaced with a literal backtick in the
+(+\`+); in that case, they'll be replaced with a literal backtick in the
 configuration.
 
 Searching for articles is possible in newsboat, too. Just press the "/" key,
@@ -99,7 +99,7 @@ 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"
+'~/.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.
+`history-limit` to `0`.

doc/chapter-password.txt

@@ -6,16 +6,16 @@ command that evaluates to the user's password.
 This is useful if the user wants to share the configuration file online or
 store the password in a password manager or the systems keyring.
 
-For example when using the API for "The Old Reader",
-newsboat will first check the `oldreader-password` configuration variable,
+For example when using the <<_the_old_reader_support,API for "The Old Reader">>,
+newsboat will first check the <<oldreader-password,`oldreader-password`>> configuration variable,
 if this variable is set (meaning it's present and not empty),
 then its value will be used for authentication.
-If `oldreader-password` is not set (meaning it's not present or it's empty)
-but the `oldreader-passwordfile` configuration variable is set,
+If <<oldreader-password,`oldreader-password`>> is not set (meaning it's not present or it's empty)
+but the <<oldreader-passwordfile,`oldreader-passwordfile`>> configuration variable is set,
 then the first line of this file will be used as the password.
 This is, unless the file doesn't exist, is unreadable or its first line is empty,
 in those cases Newsboat will exit with an error.
-If `oldreader-passwordfile` is not set but `oldreader-passwordeval` is set,
+If <<oldreader-passwordfile,`oldreader-passwordfile`>> is not set but <<oldreader-passwordeval,`oldreader-passwordeval`>> is set,
 then the command will be evaluated and the first line of the result will be
 used as the password.
 This is, unless the first line of the result's string is empty,
@@ -24,8 +24,8 @@ Newsboat will ignore the exit status of the command,
 however it will wait for the command to exit.
 The command's output to stderr will be ignored by Newsboat and forwarded to
 the user, the output to stdout on the other hand will never be printed.
-If neither `oldreader-password`, `oldreader-passwordfile` nor
-`oldreader-passwordeval` are set, then Newsboat will ask for the user's
+If neither <<oldreader-password,`oldreader-password`>>, <<oldreader-passwordfile,`oldreader-passwordfile`>> nor
+<<oldreader-passwordeval,`oldreader-passwordeval`>> are set, then Newsboat will ask for the user's
 password with an interactive prompt.
 The entered password will be used unless it is empty,
 in which case Newsboat will exit with an error.

doc/chapter-podcasts.txt

@@ -9,15 +9,15 @@ 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 file '$HOME/.newsboat/queue'.
 
-The user can then use the download manager "podboat" to download these files
+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
 package, and features a look and feel very close to the one of newsboat. It
 also shares the same configuration file.
 
 Podcasts that have been downloaded but haven't been played yet remain in the
 queue but are marked as downloaded. You can remove them by purging them from
-the queue with the 'P' key. After you've played a file and close podboat, it
+the queue with the "P" key. After you've played a file and close podboat, it
 will be removed from the queue. The downloaded file remains on the
 filesystem.

doc/chapter-snownews.txt

@@ -8,21 +8,21 @@ 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:
+'~/.newsboat/urls' file configuration lines like the following ones:
 
 	exec:~/bin/execurl-script
 	filter:~/bin/filter-script:http://some.test/url
 
 The first line shows how to add an execurl script to your configuration: start
-the line with "exec:" and then immediately append the path of the script that
+the line with `exec:` and then immediately append the path of the script that
 shall be executed.  If this script requires additional parameters, simply use
 quotes:
 
 	"exec:~/bin/execurl-script param1 param2"
 
 The second line shows how to add a filter script to your configuration: start
-the line with "filter:", then immediately append the path of the script, then
-append a colon (":"), and then append the URL of the file that shall be fed to
+the line with `filter:`, then immediately append the path of the script, then
+append a colon (`:`), and then append the URL of the file that shall be fed to
 the script. Again, if the script requires any parameters, simply quote:
 
 	"filter:~/bin/filter-script param1 param2:http://url/foobar"

doc/chapter-tagging.txt

@@ -3,10 +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
+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
+quotes (`"`) around the tag (see example below). An example '~/.newsboat/urls'
 file may look like this:
 
 	http://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff"
@@ -19,13 +19,13 @@ a tag. When you select the tag "news", you will see all three RSS feeds. Pressin
 http://blog.fefe.de/rss.xml?html RSS feed. Pressing "^T" clears the current tag,
 and again shows all RSS feeds, regardless of their assigned tags.
 
-A special type of tag are tags that start with the tilde character ("\~"). When such
-a tag is found, the feed title is set to the tag name (excluding the \~ character).
+A special type of tag are tags that start with the tilde character (`~`). When such
+a tag is found, the feed title is set to the tag name (excluding the `~` character).
 With this feature, you can give feeds any title you want in your feed list:
 
 	http://rss.orf.at/news.xml "~ORF News"
 
-Another special type of tag are tags that start with the exclamation mark. When 
+Another special type of tag are tags that start with the exclamation mark (`!`). When
 such a tag is found, the feed is hidden from the regular list of feeds and its 
 content can only be found through a query feed.