diff options
| author | Daniel Mueller <deso@posteo.net> | 2019-01-01 11:37:44 -0800 |
|---|---|---|
| committer | Daniel Mueller <deso@posteo.net> | 2019-01-01 11:37:44 -0800 |
| commit | e77650547cf2ab410fd6fe16fc5e86cf1b0772d9 (patch) | |
| tree | ab7b9184e51c3a7d3d1807376203a55345b8e4ba | |
| parent | cc3aa7f14eaec746e6718ef155a59e10c67a03fb (diff) | |
| download | nitrocli-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/Makefile | 17 | ||||
| -rw-r--r-- | nitrocli/README.md | 4 | ||||
| -rw-r--r-- | nitrocli/doc/nitrocli.1.pdf | bin | 0 -> 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 Binary files differnew file mode 100644 index 0000000..a98b9d2 --- /dev/null +++ b/nitrocli/doc/nitrocli.1.pdf |