From 46e86e494298075fc5c67b8fb0f9b4e0118e1623 Mon Sep 17 00:00:00 2001
From: Chris Patterson <cpatterson@microsoft.com>
Date: Thu, 6 Jun 2024 09:08:02 -0400
Subject: [PATCH] build(doc): drop pandoc generation of manpage

As pointed out by Noah in #15, Debian packaging lints issues in the
generated manpage due to formatting emitted by older versions of pandoc:
https://github.com/jgm/pandoc/issues/9020

While changes in recent versions of pandoc have improved the output,
let's just take the generated output from pandoc 3.2 as a starting point
and maintain it manually for the time being.  This reduces friction for
packaging and gives us flexibility if we wanted to do something in the
manpage that pandoc doesn't support.

Signed-off-by: Chris Patterson <cpatterson@microsoft.com>
---
 .github/workflows/main.yml |  2 +-
 cmake/doc.cmake            | 21 +++------------
 doc/azure-nvme-id.1        | 54 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 18 deletions(-)
 create mode 100644 doc/azure-nvme-id.1

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index f46b1a7..aee8960 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -26,7 +26,7 @@ jobs:
     - name: Setup
       run: |
         sudo apt update
-        sudo apt install gcc pandoc cmake -y
+        sudo apt install gcc cmake -y
     - name: Build & install project with cmake
       run: |
         cmake .
diff --git a/cmake/doc.cmake b/cmake/doc.cmake
index b080206..1a85422 100644
--- a/cmake/doc.cmake
+++ b/cmake/doc.cmake
@@ -1,22 +1,9 @@
-find_program(PANDOC_EXECUTABLE pandoc)
-if(NOT PANDOC_EXECUTABLE)
-        message(WARNING "Pandoc not found, will not generate manpages")
-        return()
-endif()
-
 string(TIMESTAMP TODAY "%B %d, %Y")
 
-add_custom_command(
-	OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1
-	COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/doc
-	COMMAND ${PANDOC_EXECUTABLE}
-		${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md
-		--standalone --from markdown --to man
-		--variable footer="azure-nvme-id ${VERSION}"
-		--variable date="${TODAY}"
-		-o ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1
-	DEPENDS ${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md
-	COMMENT "Generating manpage for azure-nvme-id"
+configure_file(
+    "${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.1"
+    "${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1"
+    @ONLY
 )
 
 add_custom_target(
diff --git a/doc/azure-nvme-id.1 b/doc/azure-nvme-id.1
new file mode 100644
index 0000000..f46add7
--- /dev/null
+++ b/doc/azure-nvme-id.1
@@ -0,0 +1,54 @@
+.TH "azure\-nvme\-id" "1" "@TODAY@" "azure-nvme-id\ @VERSION@" "User Manual"
+.SH NAME
+azure\-nvme\-id \- Identify Azure NVMe devices.
+.SH SYNOPSIS
+\f[B]azure\-nvme\-id\f[R] [\-\-debug] [\-\-help | \-\-version |
+\-\-udev]
+.SH DESCRIPTION
+\f[B]azure\-nvme\-id\f[R] is a utility to identify Azure NVMe devices.
+.PP
+It performs an Identify Namespace command on the NVMe namespaces,
+parsing metadata available in the vendor\-specific (vs) field which
+contains various identification details with a comma\-separated,
+key=value format.
+.SH OPTIONS
+.TP
+\f[CR]\-\-help\f[R]
+Show usage information and exit.
+.TP
+\f[CR]\-\-version\f[R]
+Show version information and exit.
+.TP
+\f[CR]\-\-udev\f[R]
+Run in udev mode, printing a set of \f[CR]<key>=<value>\f[R] variables
+consumed by udev rules.
+Requires DEVNAME to be set in environment.
+.SH EXAMPLES
+Identify NVMe namespaces:
+.IP
+.EX
+$ sudo azure\-nvme\-id
+/dev/nvme0n1:
+/dev/nvme1n1: type=local,index=1,name=nvme\-110G\-1
+.EE
+.PP
+Parse device identifiers for udev consumption:
+.IP
+.EX
+$ sudo env DEVNAME=/dev/nvme1n1 azure\-nvme\-id \-\-udev
+AZURE_NVME_VS=type=local,index=1,name=nvme\-110G\-1
+AZURE_NVME_TYPE=local
+AZURE_NVME_INDEX=1
+AZURE_NVME_NAME=nvme\-110G\-1
+.EE
+.PP
+Check \f[CR]azure\-nvme\-id\f[R] version:
+.IP
+.EX
+$ azure\-nvme\-id \-\-version
+azure\-nvme\-id 0.1.2
+.EE
+.SH SEE ALSO
+Source and documentation available at: \c
+.UR https://github.com/Azure/azure-nvme-utils
+.UE \c