doc: use mandoc as source, pre-generate documentation

generate documentation in doc/ . Now there is no hard dependency on mandoc and
systems that don't have it can just copy the files for now.

9 files changed, 342 insertions, 0 deletions

diff --git a/doc/man/sfeed.1 b/doc/man/sfeed.1
new file mode 100644
index 0000000..1804833
--- /dev/null
+++ b/doc/man/sfeed.1
@@ -0,0 +1,53 @@
+.TH "SFEED" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed\fR
+\- simple RSS and Atom parser
+.SH "SYNOPSIS"
+.HP 6n
+\fBsfeed\fR
+[\fIsuffix\ string\fR]
+.SH "DESCRIPTION"
+\fBsfeed\fR
+reads RSS or Atom feed data (XML) from stdin. It writes the feed data in a
+tab-separated format to stdout.
+.SH "TAB-SEPARATED FORMAT FIELDS"
+The items are saved in a TSV-like format except newlines, tabs and
+backslash are escaped with \\ (\\n, \\t and \\\\). Carriage returns (\\r) are
+removed.
+.PP
+The order and format of the fields are:
+.TP 19n
+\fIitem timestamp\fR
+string, UNIX timestamp in GMT+0
+.TP 19n
+\fIitem timestamp\fR
+string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM
+.TP 19n
+\fIitem title\fR
+string
+.TP 19n
+\fIitem link\fR
+string
+.TP 19n
+\fIitem content\fR
+string
+.TP 19n
+\fIitem content\-type\fR
+.br
+string, "html" or "plain"
+.TP 19n
+\fIitem id\fR
+string
+.TP 19n
+\fIitem author\fR
+string
+.TP 19n
+\fIfeed type\fR
+string, "rss" or "atom"
+.SH "SEE ALSO"
+sh(1),
+sfeed_update(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
diff --git a/doc/man/sfeed_frames.1 b/doc/man/sfeed_frames.1
new file mode 100644
index 0000000..7bf3770
--- /dev/null
+++ b/doc/man/sfeed_frames.1
@@ -0,0 +1,52 @@
+.TH "SFEED_FRAMES" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_frames\fR
+\- formats a feeds file to HTML with frames
+.SH "SYNOPSIS"
+.HP 13n
+\fBsfeed_frames\fR
+[\fIdirectory\ path\fR]
+.SH "DESCRIPTION"
+\fBsfeed_frames\fR
+formats a feeds file (TSV) from
+sfeed_update(1)
+to HTML. It reads TSV data from stdin and writes HTML to the specified
+directory. For the exact TSV format see
+sfeed_update(1).
+.SH "OPTIONS"
+.TP 16n
+\fIdirectory path\fR
+Path to write files to, default is ".". On success the specified directory will
+contain the files:
+.PP
+.RS 16n
+.PD 0
+.TP 15n
+\fIindex.html:\fR
+this is the main HTML file referencing to the frames (items.html and
+menu.html).
+.PD
+.TP 15n
+\fIitems.html:\fR
+this contains all the items as HTML links to the local content.
+.TP 15n
+\fImenu.html:\fR
+menu frame which contains navigation "anchor" links to the feed names
+(in items.html).
+.PD 0
+.PP
+.RE
+.PD
+.SH "FILE STRUCTURE"
+Directory for each feed category in the format: path/feedname/itemname.html.
+The feedname and item names are normalized, whitespace characters are replaced
+with a \-, multiple whitespaces are replaced by a single \- and trailing
+whitespace will be removed.
+.SH "SEE ALSO"
+sfeed_plain(1),
+sfeed_update(1),
+sfeed(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
diff --git a/doc/man/sfeed_html.1 b/doc/man/sfeed_html.1
new file mode 100644
index 0000000..cfa3251
--- /dev/null
+++ b/doc/man/sfeed_html.1
@@ -0,0 +1,21 @@
+.TH "SFEED_HTML" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_html\fR
+\- formats a feeds file to HTML
+.SH "SYNOPSIS"
+.HP 11n
+\fBsfeed_html\fR
+.SH "DESCRIPTION"
+\fBsfeed_html\fR
+formats a feeds file (TSV) from
+sfeed_update(1)
+to HTML. It reads TSV data from stdin and writes HTML to stdout. For the exact TSV format see
+sfeed_update(1).
+.SH "SEE ALSO"
+sfeed_plain(1),
+sfeed_update(1),
+sfeed(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
diff --git a/doc/man/sfeed_opml_export.1 b/doc/man/sfeed_opml_export.1
new file mode 100644
index 0000000..0369b86
--- /dev/null
+++ b/doc/man/sfeed_opml_export.1
@@ -0,0 +1,16 @@
+.TH SFEED 1 sfeed\-0.9
+.SH NAME
+sfeed_opml_export \- generate an OPML file based on a sfeedrc config file
+.SH SYNOPSIS
+.B sfeed_opml_export
+.RB [configfile]
+.SH OPTIONS
+.TP
+.B [configfile]
+config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default (see FILES READ section for more information).
+.SH DESCRIPTION
+Parse the specified config file and output OPML XML data to stdout.
+.SH SEE ALSO
+.BR sfeed_update(1)
+.SH BUGS
+Please report them!
diff --git a/doc/man/sfeed_opml_import.1 b/doc/man/sfeed_opml_import.1
new file mode 100644
index 0000000..a1b5060
--- /dev/null
+++ b/doc/man/sfeed_opml_import.1
@@ -0,0 +1,11 @@
+.TH SFEED 1 sfeed\-0.9
+.SH NAME
+sfeed_opml_import \- generate a sfeedrc config file based on an OPML file
+.SH SYNOPSIS
+.B sfeed_opml_import
+.SH DESCRIPTION
+It reads the OPML XML data from stdin and writes the config file text to stdout.
+.SH SEE ALSO
+.BR sfeed_update(1)
+.SH BUGS
+Please report them!
diff --git a/doc/man/sfeed_plain.1 b/doc/man/sfeed_plain.1
new file mode 100644
index 0000000..5276db8
--- /dev/null
+++ b/doc/man/sfeed_plain.1
@@ -0,0 +1,23 @@
+.TH "SFEED_PLAIN" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_plain\fR
+\- formats a feeds file to plain text
+.SH "SYNOPSIS"
+.HP 12n
+\fBsfeed_plain\fR
+.SH "DESCRIPTION"
+\fBsfeed_plain\fR
+formats a feeds file (TSV) from
+sfeed_update(1)
+to plain text. It reads TSV data from stdin and writes formatted plain text to
+stdout. For the exact TSV format see
+sfeed_update(1).
+.SH "SEE ALSO"
+sfeed_html(1),
+sfeed_update(1),
+sfeed(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
+.sp
diff --git a/doc/man/sfeed_update.1 b/doc/man/sfeed_update.1
new file mode 100644
index 0000000..7760cf8
--- /dev/null
+++ b/doc/man/sfeed_update.1
@@ -0,0 +1,101 @@
+.TH "SFEED_UPDATE" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_update\fR
+\- update feeds and merge with old feeds
+.SH "SYNOPSIS"
+.HP 13n
+\fBsfeed_update\fR
+[\fIconfigfile\fR]
+.SH "DESCRIPTION"
+\fBsfeed_update\fR
+updates feeds and merges the new data with the previous feeds. This is the file
+$HOME/.sfeed/feeds by default.
+.SH "OPTIONS"
+.TP 19n
+\fIconfigfile\fR
+config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default
+see the
+\fIFILES READ\fR
+section for more information.
+.SH "TAB-SEPARATED FORMAT FIELDS"
+The items are saved in a TSV-like format except newlines, tabs and
+backslash are escaped with \\ (\\n, \\t and \\\\). Carriage returns (\\r) are
+removed.
+.PP
+The order and format of the fields are:
+.TP 19n
+\fIitem timestamp\fR
+string, UNIX timestamp in GMT+0
+.TP 19n
+\fIitem timestamp\fR
+string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM
+.TP 19n
+\fIitem title\fR
+string
+.TP 19n
+\fIitem link\fR
+string
+.TP 19n
+\fIitem content\fR
+string
+.TP 19n
+\fIitem content\-type\fR
+.br
+string, "html" or "plain"
+.TP 19n
+\fIitem id\fR
+string
+.TP 19n
+\fIitem author\fR
+string
+.TP 19n
+\fIfeed type\fR
+string, "rss" or "atom"
+.SH "EXTRA FIELDS"
+Extra fields added by sfeed_update:
+.TP 19n
+\fIfeed name\fR
+string
+.TP 19n
+\fIfeed url\fR
+string
+.TP 19n
+\fIitem baseurl site\fR
+string
+.SH "FILES READ"
+.TP 19n
+\fIsfeedrc\fR
+Config file, see the sfeedrc.example file for an example.
+This file is evaluated as a shellscript in sfeed_update.
+You can for example override the fetchfeed() function to
+use wget, fetch or an other download program or you can
+override the merge() function to change the merge logic.
+The function feeds() is called to fetch the feeds. By
+default the function feed() is executed as a parallel
+job to speedup updating.
+.SH "FILES WRITTEN"
+.TP 19n
+\fIfeeds\fR
+Tab-separated format containing all feeds.
+The sfeed_update script merges new items with this file.
+.TP 19n
+\fIfeeds.new\fR
+Temporary file used by sfeed_update to merge items.
+.SH "EXAMPLES"
+To update feeds and format the feeds file:
+.nf
+.sp
+.RS 0n
+sfeed_update "configfile"
+sfeed_plain < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.txt
+sfeed_html < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.html
+.RE
+.fi
+.SH "SEE ALSO"
+sh(1),
+sfeed_plain(1),
+sfeed_html(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
diff --git a/doc/man/sfeed_web.1 b/doc/man/sfeed_web.1
new file mode 100644
index 0000000..addfe6d
--- /dev/null
+++ b/doc/man/sfeed_web.1
@@ -0,0 +1,40 @@
+.TH "SFEED_WEB" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_web\fR
+\- finds urls to feeds from a HTML webpage
+.SH "SYNOPSIS"
+.HP 10n
+\fBsfeed_web\fR
+[\fIbaseurl\fR]
+.SH "DESCRIPTION"
+\fBsfeed_web\fR
+reads the HTML website as XML or HTML data from stdin and writes the found
+urls to stdout.
+.SH "OPTIONS"
+.TP 10n
+\fIbaseurl\fR
+optional base url to use for found feed urls that are relative.
+.SH "OUTPUT FORMAT"
+content\-type<space>url<newline>
+.TP 15n
+\fIcontent\-type\fR
+Usually application/atom+xml or application/rss+xml.
+.TP 15n
+\fIurl\fR
+Found url to the feed. If the url is relative and the baseurl option is
+specified then the url is changed accordingly.
+.SH "EXAMPLES"
+Get urls from xkcd website:
+.nf
+.sp
+.RS 0n
+wget http://www.xkcd.com -q -O - | sfeed_web "http://www.xkcd.com/"
+.RE
+.fi
+.SH "SEE ALSO"
+sh(1),
+sfeed_update(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>
diff --git a/doc/man/sfeed_xmlenc.1 b/doc/man/sfeed_xmlenc.1
new file mode 100644
index 0000000..e5c2f29
--- /dev/null
+++ b/doc/man/sfeed_xmlenc.1
@@ -0,0 +1,25 @@
+.TH "SFEED_XMLENC" "1" "December 25, 2014" "" "General Commands Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsfeed_xmlenc\fR
+\- get text\-encoding from XML
+.SH "SYNOPSIS"
+.HP 13n
+\fBsfeed_xmlenc\fR
+.SH "DESCRIPTION"
+\fBsfeed_xmlenc\fR
+reads XML data from stdin and writes the found text\-encoding to stdout.
+.SH "EXAMPLES"
+Get text\-encoding from xkcd Atom feed:
+.nf
+.sp
+.RS 0n
+wget http://www.xkcd.com/atom.xml -q -O - | sfeed_xmlenc
+.RE
+.fi
+.SH "SEE ALSO"
+sh(1),
+sfeed_update(1)
+.SH "AUTHORS"
+Hiltjo Posthuma <\fIhiltjo@codemadness.org\fR>