Docs: Add manual pages using ronn.

This adds several new manual pages to the project, ships them
using `dist` and has a simple target to recreate the new roff
files using the `ronn` utility: `make manpages`.

These man pages are still very crude and contain the absolute
minimum amount of information. I've attempted to cross link them
as much as is reasonable.

The telemetry API is documented in `telemetry(3)`. The important
functions themselves are `linked` with a ref link that should
make `man tm_create_record` (etc.) link to telemetry(3).

I attempted to make this pass `make distcheck` and `make install`
properly, but this should still be checked.

Makefile.am

@@ -14,6 +14,7 @@ DISTCHECK_CONFIGURE_FLAGS = \
 
 include $(top_srcdir)/build-aux/make/cflags.make
 include $(top_srcdir)/build-aux/make/ldflags.make
+include $(top_srcdir)/docs/local.mk
 include $(top_srcdir)/scripts/local.mk
 include $(top_srcdir)/src/local.mk
 include $(top_srcdir)/src/data/local.mk

README

@@ -30,9 +30,3 @@ Build dependencies
 - (optional) libsystemd, for syslog-style logging to the systemd journal, and
   socket/path activation of telemd by systemd.
 
-
-Generating HTML documentation
-=============================
-
-At toplevel, run 'doxygen docs/Doxyfile'. The documentation is generated in
-the docs/html/ directory.

docs/README.md

@@ -0,0 +1,13 @@
+
+## Notes on manual pages
+
+The manual pages are generated using `ronn(1)`. To recreate them,
+run `make manpages` in the toplevel  folder. If you want to edit
+the documentation for upstream changes, make sure to edit the `*.md`
+files and not the shipped nroff output files.
+
+
+## Generating HTML documentation
+
+At toplevel, run 'doxygen docs/Doxyfile'. The documentation is
+generated in the docs/html/ directory.

docs/local.mk

@@ -0,0 +1,23 @@
+MANPAGES = \
+	docs/man/telemctl.1 \
+	docs/man/telemd.1 \
+	docs/man/telem-record-gen.1 \
+	docs/man/telemetry.3 \
+	docs/man/telemetrics.conf.5
+
+MANLINKS = \
+	docs/man/tm_create_record.3 \
+	docs/man/tm_send_record.3 \
+	docs/man/tm_set_config_file.3 \
+	docs/man/tm_set_payload.3
+
+manpages:
+	for MANPAGE in $(MANPAGES); do \
+		ronn --roff < $${MANPAGE}.md > $${MANPAGE}; \
+		ronn --html < $${MANPAGE}.md > $${MANPAGE}.html; \
+	done
+
+dist_man_MANS = \
+	$(MANPAGES) $(MANLINKS)
+
+# vim: filetype=automake tabstop=8 shiftwidth=8 noexpandtab

docs/man/.gitignore

@@ -0,0 +1 @@
+*.html

docs/man/telem-record-gen.1

@@ -0,0 +1,81 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEM\-RECORD\-GEN" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelem\-record\-gen\fR \- Create custom telemetry record
+.
+.SH "SYNOPSIS"
+\fBtelem\-record\-gen\fR \fIoptions\fR
+.
+.SH "DESCRIPTION"
+Generate and attempt to send a telemetry record to \fBtelemd(1)\fR\. This program can be used to create a telemetry record from a shell script or from another program using e\.g\. \fBsystem()\fR\. The program connects to a local \fBtelemd(1)\fR daemon to spool the record for delivery to the actual collection service\.
+.
+.P
+The payload can be provided as standard input, as a file with the \fB\-\-payload\-file\fR option, or as a string argument with the \fB\-\-payload\fR option\. If neither the \fB\-\-payload\fR or \fB\-\-payload\-file\fR is provided, the payload is assumed to be on \fIstdin\fR\.
+.
+.P
+Each record is expected to have a class identifier, a record version number, and a severity level\. A class identifier is required to be provided\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help options\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the program version\.
+.
+.TP
+\fB\-f\fR, \fB\-\-config\-file\fR \fIfile\fR
+Path to configuration file (not implemented yet)\.
+.
+.TP
+\fB\-s\fR, \fB\-\-severity\fR
+Severity level (1\-4) \- (default 1)\.
+.
+.TP
+\fB\-c\fR, \fB\-\-class\fR
+Classification \fBlevel_1\fR/\fBlevel_2\fR/\fBlevel_3\fR\.
+.
+.TP
+\fB\-p\fR, \fB\-\-payload\fR \fIpayload\fR
+Record body (max size = 8k)\.
+.
+.TP
+\fB\-P\fR, \fB\-\-payload\-file\fR \fIfile\fR
+File to read payload from\.
+.
+.TP
+\fB\-R\fR, \fB\-\-record\-version\fR \fIversion\fR
+Version number for format of payload (default 1)\.
+.
+.SH "RETURN VALUES"
+0 on success\. A non\-zero exit code indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+

docs/man/telem-record-gen.1.md

@@ -0,0 +1,70 @@
+telem-record-gen(1) -- Create custom telemetry record
+=====================================================
+
+## SYNOPSIS
+
+`telem-record-gen` <options>
+
+## DESCRIPTION
+
+Generate and attempt to send a telemetry record to `telemd(1)`. This
+program can be used to create a telemetry record from a shell script
+or from another program using e.g. `system()`. The program connects
+to a local `telemd(1)` daemon to spool the record for delivery to
+the actual collection service.
+
+The payload can be provided as standard input, as a file with the
+`--payload-file` option, or as a string argument with the `--payload`
+option. If neither the `--payload` or `--payload-file` is provided,
+the payload is assumed to be on <stdin>.
+
+Each record is expected to have a class identifier, a record version
+number, and a severity level. A class identifier is required to be
+provided.
+
+## OPTIONS
+ * `-h`, `--help`:
+   Show help options.
+
+ * `-V`, `--version`:
+   Print the program version.
+
+ * `-f`, `--config-file` <file>:
+   Path to configuration file (not implemented yet).
+
+ * `-s`, `--severity`:
+   Severity level (1-4) - (default 1).
+
+ * `-c`, `--class`:
+   Classification `level_1`/`level_2`/`level_3`.
+
+ * `-p`, `--payload` <payload>:
+   Record body (max size = 8k).
+
+ * `-P`, `--payload-file` <file>:
+   File to read payload from.
+
+ * `-R`, `--record-version` <version>:
+   Version number for format of payload (default 1).
+
+## RETURN VALUES
+
+0 on success. A non-zero exit code indicates a failure occurred.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/

docs/man/telemctl.1

@@ -0,0 +1,58 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMCTL" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemctl\fR \- Telemetry service administration tool
+.
+.SH "SYNOPSIS"
+\fBtelemctl\fR
+.
+.P
+\fB/etc/telemetrics/opt\-out\fR
+.
+.SH "DESCRIPTION"
+Control actions for telemetry services\. The command can be used to start, restart, or stop \fBtelemd(1)\fR, or to opt\-in or opt\-out of telemetry delivery of records to a central telemetry service\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fBstart\fR|\fBstop\fR|\fBrestart\fR
+Starts, stops or restarts all running telemetry services\.
+.
+.TP
+\fBopt\-in\fR
+Opts in to telemetry, and starts telemetry services\. The opt\-out file \fB/etc/telemetrics/opt\-out\fR is removed\.
+.
+.TP
+\fBopt\-out\fR
+Opts out of telemetry, and stops telemetry services\. The opt\-out file \fB/etc/telemetrics/opt\-out\fR is created\.
+.
+.SH "RETURN VALUES"
+0 on success\. A non\-zero exit code indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+

docs/man/telemctl.1.md

@@ -0,0 +1,49 @@
+telemctl(1) -- Telemetry service administration tool
+====================================================
+
+## SYNOPSIS
+
+`telemctl`
+
+`/etc/telemetrics/opt-out`
+
+## DESCRIPTION
+
+Control actions for telemetry services. The command can be used to start,
+restart, or stop `telemd(1)`, or to opt-in or opt-out of telemetry delivery
+of records to a central telemetry service.
+
+## OPTIONS
+
+ * `start`|`stop`|`restart`:
+   Starts, stops or restarts all running telemetry services.
+
+ * `opt-in`: 
+   Opts in to telemetry, and starts telemetry services. The opt-out file
+   `/etc/telemetrics/opt-out` is removed.
+
+ * `opt-out`: 
+   Opts out of telemetry, and stops telemetry services. The opt-out file
+   `/etc/telemetrics/opt-out` is created.
+
+## RETURN VALUES
+
+0 on success. A non-zero exit code indicates a failure occurred.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/

docs/man/telemd.1

@@ -0,0 +1,55 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMD" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemd\fR \- Telemetry client service
+.
+.SH "SYNOPSIS"
+\fBtelemd\fR \fIflags\fR \fB/etc/telemetrics/telemetrics\.conf\fR
+.
+.SH "DESCRIPTION"
+The \fBtelemd\fR program delivers locally generated telemetry records to a remote telemetry service\. Telemetry data can be in any format, and is relayed as\-is\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-f\fR, \fB\-\-config_file\fR [\fIfile\fR]
+Configuration file\. This overides the other parameters\.
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display this help message\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the program version\.
+.
+.SH "EXIT STATUS"
+0 when no errors occurred\. A non\-zero exit status indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemetry(3)\fR \fBtelemetrics\-client\.conf(5)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+