aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CMakeLists.txt40
-rw-r--r--README.adoc25
-rw-r--r--hex.adoc81
-rw-r--r--hex.c4
4 files changed, 121 insertions, 29 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c5a5fd3..732fb15 100644
--- a/CMakeLists.txt
+++ b/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
-find_program (HELP2MAN_EXECUTABLE help2man)
-if (NOT HELP2MAN_EXECUTABLE)
- message (FATAL_ERROR "help2man not found")
+# Generate documentation from text markup
+find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
+find_program (A2X_EXECUTABLE a2x)
+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}
- COMMAND ${HELP2MAN_EXECUTABLE} -N
- "${PROJECT_BINARY_DIR}/${page}" -o ${page_output}
- DEPENDS ${page}
- COMMENT "Generating man page for ${page}" VERBATIM)
+ if (ASCIIDOCTOR_EXECUTABLE)
+ add_custom_command (OUTPUT ${page_output}
+ COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
+ -a release-version=${PROJECT_VERSION}
+ -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})
diff --git a/README.adoc b/README.adoc
index d8cdb08..f2b23d1 100644
--- a/README.adoc
+++ b/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),
- termo (included) +
+Build dependencies: CMake, pkg-config, awk, liberty (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
diff --git a/hex.adoc b/hex.adoc
new file mode 100644
index 0000000..d422283
--- /dev/null
+++ b/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.
diff --git a/hex.c b/hex.c
index 3cb87e2..0c57aff 100644
--- a/hex.c
+++ b/hex.c
@@ -1871,8 +1871,8 @@ main (int argc, char *argv[])
{ 0, NULL, NULL, 0, NULL }
};
- struct opt_handler oh =
- opt_handler_make (argc, argv, opts, "[FILE]", "Hex viewer.");
+ struct opt_handler oh = opt_handler_make (argc, argv, opts, "[FILE]",
+ "Interpreting hex viewer.");
int64_t size_limit = 1 << 30;
const char *forced_type = NULL;