diff --git a/Justfile b/Justfile index c51b442..5c90bc7 100644 --- a/Justfile +++ b/Justfile @@ -40,13 +40,8 @@ push-docker-latest: build-docker push-docker docker push forge.steck.dev/bryson/picca:latest docker image rm forge.steck.dev/bryson/picca:latest -# generate algorithm bin into Cargo.toml -generate-bin: - - doc: - @mkdir -p target - sed s/\/{{version}}/g man/picca.1.md | pandoc --standalone -t man > target/picca.1 + man/generate-docs.sh {{version}} preview-man: doc man target/picca.1 diff --git a/man/algorithm.1.md b/man/algorithm.1.md new file mode 100644 index 0000000..96d25f6 --- /dev/null +++ b/man/algorithm.1.md @@ -0,0 +1,59 @@ +% (1) Version | User Commands +% Written by Bryson Steck (bryson@steck.dev) +% August 2025 + +# NAME + +sum - a Parallel Implementation of the algorithm + +# SYNOPSIS + +sum [_OPTIONS_] [_FILE_]... + +# DESCRIPTION + +Print or verify checksums by reading files in parallel, using the algorithm. + +When conditions are suitable, being able to hash multiple files in parallel can significantly increase performance with multi-file hashing operations. However, it can also significantly degrade performance depending on different factors with your particular system. Some factors to consider are: + +- The type of storage being used, +- The type of processor(s) in the system, +- The latency of I/O operations, +- etc. + +sum is a standalone binary of the picca project that only runs the algorithm. See **picca**(1) for information on the main binary. + +# OPTIONS + +With no FILE(s) specified, or when FILE is a dash (-), sum will read from standard input. + +**-c, ––check** _CHECK_ +: Read checksums from the specified file and verify them. This argument can be specified multiple times to read checksums from multiple files. + +**-d, ––debug** +: Enable debug output for troubleshooting purposes. Messages output to standard error. + +**-f, ––canonicalize** +: Show canonicalized file paths; convert relative paths to absolute paths. + +**-h, ––help** +: Show command usage and available options + +**-t, ––threads** _THREADS_ +: Use at most, at any given time, this number of threads. By default, sum will detect the amount of processors on the system and use that as the thread count. Using 0 for this value results in the default behavior; this is the same as omitting this option. + +**-V, ––version** +: Show the version of picca and exit + +The following option is only useful when verifying checksums with the **-c** flag: + +**-q, ––quiet** +: Only print checksums that fail verification; do not print anything to standard output if a verfication is successful. Helpful to limit the amount of information printed to the screen. + +# REPORTING BUGS + +Bugs to the picca project can be submitted via an issue on Codeberg: [https://codeberg.org/bryson/picca]() + +# COPYRIGHT + +Copyright © 2025 Bryson Steck. diff --git a/man/generate-docs.sh b/man/generate-docs.sh new file mode 100755 index 0000000..1d87b10 --- /dev/null +++ b/man/generate-docs.sh @@ -0,0 +1,25 @@ +#!/usr/bin/bash + +pushd $(dirname "$0") > /dev/null + +if [ -z $1 ]; then + echo "missing version passed as an argument" + exit 1 +fi + +mkdir -p ../target/man +for i in ascon belt blake2b512 blake2s256 blake3 fsb160 fsb224 fsb256 fsb384 fsb512 gost94 \ + groestl224 groestl256 groestl384 groestl512 jh224 jh256 jh384 jh512 k12 md2 md4 md5 \ + ripemd128 ripemd160 ripemd256 ripemd320 sha1 sha224 sha256 sha384 sha3_224 sha3_256 \ + sha3_384 sha3_512 sha512 shabal192 shabal224 shabal256 shabal384 shabal512 shake128 \ + shake256 skein1024 skein256 skein512 sm3 streebog256 streebog512 tiger whirlpool; do + echo $i + upper=$(echo $i | tr '[:lower:]' '[:upper:]') + pandoc --standalone <(sed "s//$1/g;s//$upper/g;s//$i/g" algorithm.1.md) \ + -f markdown -t man > ../target/man/${i}sum.1 +done + +echo picca +pandoc --standalone <(sed "s//$1/g" picca.1.md) -f markdown -t man > ../target/man/picca.1 + +popd > /dev/null diff --git a/man/picca.1.md b/man/picca.1.md index e389e09..08992dc 100644 --- a/man/picca.1.md +++ b/man/picca.1.md @@ -50,3 +50,11 @@ The following option is only useful when verifying checksums with the **-c** fla **-q, ––quiet** : Only print checksums that fail verification; do not print anything to standard output if a verfication is successful. Helpful to limit the amount of information printed to the screen. + +# REPORTING BUGS + +Bugs to the picca project can be submitted via an issue on Codeberg: [https://codeberg.org/bryson/picca]() + +# COPYRIGHT + +Copyright © 2025 Bryson Steck.