From 9c076e6ce8915bfe9ed895103fbd5ba3eb79c895 Mon Sep 17 00:00:00 2001 From: Shun Sakai Date: Thu, 24 Mar 2022 01:42:10 +0900 Subject: [PATCH] Add man page --- .github/workflows/CICD.yml | 13 ++++ .gitignore | 3 + README.md | 13 ++++ doc/hexyl.1.md | 145 +++++++++++++++++++++++++++++++++++++ 4 files changed, 174 insertions(+) create mode 100644 doc/hexyl.1.md diff --git a/.github/workflows/CICD.yml b/.github/workflows/CICD.yml index 220d97dd..a8f7377f 100644 --- a/.github/workflows/CICD.yml +++ b/.github/workflows/CICD.yml @@ -155,6 +155,12 @@ jobs: command: test args: --target=${{ matrix.job.target }} ${{ steps.test-options.outputs.CARGO_TEST_OPTIONS}} + - name: Setup Pandoc + uses: r-lib/actions/setup-pandoc@v2 + + - name: Generate man page + run: pandoc -s -f markdown -t man -o "doc/${{ env.PROJECT_NAME }}.1" "doc/${{ env.PROJECT_NAME }}.1.md" + - name: Create tarball id: package shell: bash @@ -171,6 +177,9 @@ jobs: # Binary cp "${{ steps.strip.outputs.BIN_PATH }}" "$ARCHIVE_DIR" + # Man page + cp "doc/${{ env.PROJECT_NAME }}.1" "$ARCHIVE_DIR" + # README, LICENSE and CHANGELOG files cp "README.md" "LICENSE-MIT" "LICENSE-APACHE" "CHANGELOG.md" "$ARCHIVE_DIR" @@ -215,6 +224,10 @@ jobs: # Binary install -Dm755 "${{ steps.strip.outputs.BIN_PATH }}" "${DPKG_DIR}/usr/bin/${{ steps.strip.outputs.BIN_NAME }}" + # Man page + install -Dm644 "doc/${{ env.PROJECT_NAME }}.1" "${DPKG_DIR}/usr/share/man/man1/${{ env.PROJECT_NAME }}.1" + gzip -n --best "${DPKG_DIR}/usr/share/man/man1/${{ env.PROJECT_NAME }}.1" + # README and LICENSE install -Dm644 "README.md" "${DPKG_DIR}/usr/share/doc/${DPKG_BASENAME}/README.md" install -Dm644 "LICENSE-MIT" "${DPKG_DIR}/usr/share/doc/${DPKG_BASENAME}/LICENSE-MIT" diff --git a/.gitignore b/.gitignore index 53eaa219..adedbef7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ /target **/*.rs.bk + +# Generated files +hexyl.1 diff --git a/README.md b/README.md index 6ea8e4b6..456ebe30 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,19 @@ If you have Rust 1.46 or higher, you can install `hexyl` from source via `cargo` cargo install hexyl ``` +Alternatively, you can install `hexyl` directly from the repository by using: +``` +git clone https://github.com/sharkdp/hexyl +cargo install --path ./hexyl +``` + +Note: To convert the man page, you will need [Pandoc](https://pandoc.org/). + +You can convert from Markdown by using (in the project root): +``` +pandoc -s -f markdown -t man -o ./doc/hexyl.1 ./doc/hexyl.1.md +``` + ### Via snap package ``` diff --git a/doc/hexyl.1.md b/doc/hexyl.1.md new file mode 100644 index 00000000..8b02259b --- /dev/null +++ b/doc/hexyl.1.md @@ -0,0 +1,145 @@ +% HEXYL(1) hexyl 0.9.0 | General Commands Manual +% +% 2022-03-23 + + + +# NAME + +hexyl - a command-line hex viewer + +# SYNOPSIS + +**hexyl** [_OPTIONS_] [_FILE_] + +# DESCRIPTION + +**hexyl** is a simple hex viewer for the terminal. +It uses a colored output to distinguish different categories of bytes (NULL +bytes, printable ASCII characters, ASCII whitespace characters, other ASCII +characters and non-ASCII). + +# POSITIONAL ARGUMENTS + +_FILE_ +: The file to display. + If no _FILE_ argument is given, read from STDIN. + +# OPTIONS + +**-n**, **\--length** _N_ +: Only read _N_ bytes from the input. + The _N_ argument can also include a unit with a decimal prefix (kB, MB, ..) + or binary prefix (kiB, MiB, ..), or can be specified using a hex number. + + Examples: + + : + + Read the first 64 bytes: + : $ **hexyl \--length=64** + + Read the first 4 kibibytes: + : $ **hexyl \--length=4KiB** + + Read the first 255 bytes (specified using a hex number): + : $ **hexyl \--length=0xff** + +**-c**, **\--bytes** _N_ +: An alias for **-n**/**\--length**. + +**-l** _N_ +: Yet another alias for **-n**/**\--length**. + +**-s**, **\--skip** _N_ +: Skip the first _N_ bytes of the input. + The _N_ argument can also include a unit (see **\--length** for details). + A negative value is valid and will seek from the end of the file. + +**\--block-size** _SIZE_ +: Sets the size of the block unit to _SIZE_ (default is 512). + + Examples: + + : + + Sets the block size to 1024 bytes: + : $ **hexyl \--block-size=1024 \--length=5block** + + Sets the block size to 4 kilobytes: + : $ **hexyl \--block-size=4kB \--length=2block** + +**-v**, **\--no-squeezing** +: Displays all input data. + Otherwise any number of groups of output lines which would be identical to + the preceding group of lines, are replaced with a line comprised of a + single asterisk. + +**\--color** _WHEN_ +: When to use colors. + The auto-mode only displays colors if the output goes to an interactive + terminal. + + Possible values: + + : - **always** (default) + - **auto** + - **never** + +**\--border** _STYLE_ +: Whether to draw a border with Unicode characters, ASCII characters, or none + at all. + + Possible values: + + : - **unicode** (default) + - **ascii** + - **none** + +**-o**, **\--display-offset** _N_ +: Add _N_ bytes to the displayed file position. + The _N_ argument can also include a unit (see **\--length** for details). + A negative value is valid and calculates an offset relative to the end of + the file. + +**-h**, **\--help** +: Prints help information. + +**-V**, **\--version** +: Prints version information. + +# NOTES + +Source repository: +: + +# EXAMPLES + +Print a given file: +: $ **hexyl small.png** + +Print the first 256 bytes of a given special file: +: $ **hexyl -n 256 /dev/urandom** + +# AUTHORS + +**hexyl** was written by David Peter . + +# REPORTING BUGS + +Bugs can be reported on GitHub at: +: + +# COPYRIGHT + +**hexyl** is dual-licensed under: + +: - Apache License 2.0 () + - MIT License () + +# SEE ALSO + +**hexdump**(1), **xxd**(1)