Add a real manual page

CMakeLists.txt

@@ -90,20 +90,42 @@ include (GNUInstallDirs)
 install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR})
 install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR})
 
-# Generate documentation from program help
+# Generate documentation from text markup
-find_program (HELP2MAN_EXECUTABLE help2man)
+find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
-if (NOT HELP2MAN_EXECUTABLE)
+find_program (A2X_EXECUTABLE a2x)
-	message (FATAL_ERROR "help2man not found")
+if (NOT ASCIIDOCTOR_EXECUTABLE AND NOT A2X_EXECUTABLE)
+	message (WARNING "Neither asciidoctor nor a2x were found, "
+		"falling back to a substandard manual page generator")
 endif ()
 
 foreach (page ${PROJECT_NAME})
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
-	add_custom_command (OUTPUT ${page_output}
+	if (ASCIIDOCTOR_EXECUTABLE)
-		COMMAND ${HELP2MAN_EXECUTABLE} -N
+		add_custom_command (OUTPUT ${page_output}
-			"${PROJECT_BINARY_DIR}/${page}" -o ${page_output}
+			COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
-		DEPENDS ${page}
+				-a release-version=${PROJECT_VERSION}
-		COMMENT "Generating man page for ${page}" VERBATIM)
+				-o "${page_output}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	elseif (A2X_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${A2X_EXECUTABLE} --doctype manpage --format manpage
+				-a release-version=${PROJECT_VERSION}
+				-D "${PROJECT_BINARY_DIR}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	else ()
+		set (ASCIIMAN ${PROJECT_SOURCE_DIR}/liberty/tools/asciiman.awk)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND env LC_ALL=C asciidoc-release-version=${PROJECT_VERSION}
+				awk -f ${ASCIIMAN} "${PROJECT_SOURCE_DIR}/${page}.adoc"
+				> ${page_output}
+			DEPENDS ${page}.adoc ${ASCIIMAN}
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	endif ()
 endforeach ()
 
 add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})

README.adoc

@@ -14,10 +14,15 @@ Packages
 Regular releases are sporadic.  git master should be stable enough.  You can get
 a package with the latest development version from Archlinux's AUR.
 
+Documentation
+-------------
+See the link:hex.adoc[man page] for information about usage.
+The rest of this README will concern itself with externalities.
+
 Building and Running
 --------------------
-Build dependencies: CMake, pkg-config, help2man, liberty (included),
+Build dependencies: CMake, pkg-config, awk, liberty (included),
-                    termo (included) +
+ termo (included), asciidoctor or asciidoc (recommended but optional) +
 Runtime dependencies: ncursesw, libunistring, Lua >= 5.3 (for highlighting)
 
  $ git clone --recursive https://git.janouch.name/p/hex.git
@@ -38,22 +43,6 @@ Or you can try telling CMake to make a package for you.  For Debian it is:
 Having the program installed, optionally create a configuration file and run it
 on a file of your choice.
 
-Configuration
--------------
-Create _~/.config/hex/hex.conf_ with contents like the following:
-
-....
-colors = {
-	footer     = ""
-	footer_hl  = "bold"
-	bar        = "reverse"
-	bar_hl     = "reverse bold"
-	even       = ""
-	odd        = ""
-	selection  = "reverse"
-}
-....
-
 Terminal caveats
 ----------------
 Terminals are somewhat tricky to get consistent results on, so be aware of the

hex.adoc

@@ -0,0 +1,81 @@
+hex(1)
+======
+:doctype: manpage
+:manmanual: hex Manual
+:mansource: hex {release-version}
+
+Name
+----
+hex - Interpreting hex viewer
+
+Synopsis
+--------
+*hex* [_OPTION_]... [_PATH_]
+
+Description
+-----------
+*hex* is a hex viewer that uses Lua scripts to interpret fields within files,
+colorizes them, and shows their descriptions on the side.
+
+When run without arguments, it reads from its standard input stream.
+
+Options
+-------
+*-o*, *--offset* _OFFSET_::
+	Byte offset into the file.  All preceding data will be ignored.
+
+*-s*, *--size* _SIZE_::
+	Size limit in bytes.  Any following data will be ignored.
++
+The _SIZE_ argument accepts similar suffixes as in *dd*(1): _c_=1,
+_w_=2, _b_=512, _K_=1024, _KB_=1000, _M_=1024K, _MB_=1000KB,
+_G_=1024M, and _GB_=1000M.  The default value is 1G.
+
+*-t*, *--type* _TYPE_::
+	Force interpretation as the given type, skipping autodetection.
+	Pass in "list" for a listing of all available decoders.
+
+*-d*, *--debug*::
+	Run in debug mode.
+
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+Configuration
+-------------
+Create _~/.config/hex/hex.conf_ with contents like the following:
+
+....
+colors = {
+	footer     = ""
+	footer_hl  = "bold"
+	bar        = "reverse"
+	bar_hl     = "reverse bold"
+	even       = ""
+	odd        = ""
+	selection  = "reverse"
+}
+....
+
+Terminal attributes are accepted in a format similar to that of *git-config*(1),
+only named colours aren't supported.
+
+Files
+-----
+*hex* follows the XDG Base Directory Specification.
+
+_~/.config/hex/hex.conf_::
+	The configuration file.
+
+_~/.local/share/hex/plugins/_::
+_/usr/local/share/hex/plugins/_::
+_/usr/share/hex/plugins/_::
+	Plugins are loaded from these directories, in order.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/hex to report bugs, request features,
+or submit pull requests.

hex.c

@@ -1871,8 +1871,8 @@ main (int argc, char *argv[])
 		{ 0, NULL, NULL, 0, NULL }
 	};
 
-	struct opt_handler oh =
+	struct opt_handler oh = opt_handler_make (argc, argv, opts, "[FILE]",
-		opt_handler_make (argc, argv, opts, "[FILE]", "Hex viewer.");
+		"Interpreting hex viewer.");
 	int64_t size_limit = 1 << 30;
 	const char *forced_type = NULL;