diff options
| -rw-r--r-- | CMakeLists.txt | 40 | ||||
| -rw-r--r-- | README.adoc | 25 | ||||
| -rw-r--r-- | hex.adoc | 81 | ||||
| -rw-r--r-- | hex.c | 4 |
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. @@ -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; |