From c61c37abf3b6236cd65690fe8a47bdcd9d66bc13 Mon Sep 17 00:00:00 2001 From: Hiltjo Posthuma Date: Fri, 2 Jan 2015 15:13:12 +0100 Subject: 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. --- Makefile | 6 +- README | 7 +- doc/html/man.css | 114 +++++++++++++++++++++++++++ doc/html/sfeed.1.html | 108 +++++++++++++++++++++++++ doc/html/sfeed_frames.1.html | 90 +++++++++++++++++++++ doc/html/sfeed_html.1.html | 66 ++++++++++++++++ doc/html/sfeed_opml_export.1.html | 60 ++++++++++++++ doc/html/sfeed_opml_import.1.html | 52 +++++++++++++ doc/html/sfeed_plain.1.html | 68 ++++++++++++++++ doc/html/sfeed_update.1.html | 160 ++++++++++++++++++++++++++++++++++++++ doc/html/sfeed_web.1.html | 92 ++++++++++++++++++++++ doc/html/sfeed_xmlenc.1.html | 72 +++++++++++++++++ doc/man/sfeed.1 | 53 +++++++++++++ doc/man/sfeed_frames.1 | 52 +++++++++++++ doc/man/sfeed_html.1 | 21 +++++ doc/man/sfeed_opml_export.1 | 16 ++++ doc/man/sfeed_opml_import.1 | 11 +++ doc/man/sfeed_plain.1 | 23 ++++++ doc/man/sfeed_update.1 | 101 ++++++++++++++++++++++++ doc/man/sfeed_web.1 | 40 ++++++++++ doc/man/sfeed_xmlenc.1 | 25 ++++++ 21 files changed, 1232 insertions(+), 5 deletions(-) create mode 100644 doc/html/man.css create mode 100644 doc/html/sfeed.1.html create mode 100644 doc/html/sfeed_frames.1.html create mode 100644 doc/html/sfeed_html.1.html create mode 100644 doc/html/sfeed_opml_export.1.html create mode 100644 doc/html/sfeed_opml_import.1.html create mode 100644 doc/html/sfeed_plain.1.html create mode 100644 doc/html/sfeed_update.1.html create mode 100644 doc/html/sfeed_web.1.html create mode 100644 doc/html/sfeed_xmlenc.1.html create mode 100644 doc/man/sfeed.1 create mode 100644 doc/man/sfeed_frames.1 create mode 100644 doc/man/sfeed_html.1 create mode 100644 doc/man/sfeed_opml_export.1 create mode 100644 doc/man/sfeed_opml_import.1 create mode 100644 doc/man/sfeed_plain.1 create mode 100644 doc/man/sfeed_update.1 create mode 100644 doc/man/sfeed_web.1 create mode 100644 doc/man/sfeed_xmlenc.1 diff --git a/Makefile b/Makefile index f09cc42..30adf77 100644 --- a/Makefile +++ b/Makefile @@ -76,16 +76,18 @@ dist: $(BIN) (cd release/${VERSION}; \ tar -czf ../../sfeed-${VERSION}.tar.gz .) +doc: doc-html doc-oldman + # man to HTML: make sure to copy the mandoc example stylesheet to # doc/html/man.css . doc-html: $(MAN1) mkdir -p doc/html - for m in $(MAN1); do mandoc -Thtml -Ostyle=man.css $$m > doc/html/$$m.html; done + for m in $(MAN1); do mandoc -Ios="" -Thtml -Ostyle=man.css $$m > doc/html/$$m.html; done # legacy man pages, if you want semantic mandoc pages just copy them. doc-oldman: $(MAN1) mkdir -p doc/man - for m in $(MAN1); do mandoc -Tman $$m > doc/man/$$m; done + for m in $(MAN1); do mandoc -Ios="" -Tman $$m > doc/man/$$m; done ${OBJ}: config.mk diff --git a/README b/README index 467faf2..b5ad626 100644 --- a/README +++ b/README @@ -9,9 +9,6 @@ Dependencies - C compiler (C99). - libc (recommended: C99 and POSIX >= 200809). -- mandoc for documentation: http://mdocml.bsd.lv/ . If your host - system doesn't have mandoc you can convert the pages to the legacy format - with mandoc -Tman (make doc-oldman). Optional dependencies @@ -26,6 +23,10 @@ Optional dependencies used by sfeed_update. If the text in your RSS/Atom feeds are already UTF-8 encoded then you don't need this. For an alternative minimal iconv implementation: http://git.etalabs.net/cgit/noxcuse/tree/src/iconv.c +- mandoc for documentation: http://mdocml.bsd.lv/ . If your host + system doesn't have mandoc you can copy the legacy man-pages from doc/man + to your $MANPATH. For the most up-to-date documentation you can convert + the pages to the legacy format with mandoc -Tman (make doc-oldman). Platforms tested diff --git a/doc/html/man.css b/doc/html/man.css new file mode 100644 index 0000000..905412b --- /dev/null +++ b/doc/html/man.css @@ -0,0 +1,114 @@ +/* $Id: example.style.css,v 1.54 2014/12/10 22:19:45 schwarze Exp $ */ +/* + * This is an example style-sheet provided for mandoc(1) and the -Thtml + * or -Txhtml output mode. + * It mimics the appearance of the legacy man.cgi output. + * See mdoc(7) and man(7) for macro explanations. + */ + +div.mandoc { min-width: 102ex; + width: 102ex; + font-family: monospace; } /* This is the outer node of all mandoc -T[x]html documents. */ +div.mandoc h1 { margin-bottom: 0ex; font-size: inherit; margin-left: -4ex; } /* Section header (Sh, SH). */ +div.mandoc h2 { margin-bottom: 0ex; font-size: inherit; margin-left: -2ex; } /* Sub-section header (Ss, SS). */ +div.mandoc table { width: 100%; margin-top: 0ex; margin-bottom: 0ex; } /* All tables. */ +div.mandoc td { vertical-align: top; } /* All table cells. */ +div.mandoc p { } /* Paragraph: Pp, Lp. */ +div.mandoc blockquote { margin-left: 5ex; margin-top: 0ex; margin-bottom: 0ex; } /* D1, Dl. */ +div.mandoc div.section { margin-bottom: 2ex; margin-left: 5ex; } /* Sections (Sh, SH). */ +div.mandoc div.subsection { } /* Sub-sections (Ss, SS). */ +div.mandoc table.synopsis { } /* SYNOPSIS section table. */ +div.mandoc table.foot { } /* Document footer. */ +div.mandoc td.foot-date { width: 50%; } /* Document footer: date. */ +div.mandoc td.foot-os { width: 50%; + text-align: right; } /* Document footer: OS/source. */ +div.mandoc table.head { } /* Document header. */ +div.mandoc td.head-ltitle { width: 10%; } /* Document header: left-title. */ +div.mandoc td.head-vol { width: 80%; + text-align: center; } /* Document header: volume. */ +div.mandoc td.head-rtitle { width: 10%; + text-align: right; } /* Document header: right-title. */ +div.mandoc .display { } /* All Bd, D1, Dl. */ +div.mandoc .list { } /* All Bl. */ +div.mandoc i { } /* Italic: BI, IB, I, (implicit). */ +div.mandoc b { } /* Bold: SB, BI, IB, BR, RB, B, (implicit). */ +div.mandoc small { } /* Small: SB, SM. */ +div.mandoc .emph { font-style: italic; font-weight: normal; } /* Emphasis: Em, Bl -emphasis. */ +div.mandoc .symb { font-style: normal; font-weight: bold; } /* Symbolic: Sy, Ms, Bf -symbolic. */ +div.mandoc .lit { font-style: normal; font-weight: normal; font-family: monospace; } /* Literal: Dl, Li, Ql, Bf -literal, Bl -literal, Bl -unfilled. */ +div.mandoc i.addr { font-weight: normal; } /* Address (Ad). */ +div.mandoc i.arg { font-weight: normal; } /* Command argument (Ar). */ +div.mandoc span.author { } /* Author name (An). */ +div.mandoc b.cmd { font-style: normal; } /* Command (Cm). */ +div.mandoc b.config { font-style: normal; } /* Config statement (Cd). */ +div.mandoc span.define { } /* Defines (Dv). */ +div.mandoc span.desc { } /* Nd. After em-dash. */ +div.mandoc b.diag { font-style: normal; } /* Diagnostic (Bl -diag). */ +div.mandoc span.env { } /* Environment variables (Ev). */ +div.mandoc span.errno { } /* Error string (Er). */ +div.mandoc i.farg { font-weight: normal; } /* Function argument (Fa, Fn). */ +div.mandoc i.file { font-weight: normal; } /* File (Pa). */ +div.mandoc b.flag { font-style: normal; } /* Flag (Fl, Cm). */ +div.mandoc b.fname { font-style: normal; } /* Function name (Fa, Fn, Rv). */ +div.mandoc i.ftype { font-weight: normal; } /* Function types (Ft, Fn). */ +div.mandoc b.includes { font-style: normal; } /* Header includes (In). */ +div.mandoc span.lib { } /* Library (Lb). */ +div.mandoc i.link-sec { font-weight: normal; } /* Section links (Sx). */ +div.mandoc b.macro { font-style: normal; } /* Macro-ish thing (Fd). */ +div.mandoc b.name { font-style: normal; } /* Name of utility (Nm). */ +div.mandoc span.opt { } /* Options (Op, Oo/Oc). */ +div.mandoc span.ref { } /* Citations (Rs). */ +div.mandoc span.ref-auth { } /* Reference author (%A). */ +div.mandoc i.ref-book { font-weight: normal; } /* Reference book (%B). */ +div.mandoc span.ref-city { } /* Reference city (%C). */ +div.mandoc span.ref-date { } /* Reference date (%D). */ +div.mandoc i.ref-issue { font-weight: normal; } /* Reference issuer/publisher (%I). */ +div.mandoc i.ref-jrnl { font-weight: normal; } /* Reference journal (%J). */ +div.mandoc span.ref-num { } /* Reference number (%N). */ +div.mandoc span.ref-opt { } /* Reference optionals (%O). */ +div.mandoc span.ref-page { } /* Reference page (%P). */ +div.mandoc span.ref-corp { } /* Reference corporate/foreign author (%Q). */ +div.mandoc span.ref-rep { } /* Reference report (%R). */ +div.mandoc span.ref-title { text-decoration: underline; } /* Reference title (%T). */ +div.mandoc span.ref-vol { } /* Reference volume (%V). */ +div.mandoc span.type { font-style: italic; font-weight: normal; } /* Variable types (Vt). */ +div.mandoc span.unix { } /* Unices (Ux, Ox, Nx, Fx, Bx, Bsx, Dx). */ +div.mandoc b.utility { font-style: normal; } /* Name of utility (Ex). */ +div.mandoc b.var { font-style: normal; } /* Variables (Rv). */ +div.mandoc a.link-ext { } /* Off-site link (Lk). */ +div.mandoc a.link-includes { } /* Include-file link (In). */ +div.mandoc a.link-mail { } /* Mailto links (Mt). */ +div.mandoc a.link-man { } /* Manual links (Xr). */ +div.mandoc a.link-ref { } /* Reference section links (%Q). */ +div.mandoc a.link-sec { } /* Section links (Sx). */ +div.mandoc dl.list-diag { } /* Formatting for lists. See mdoc(7). */ +div.mandoc dt.list-diag { } +div.mandoc dd.list-diag { } +div.mandoc dl.list-hang { } +div.mandoc dt.list-hang { } +div.mandoc dd.list-hang { } +div.mandoc dl.list-inset { } +div.mandoc dt.list-inset { } +div.mandoc dd.list-inset { } +div.mandoc dl.list-ohang { } +div.mandoc dt.list-ohang { } +div.mandoc dd.list-ohang { margin-left: 0ex; } +div.mandoc dl.list-tag { } +div.mandoc dt.list-tag { } +div.mandoc dd.list-tag { } +div.mandoc table.list-col { } +div.mandoc tr.list-col { } +div.mandoc td.list-col { } +div.mandoc ul.list-bul { list-style-type: disc; padding-left: 1em; } +div.mandoc li.list-bul { } +div.mandoc ul.list-dash { list-style-type: none; padding-left: 0em; } +div.mandoc li.list-dash:before { content: "\2014 "; } +div.mandoc ul.list-hyph { list-style-type: none; padding-left: 0em; } +div.mandoc li.list-hyph:before { content: "\2013 "; } +div.mandoc ul.list-item { list-style-type: none; padding-left: 0em; } +div.mandoc li.list-item { } +div.mandoc ol.list-enum { padding-left: 2em; } +div.mandoc li.list-enum { } +div.mandoc span.eqn { } /* Equation modes. See eqn(7). */ +div.mandoc table.tbl { } /* Table modes. See tbl(7). */ +div.mandoc div.spacer { margin: 1em 0; } diff --git a/doc/html/sfeed.1.html b/doc/html/sfeed.1.html new file mode 100644 index 0000000..09301fc --- /dev/null +++ b/doc/html/sfeed.1.html @@ -0,0 +1,108 @@ + + + + + + + +SFEED(1) + + +
+ + + + + + + + +
+SFEED(1) +General Commands Manual +SFEED(1)
+
+

NAME

sfeed — simple RSS and Atom parser
+
+

SYNOPSIS

+++ + + + + + +
+sfeed +[suffix string]
+
+
+

DESCRIPTION

sfeed reads RSS or Atom feed data (XML) from stdin. It writes the feed data in a tab-separated format to stdout.
+
+

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.
+
+The order and format of the fields are:
+
+item timestamp
+
+string, UNIX timestamp in GMT+0
+
+item timestamp
+
+string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM
+
+item title
+
+string
+
+item link
+
+string
+
+item content
+
+string
+
+item content-type
+
+string, "html" or "plain"
+
+item id
+
+string
+
+item author
+
+string
+
+feed type
+
+string, "rss" or "atom"
+
+
+
+

SEE ALSO

sh(1), sfeed_update(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_frames.1.html b/doc/html/sfeed_frames.1.html new file mode 100644 index 0000000..3825b35 --- /dev/null +++ b/doc/html/sfeed_frames.1.html @@ -0,0 +1,90 @@ + + + + + + + +SFEED_FRAMES(1) + + +
+ + + + + + + + +
+SFEED_FRAMES(1) +General Commands Manual +SFEED_FRAMES(1)
+
+

NAME

sfeed_frames — formats a feeds file to HTML with frames
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_frames +[directory path]
+
+
+

DESCRIPTION

sfeed_frames 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).
+
+

OPTIONS

+
+directory path
+
+Path to write files to, default is ".". On success the specified directory will contain the files:
+
+index.html:
+
+this is the main HTML file referencing to the frames (items.html and menu.html).
+
+items.html:
+
+this contains all the items as HTML links to the local content.
+
+menu.html:
+
+menu frame which contains navigation "anchor" links to the feed names (in items.html).
+
+
+
+
+
+

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.
+
+

SEE ALSO

sfeed_plain(1), sfeed_update(1), sfeed(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_html.1.html b/doc/html/sfeed_html.1.html new file mode 100644 index 0000000..5f042f5 --- /dev/null +++ b/doc/html/sfeed_html.1.html @@ -0,0 +1,66 @@ + + + + + + + +SFEED_HTML(1) + + +
+ + + + + + + + +
+SFEED_HTML(1) +General Commands Manual +SFEED_HTML(1)
+
+

NAME

sfeed_html — formats a feeds file to HTML
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_html +
+
+
+

DESCRIPTION

sfeed_html 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).
+
+

SEE ALSO

sfeed_plain(1), sfeed_update(1), sfeed(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_opml_export.1.html b/doc/html/sfeed_opml_export.1.html new file mode 100644 index 0000000..ddf081e --- /dev/null +++ b/doc/html/sfeed_opml_export.1.html @@ -0,0 +1,60 @@ + + + + + + + +SFEED(1) + + +
+ + + + + + + + +
+SFEED(1) +General Commands Manual +SFEED(1)
+
+

NAME

sfeed_opml_export - generate an OPML file based on a sfeedrc config file
+
+

SYNOPSIS

sfeed_opml_export [configfile]
+
+

OPTIONS

+
+[configfile]
+
+config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default (see FILES READ section for more information).
+
+
+
+

DESCRIPTION

Parse the specified config file and output OPML XML data to stdout.
+
+

SEE ALSO

sfeed_update(1)
+
+

BUGS

Please report them!
+ + + + + +
+sfeed-0.9 +
+
+ + + diff --git a/doc/html/sfeed_opml_import.1.html b/doc/html/sfeed_opml_import.1.html new file mode 100644 index 0000000..268b543 --- /dev/null +++ b/doc/html/sfeed_opml_import.1.html @@ -0,0 +1,52 @@ + + + + + + + +SFEED(1) + + +
+ + + + + + + + +
+SFEED(1) +General Commands Manual +SFEED(1)
+
+

NAME

sfeed_opml_import - generate a sfeedrc config file based on an OPML file
+
+

SYNOPSIS

sfeed_opml_import
+
+

DESCRIPTION

It reads the OPML XML data from stdin and writes the config file text to stdout.
+
+

SEE ALSO

sfeed_update(1)
+
+

BUGS

Please report them!
+ + + + + +
+sfeed-0.9 +
+
+ + + diff --git a/doc/html/sfeed_plain.1.html b/doc/html/sfeed_plain.1.html new file mode 100644 index 0000000..622376e --- /dev/null +++ b/doc/html/sfeed_plain.1.html @@ -0,0 +1,68 @@ + + + + + + + +SFEED_PLAIN(1) + + +
+ + + + + + + + +
+SFEED_PLAIN(1) +General Commands Manual +SFEED_PLAIN(1)
+
+

NAME

sfeed_plain — formats a feeds file to plain text
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_plain +
+
+
+

DESCRIPTION

sfeed_plain 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).
+
+

SEE ALSO

sfeed_html(1), sfeed_update(1), sfeed(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ 
+
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_update.1.html b/doc/html/sfeed_update.1.html new file mode 100644 index 0000000..7ed03c5 --- /dev/null +++ b/doc/html/sfeed_update.1.html @@ -0,0 +1,160 @@ + + + + + + + +SFEED_UPDATE(1) + + +
+ + + + + + + + +
+SFEED_UPDATE(1) +General Commands Manual +SFEED_UPDATE(1)
+
+

NAME

sfeed_update — update feeds and merge with old feeds
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_update +[configfile]
+
+
+

DESCRIPTION

sfeed_update updates feeds and merges the new data with the previous feeds. This is the file $HOME/.sfeed/feeds by default.
+
+

OPTIONS

+
+configfile
+
+config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default see the FILES READ section for more information.
+
+
+
+

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.
+
+The order and format of the fields are:
+
+item timestamp
+
+string, UNIX timestamp in GMT+0
+
+item timestamp
+
+string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM
+
+item title
+
+string
+
+item link
+
+string
+
+item content
+
+string
+
+item content-type
+
+string, "html" or "plain"
+
+item id
+
+string
+
+item author
+
+string
+
+feed type
+
+string, "rss" or "atom"
+
+
+
+

EXTRA FIELDS

Extra fields added by sfeed_update:
+
+feed name
+
+string
+
+feed url
+
+string
+
+item baseurl site
+
+string
+
+
+
+

FILES READ

+
+sfeedrc
+
+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.
+
+
+
+

FILES WRITTEN

+
+feeds
+
+Tab-separated format containing all feeds. The sfeed_update script merges new items with this file.
+
+feeds.new
+
+Temporary file used by sfeed_update to merge items.
+
+
+
+

EXAMPLES

To update feeds and format the feeds file:
+
+
+sfeed_update "configfile" 
+sfeed_plain < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.txt 
+sfeed_html < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.html
+
+
+

SEE ALSO

sh(1), sfeed_plain(1), sfeed_html(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_web.1.html b/doc/html/sfeed_web.1.html new file mode 100644 index 0000000..489c042 --- /dev/null +++ b/doc/html/sfeed_web.1.html @@ -0,0 +1,92 @@ + + + + + + + +SFEED_WEB(1) + + +
+ + + + + + + + +
+SFEED_WEB(1) +General Commands Manual +SFEED_WEB(1)
+
+

NAME

sfeed_web — finds urls to feeds from a HTML webpage
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_web +[baseurl]
+
+
+

DESCRIPTION

sfeed_web reads the HTML website as XML or HTML data from stdin and writes the found urls to stdout.
+
+

OPTIONS

+
+baseurl
+
+optional base url to use for found feed urls that are relative.
+
+
+
+

OUTPUT FORMAT

content-type<space>url<newline>
+
+content-type
+
+Usually application/atom+xml or application/rss+xml.
+
+url
+
+Found url to the feed. If the url is relative and the baseurl option is specified then the url is changed accordingly.
+
+
+
+

EXAMPLES

Get urls from xkcd website:
+
+
+wget http://www.xkcd.com -q -O - | sfeed_web "http://www.xkcd.com/"
+
+
+

SEE ALSO

sh(1), sfeed_update(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + diff --git a/doc/html/sfeed_xmlenc.1.html b/doc/html/sfeed_xmlenc.1.html new file mode 100644 index 0000000..87a2b60 --- /dev/null +++ b/doc/html/sfeed_xmlenc.1.html @@ -0,0 +1,72 @@ + + + + + + + +SFEED_XMLENC(1) + + +
+ + + + + + + + +
+SFEED_XMLENC(1) +General Commands Manual +SFEED_XMLENC(1)
+
+

NAME

sfeed_xmlenc — get text-encoding from XML
+
+

SYNOPSIS

+++ + + + + + +
+sfeed_xmlenc +
+
+
+

DESCRIPTION

sfeed_xmlenc reads XML data from stdin and writes the found text-encoding to stdout.
+
+

EXAMPLES

Get text-encoding from xkcd Atom feed:
+
+
+wget http://www.xkcd.com/atom.xml -q -O - | sfeed_xmlenc
+
+
+

SEE ALSO

sh(1), sfeed_update(1)
+
+

AUTHORS

Hiltjo Posthuma <hiltjo@codemadness.org>
+ + + + + + + +
+December 25, 2014 +
+
+ + + 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\-typeurl +.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> -- cgit v1.2.3