From e77650547cf2ab410fd6fe16fc5e86cf1b0772d9 Mon Sep 17 00:00:00 2001 From: Daniel Mueller Date: Tue, 1 Jan 2019 11:37:44 -0800 Subject: 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. --- nitrocli/Makefile | 17 ++++++++++++++++- nitrocli/README.md | 4 ++++ nitrocli/doc/nitrocli.1.pdf | Bin 0 -> 13301 bytes 3 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 nitrocli/doc/nitrocli.1.pdf 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 Binary files /dev/null and b/nitrocli/doc/nitrocli.1.pdf differ -- cgit v1.2.3