docs: Add man pages for checkpointctl

This patch adds man pages for checkpointctl. Similar to CRIU, we
use AsciiDoc language and Asciidoctor [1] for generating the man pages.

[1] https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/

Signed-off-by: Radostin Stoyanov <radostin@redhat.com>

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Install tools
-        run: sudo dnf -y install ShellCheck bats golang criu
+        run: sudo dnf -y install ShellCheck bats golang criu asciidoctor
       - name: Run make shellcheck
         run: make shellcheck
       - name: Run make all

Makefile

@@ -8,11 +8,7 @@ GO_SRC = $(shell find . -name \*.go)
 GO_BUILD = $(GO) build
 NAME = checkpointctl
 
-VERSION_MAJOR := 0
-VERSION_MINOR := 1
-VERSION_SUBLEVEL := 0
-VERSION_EXTRA :=
-VERSION := $(VERSION_MAJOR)$(if $(VERSION_MINOR),.$(VERSION_MINOR))$(if $(VERSION_SUBLEVEL),.$(VERSION_SUBLEVEL))$(if $(VERSION_EXTRA),.$(VERSION_EXTRA))
+include Makefile.versions
 
 COVERAGE_PATH ?= $(shell pwd)/.coverage
 
@@ -52,14 +48,17 @@ install: $(NAME)
 	@echo "  INSTALL " $<
 	@mkdir -p $(DESTDIR)$(BINDIR)
 	@install -m0755 $< $(DESTDIR)$(BINDIR)
+	@make -C docs install
 
 uninstall:
+	@make -C docs uninstall
 	@echo " UNINSTALL" $(NAME)
 	@$(RM) $(addprefix $(DESTDIR)$(BINDIR)/,$(NAME))
 
 clean:
 	rm -f $(NAME) junit.xml $(NAME).coverage $(COVERAGE_PATH)/*
 	if [ -d $(COVERAGE_PATH) ]; then rmdir $(COVERAGE_PATH); fi
+	@make -C docs clean
 
 golang-lint:
 	golangci-lint run
@@ -93,9 +92,13 @@ vendor:
 	go mod vendor
 	go mod verify
 
+docs:
+	@make -C docs
+
 help:
 	@echo "Usage: make <target>"
 	@echo " * clean - remove artifacts"
+	@echo " * docs - build man pages"
 	@echo " * lint - verify the source code (shellcheck/golangci-lint)"
 	@echo " * golang-lint - run golangci-lint"
 	@echo " * shellcheck - run shellcheck"
@@ -109,4 +112,4 @@ help:
 	@echo " * release - build a static binary"
 	@echo " * help - show help"
 
-.PHONY: clean install uninstall release lint golang-lint shellcheck vendor test help check-go-version test-junit
+.PHONY: clean docs install uninstall release lint golang-lint shellcheck vendor test help check-go-version test-junit

Makefile.versions

@@ -0,0 +1,5 @@
+VERSION_MAJOR := 0
+VERSION_MINOR := 1
+VERSION_SUBLEVEL := 0
+VERSION_EXTRA :=
+VERSION := $(VERSION_MAJOR)$(if $(VERSION_MINOR),.$(VERSION_MINOR))$(if $(VERSION_SUBLEVEL),.$(VERSION_SUBLEVEL))$(if $(VERSION_EXTRA),.$(VERSION_EXTRA))

docs/.gitattributes

@@ -0,0 +1 @@
+*.txt whitespace

docs/.gitignore

@@ -0,0 +1,2 @@
+*.[1-8]
+footer.adoc

docs/Makefile

@@ -0,0 +1,49 @@
+PREFIX ?= /usr/local
+MANDIR ?= $(PREFIX)/share/man
+
+ASCIIDOC := asciidoctor
+
+FOOTER := footer.adoc
+
+SRC1 += checkpointctl-inspect.adoc
+SRC1 += checkpointctl-memparse.adoc
+SRC1 += checkpointctl-show.adoc
+SRC1 += checkpointctl.adoc
+SRC := $(SRC1)
+
+MAN1S := $(patsubst %.adoc,%.1,$(SRC1))
+MANS := $(MAN1S)
+MAN1DIR := $(MANDIR)/man1
+
+all: check $(MANS)
+
+check:
+	@$(ASCIIDOC) --version > /dev/null || exit 1
+
+include ../Makefile.versions
+$(FOOTER):
+	$(call msg-gen, $@)
+	@echo "The CRIU team" >  $@
+	@echo "v$(VERSION)" >>  $@
+	@echo ":doctype: manpage" >>  $@
+	@echo ":mansource: checkpointctl" >> $@
+	@echo ":manversion: $(VERSION)" >> $@
+	@echo ":manmanual: CHECKPOINTCTL Manual" >> $@
+
+%.1: %.adoc $(FOOTER) custom.xsl
+	$(call msg-gen, $@)
+	@$(ASCIIDOC) -b manpage -d manpage -o $@ $<
+
+clean:
+	@rm -f $(MANS) $(FOOTER)
+
+install: check $(MANS)
+	@echo "  INSTALL " $(MAN1S)
+	@mkdir -p $(DESTDIR)$(MAN1DIR)
+	@install -m 644 $(MAN1S) $(DESTDIR)$(MAN1DIR)
+
+uninstall:
+	@echo " UNINSTALL" $(MAN1S)
+	@rm -rf $(addprefix $(DESTDIR)$(MAN1DIR)/,$(MAN1S))
+
+.PHONY: all check clean install uninstall

docs/checkpointctl-inspect.adoc

@@ -0,0 +1,49 @@
+= checkpointctl-inspect(1)
+include::footer.adoc[]
+
+== Name
+
+*checkpointctl-inspect* - display low-level information about a container checkpoint
+
+== Synopsis
+
+*checkpointctl inspect* [_OPTION_]...  _FILE_
+
+== Options
+
+*-h*, *--help*::
+  Show help for checkpointctl memparse
+
+*--all*::
+  Show all information about container checkpoints
+
+*--files*::
+  Display the open file descriptors for processes in the container checkpoint
+
+*--format*=_FORMAT_::
+  Specify the output format: tree or json (default "tree")
+
+*--mounts*::
+  Display an overview of mounts used in the container checkpoint
+
+*-p, --pid*=_PID_::
+  Display the process tree of a specific PID
+
+*--ps-tree*::
+  Display an overview of processes in the container checkpoint
+
+*--ps-tree-cmd*::
+  Display an overview of processes in the container checkpoint with full command line arguments
+
+*--ps-tree-env*::
+  Display an overview of processes in the container checkpoint with their environment variables
+
+*--sockets*::
+  Display the open sockets for processes in the container checkpoint
+
+*--stats*::
+  Display checkpoint statistics
+
+== See also
+
+checkpointctl(1)

docs/checkpointctl-memparse.adoc

@@ -0,0 +1,25 @@
+= checkpointctl-memparse(1)
+include::footer.adoc[]
+
+== Name
+
+*checkpointctl-memparse* - analyze container checkpoint memory
+
+== Synopsis
+
+*checkpointctl memparse* [_OPTION_]... _FILE_
+
+== Options
+
+*-h*, *--help*::
+  Show help for checkpointctl memparse
+
+*-o, --output*=_FILE_::
+  Specify the output file to be written to
+
+*-p, --pid*=_PID_::
+  Specify the PID of a process to analyze
+
+== See also
+
+checkpointctl(1)

docs/checkpointctl-show.adoc

@@ -0,0 +1,19 @@
+= checkpointctl-show(1)
+include::footer.adoc[]
+
+== Name
+
+*checkpointctl-show* - show an overview of container checkpoints
+
+== Synopsis
+
+*checkpointctl show* [_OPTION_]... _FILE_...
+
+== Options
+
+*-h*, *--help*::
+  Show help for checkpointctl show
+
+== See also
+
+checkpointctl(1)

docs/checkpointctl.adoc

@@ -0,0 +1,49 @@
+= checkpointctl(1)
+include::footer.adoc[]
+
+== Name
+
+checkpointctl - a tool for advanced analysis of container checkpoints
+
+== Synopsis
+
+*checkpointctl* _COMMAND_ [_OPTION_]...
+
+== Description
+
+*checkpointctl* is a tool for advanced analysis of container checkpoints
+created by Podman, CRI-O, and Kubernetes. It allows users to get an overview
+of the checkpoint metadata, inspect the run-time state of processes in the
+container, and perform in-depth analysis of checkpoint memory.
+
+== Options
+
+*-h, --help*::
+  Show help for checkpointctl
+
+*-v, --version*::
+  Show version of checkpointctl
+
+== COMMANDS
+
+[cols="1,1"]
+|===
+|Command |Description
+
+|checkpointctl-completion
+|Generate shell completion scripts
+
+|checkpointctl-inspect(1)
+|Display low-level information about a container checkpoint
+
+|checkpointctl-memparse(1)
+|Analyze container checkpoint memory
+
+|checkpointctl-show(1)
+|Show an overview of container checkpoints
+|===
+
+
+== SEE ALSO
+
+checkpointctl-inspect(1), checkpointctl-memparse(1), checkpointctl-show(1)

docs/custom.xsl

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+ <xsl:param name="man.hyphenate">1</xsl:param>
+ <xsl:param name="man.justify">1</xsl:param>
+ <xsl:param name="man.output.better.ps.enabled">1</xsl:param>
+
+</xsl:stylesheet>