Merge branch 'better-mans'

* Add manual pages for uncov-gcov and uncov-web.
* Make args in synopsis bold in the manual page.
* Fix a typo in uncov-gcov's usage.
* Fix what INSTALL says about build mans.

INSTALL.md

@@ -34,7 +34,7 @@ Builds debug version with undefined and address sanitizers enabled in
 
 **`man`**
 
-Rebuilds manual page in `<out>/docs/uncov.1`, requires `pandoc`.
+Rebuilds manual pages in `docs/`, requires `pandoc`.
 
 **`doxygen`**
 

Makefile

@@ -121,17 +121,33 @@ self-coverage: UNCOV_PREFIX := $(out_dir)/
 self-coverage: GCOV_PREFIX := ./
 self-coverage: coverage
 
-man: docs/uncov.1
-# the next target doesn't depend on $(wildcard docs/*.md) to make pandoc
+man: docs/uncov.1 docs/uncov-gcov.1 docs/uncov-web.1
+# the following targets don't depend on $(wildcard docs/*/*.md) to make pandoc
 # optional
-docs/uncov.1: force | $(out_dir)/docs
+docs/uncov.1: force
 	pandoc -V title=uncov \
 	       -V section=1 \
 	       -V app=uncov \
 	       -V footer="uncov v0.1" \
 	       -V date="$$(date +'%B %d, %Y')" \
 	       -V author='xaizek <[email protected]>' \
-	       -s -o $@ $(sort $(wildcard docs/*.md))
+	       -s -o $@ $(sort $(wildcard docs/uncov/*.md))
+docs/uncov-gcov.1: force
+	pandoc -V title=uncov-gcov \
+	       -V section=1 \
+	       -V app=uncov-gcov \
+	       -V footer="uncov v0.1" \
+	       -V date="$$(date +'%B %d, %Y')" \
+	       -V author='xaizek <[email protected]>' \
+	       -s -o $@ $(sort $(wildcard docs/uncov-gcov/*.md))
+docs/uncov-web.1: force
+	pandoc -V title=uncov-web \
+	       -V section=1 \
+	       -V app=uncov-web \
+	       -V footer="uncov v0.1" \
+	       -V date="$$(date +'%B %d, %Y')" \
+	       -V author='xaizek <[email protected]>' \
+	       -s -o $@ $(sort $(wildcard docs/uncov-web/*.md))
 
 doxygen:
 	doxygen doxygen/config
@@ -166,11 +182,16 @@ install: release
 	$(INSTALL) -t $(DESTDIR)/usr/bin/ $(bin) $(webbin) uncov-gcov
 	$(INSTALL) -t $(DESTDIR)/usr/share/uncov/srchilight/ data/srchilight/*
 	$(INSTALL) -m 644 docs/uncov.1 $(DESTDIR)/usr/share/man/man1/uncov.1
+	$(INSTALL) -m 644 docs/uncov-gcov.1 \
+	              $(DESTDIR)/usr/share/man/man1/uncov-gcov.1
+	$(INSTALL) -m 644 docs/uncov-web.1 $(DESTDIR)/usr/share/man/man1/uncov-web.1
 
 uninstall:
 	$(RM) $(DESTDIR)/usr/bin/$(basename $(bin)) \
 	      $(DESTDIR)/usr/bin/$(basename $(webbin)) \
-	      $(DESTDIR)/usr/bin/uncov-gcov $(DESTDIR)/usr/share/man/man1/uncov.1
+	      $(DESTDIR)/usr/bin/uncov-gcov $(DESTDIR)/usr/share/man/man1/uncov.1 \
+	      $(DESTDIR)/usr/share/man/man1/uncov-gcov.1 \
+	      $(DESTDIR)/usr/share/man/man1/uncov-web.1
 	$(RM) -r $(DESTDIR)/usr/share/uncov/
 
 # work around parenthesis warning in tests somehow caused by ccache

TODO.md

@@ -74,12 +74,6 @@ maybe even when branch ref matches build commit.
 
 Maybe should also indicate "temporary" commits somehow.
 
-## Write manual pages for uncov-gcov and uncov-web. ##
-
-| ID   |  Status   |  Type  |
-|------|-----------|--------|
-| LSY  |  planned  |  task  |
-
 ## Source-highlight hangs if passed in std::istream is at EOF? ##
 
 | ID   |  Status     |  Type   |
@@ -138,12 +132,6 @@ Or should this be handled by coverage providers?
 
 It's slow for huge diffs/files (quite understandable).
 
-## More code documentation comments. ##
-
-| ID   |  Status       |  Type  |
-|------|---------------|--------|
-| ZRY  |  in progress  |  task  |
-
 ## Language detection for file highlight relies on file name only. ##
 
 | ID   |  Status     |  Type   |

docs/uncov-gcov.1

@@ -0,0 +1,112 @@
+.\" Automatically generated by Pandoc 1.17.0.3
+.\"
+.TH "uncov-gcov" "1" "September 18, 2017" "uncov v0.1" ""
+.hy
+.SH NAME
+.PP
+uncov\-gcov is coverage information collector for C and C++ languages to
+be used with \f[B]uncov(1)\f[].
+.SH SYNOPSIS
+.PP
+\f[B]uncov\-gcov\f[] \f[B]\-h|\-\-help\f[]
+.PP
+\f[B]uncov\-gcov\f[] \f[B]\-v|\-\-version\f[]
+.PP
+\f[B]uncov\-gcov\f[] \f[B][<options>...]\f[]
+.SH OPTIONS
+.SS \f[B]\-\-help, \-h\f[]
+.PP
+Displays short usage help.
+.SS \f[B]\-\-version, \-v\f[]
+.PP
+Displays version information.
+.SS \f[B]\-\-verbose\f[]
+.PP
+Print verbose messages.
+.SS \f[B]\-\-dryrun\f[]
+.PP
+Run the script without printing report.
+.SS \f[B]\-\-gcov\f[] [=gcov]
+.PP
+Set the location of gcov.
+.SS \f[B]\-\-gcov\-options\f[] [=""]
+.PP
+Set the options given to gcov.
+.SS \f[B]\-r\f[], \f[B]\-\-root\f[] [=.]
+.PP
+Set the root directory.
+.SS \f[B]\-b\f[], \f[B]\-\-build\-root\f[] [={discovered}]
+.PP
+Set the directory from which gcov will be called; by default gcov is run
+in the directory of the .o files; however the paths of the sources are
+often relative to the directory from which the compiler was run and
+these relative paths are saved in the .o file; when this happens, gcov
+needs to run in the same directory as the compiler in order to find the
+source files.
+.SS \f[B]\-\-collect\-root\f[] [={value of \-\-root}]
+.PP
+Directory to look gcov files in.
+.SS \f[B]\-e\f[], \f[B]\-\-exclude\f[] [=""]
+.PP
+Set exclude file or directory.
+.SS \f[B]\-i\f[], \f[B]\-\-include\f[] [=""]
+.PP
+Set include file or directory.
+.SS \f[B]\-E\f[], \f[B]\-\-exclude\-pattern\f[] [=""]
+.PP
+Set exclude file/directory pattern.
+.SS \f[B]\-x\f[], \f[B]\-\-extension\f[]
+[=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
+.PP
+Set extension of files to process.
+.SS \f[B]\-n\f[], \f[B]\-\-no\-gcov\f[]
+.PP
+Do not run gcov.
+.SS \f[B]\-\-encodings\f[] [=utf\-8,latin\-1]
+.PP
+Source encodings to try in order of preference.
+.SS \f[B]\-\-dump\f[] <file>
+.PP
+Dump JSON payload to a file.
+.SS \f[B]\-\-follow\-symlinks\f[]
+.PP
+Follow symlinks.
+.SS \f[B]\-c\f[], \f[B]\-\-capture\-worktree\f[]
+.PP
+Make a dangling commit if working directory is dirty.
+.SS \f[B]\-\-ref\-name\f[] [={discovered}]
+.PP
+Force custom ref name.
+.SH USAGE
+.PP
+uncov\-gcov can be used to generate coverage, but it seems to not play
+well with out\-of\-tree builds (some coverage is missing, this issue is
+inherited from its origin), so the recommended way of recording coverage
+information is as follows:
+.IP
+.nf
+\f[C]
+#\ reset\ coverage\ counters\ from\ previous\ runs
+find\ .\ \-name\ \[aq]*.gcda\[aq]\ \-delete
+
+#\ run\ tests\ here\ with\ something\ like\ `make\ check`
+
+#\ generage\ coverage\ for\ every\ object\ file\ found\ (change\ "."\ to\ build\ root)
+find\ .\ \-name\ \[aq]*.o\[aq]\ \-exec\ gcov\ \-p\ {}\ +
+
+#\ generage\ and\ combine\ coverage\ reports\ (\-\-capture\-worktree\ automatically
+#\ makes\ stray\ commit\ if\ repository\ is\ dirty)
+uncov\-gcov\ \-\-root\ .\ \-\-no\-gcov\ \-\-capture\-worktree\ \-\-exclude\ tests\ |\ uncov\ new
+
+#\ remove\ coverage\ reports
+find\ .\ \-name\ \[aq]*.gcov\[aq]\ \-delete
+\f[]
+.fi
+.PP
+These commands can be put in a separate script or embedded directly into
+build system.
+.SH SEE ALSO
+.PP
+\f[B]uncov\f[](1), \f[B]uncov\-web\f[](1)
+.SH AUTHORS
+xaizek <[email protected]>.

docs/uncov-gcov/01-name.md

@@ -0,0 +1,5 @@
+NAME
+====
+
+uncov-gcov is coverage information collector for C and C++ languages to be used
+with **uncov(1)**.

docs/uncov-gcov/02-synopsis.md

@@ -0,0 +1,8 @@
+SYNOPSIS
+========
+
+**uncov-gcov** **-h|--help**
+
+**uncov-gcov** **-v|--version**
+
+**uncov-gcov** **[\<options\>...]**

docs/uncov-gcov/03-options.md

@@ -0,0 +1,101 @@
+OPTIONS
+=======
+
+**--help, -h**
+--------------
+
+Displays short usage help.
+
+**--version, -v**
+-----------------
+
+Displays version information.
+
+**--verbose**
+-------------
+
+Print verbose messages.
+
+**--dryrun**
+------------
+
+Run the script without printing report.
+
+**--gcov** [=gcov]
+------------------
+
+Set the location of gcov.
+
+**--gcov-options** [=""]
+------------------------
+
+Set the options given to gcov.
+
+**-r**, **--root** [=.]
+-----------------------
+
+Set the root directory.
+
+**-b**, **--build-root** [={discovered}]
+----------------------------------------
+
+Set the directory from which gcov will be called; by default gcov is run in the
+directory of the .o files; however the paths of the sources are often relative
+to the directory from which the compiler was run and these relative paths are
+saved in the .o file; when this happens, gcov needs to run in the same directory
+as the compiler in order to find the source files.
+
+**--collect-root** [={value of --root}]
+---------------------------------------
+
+Directory to look gcov files in.
+
+**-e**, **--exclude** [=""]
+---------------------------
+
+Set exclude file or directory.
+
+**-i**, **--include** [=""]
+---------------------------
+
+Set include file or directory.
+
+**-E**, **--exclude-pattern** [=""]
+-----------------------------------
+
+Set exclude file/directory pattern.
+
+**-x**, **--extension** [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
+-------------------------------------------------------------------
+
+Set extension of files to process.
+
+**-n**, **--no-gcov**
+---------------------
+
+Do not run gcov.
+
+**--encodings** [=utf-8,latin-1]
+--------------------------------
+
+Source encodings to try in order of preference.
+
+**--dump** \<file\>
+-------------------
+
+Dump JSON payload to a file.
+
+**--follow-symlinks**
+---------------------
+
+Follow symlinks.
+
+**-c**, **--capture-worktree**
+------------------------------
+
+Make a dangling commit if working directory is dirty.
+
+**--ref-name** [={discovered}]
+------------------------------
+
+Force custom ref name.

docs/uncov-gcov/04-usage.md

@@ -0,0 +1,26 @@
+USAGE
+=====
+
+uncov-gcov can be used to generate coverage, but it seems to not play well with
+out-of-tree builds (some coverage is missing, this issue is inherited from its
+origin), so the recommended way of recording coverage information is as follows:
+
+```
+# reset coverage counters from previous runs
+find . -name '*.gcda' -delete
+
+# run tests here with something like `make check`
+
+# generage coverage for every object file found (change "." to build root)
+find . -name '*.o' -exec gcov -p {} +
+
+# generage and combine coverage reports (--capture-worktree automatically
+# makes stray commit if repository is dirty)
+uncov-gcov --root . --no-gcov --capture-worktree --exclude tests | uncov new
+
+# remove coverage reports
+find . -name '*.gcov' -delete
+```
+
+These commands can be put in a separate script or embedded directly into build
+system.

docs/uncov-gcov/05-see-also.md

@@ -0,0 +1,4 @@
+SEE ALSO
+========
+
+**uncov**(1), **uncov-web**(1)