summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Mueller <deso@posteo.net>2019-01-01 11:37:44 -0800
committerDaniel Mueller <deso@posteo.net>2019-01-01 11:37:44 -0800
commite77650547cf2ab410fd6fe16fc5e86cf1b0772d9 (patch)
treeab7b9184e51c3a7d3d1807376203a55345b8e4ba
parentcc3aa7f14eaec746e6718ef155a59e10c67a03fb (diff)
downloadnitrocli-e77650547cf2ab410fd6fe16fc5e86cf1b0772d9.tar.gz
nitrocli-e77650547cf2ab410fd6fe16fc5e86cf1b0772d9.tar.bz2
Add 'doc' Makefile target for generating PDF version of man page
This change adds a new target to the Makefile that can be used for generating a PDF version of the man page. It also checks in the generated file and links to it from the README. We have also experimented with creation of an HTML version, but at least the groff generated file is not very visually pleasing and also cannot be linked to directly from Github. Github wants to prevent hosting of web pages directly like this in repositories and instead promote their Github Pages solution for that purpose. To that end they deliver content with a Content-Type representing plain text which causes HTML to not be rendered. PDF content, however, is rendered in-line and looks reasonable at that.
-rw-r--r--nitrocli/Makefile17
-rw-r--r--nitrocli/README.md4
-rw-r--r--nitrocli/doc/nitrocli.1.pdfbin0 -> 13301 bytes
3 files changed, 20 insertions, 1 deletions
diff --git a/nitrocli/Makefile b/nitrocli/Makefile
index ca3a0b9..cc1ad3f 100644
--- a/nitrocli/Makefile
+++ b/nitrocli/Makefile
@@ -1,7 +1,7 @@
# Makefile
#/***************************************************************************
-# * Copyright (C) 2017 Daniel Mueller (deso@posteo.net) *
+# * Copyright (C) 2017-2019 Daniel Mueller (deso@posteo.net) *
# * *
# * This program is free software: you can redistribute it and/or modify *
# * it under the terms of the GNU General Public License as published by *
@@ -25,3 +25,18 @@
.PHONY: test
test:
@RUST_TEST_NOCAPTURE=1 RUST_TEST_THREADS=1 cargo test
+
+PS2PDF ?= ps2pdf
+
+NITROCLI_MAN := doc/nitrocli.1
+NITROCLI_PDF := $(addsuffix .pdf,$(NITROCLI_MAN))
+
+.PHONY: doc
+doc: $(NITROCLI_PDF) $(NITROCLI_HTML)
+
+# We assume and do not check existence of man, which, false, and echo
+# commands.
+$(NITROCLI_PDF): $(NITROCLI_MAN)
+ @which $(PS2PDF) &> /dev/null || \
+ (echo "$(PS2PDF) command not found, unable to generate documentation"; false)
+ @man --local-file --troff $(<) | $(PS2PDF) - $(@)
diff --git a/nitrocli/README.md b/nitrocli/README.md
index ac6710f..df6117e 100644
--- a/nitrocli/README.md
+++ b/nitrocli/README.md
@@ -70,6 +70,10 @@ Status:
$ nitrocli storage close
```
+More examples, a more detailed explanation of the purpose, the potential
+subcommands, as well as the parameters of each command are provided in
+the [`man` page](doc/nitrocli.1.pdf).
+
Installation
------------
diff --git a/nitrocli/doc/nitrocli.1.pdf b/nitrocli/doc/nitrocli.1.pdf
new file mode 100644
index 0000000..a98b9d2
--- /dev/null
+++ b/nitrocli/doc/nitrocli.1.pdf
Binary files differ