Add a real manual page

This commit is contained in:
Přemysl Eric Janouch 2023-06-15 22:32:02 +02:00
parent ccb3974895
commit 62c6d43ca3
Signed by: p
GPG Key ID: A0420B94F92B9493
4 changed files with 121 additions and 29 deletions

View File

@ -90,20 +90,42 @@ include (GNUInstallDirs)
install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR}) install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR})
install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR}) 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 () endif ()
foreach (page ${PROJECT_NAME}) foreach (page ${PROJECT_NAME})
set (page_output "${PROJECT_BINARY_DIR}/${page}.1") set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
list (APPEND project_MAN_PAGES "${page_output}") 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 () endforeach ()
add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES}) add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})

View File

@ -14,10 +14,15 @@ Packages
Regular releases are sporadic. git master should be stable enough. You can get Regular releases are sporadic. git master should be stable enough. You can get
a package with the latest development version from Archlinux's AUR. 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 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) Runtime dependencies: ncursesw, libunistring, Lua >= 5.3 (for highlighting)
$ git clone --recursive https://git.janouch.name/p/hex.git $ 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 Having the program installed, optionally create a configuration file and run it
on a file of your choice. 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 Terminal caveats
---------------- ----------------
Terminals are somewhat tricky to get consistent results on, so be aware of the Terminals are somewhat tricky to get consistent results on, so be aware of the

81
hex.adoc Normal file
View File

@ -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.

4
hex.c
View File

@ -1871,8 +1871,8 @@ main (int argc, char *argv[])
{ 0, NULL, NULL, 0, NULL } { 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; int64_t size_limit = 1 << 30;
const char *forced_type = NULL; const char *forced_type = NULL;