Break up man page sections for legibility. Use macros for code examples. Add link...

diff --git a/cli.js b/cli.js
index ab7f6642450464aed5fdc5c507470379ca55b548..3a89c54acc37852526c8237d82a4e14fa3b0429b 100755 (executable)
--- a/cli.js
+++ b/cli.js
@@ -9,7 +9,10 @@ const args = process.argv.slice(2)
 if (args.length === 0 || args.some(v => v === '--help' || v === '-h')) {
        console.log(`Usage: nano-pow [OPTION]... BLOCKHASH...
 Generate work for BLOCKHASH, or multiple work values for BLOCKHASH(es)
+BLOCKHASH is a 64-character hexadecimal string.
 Multiple blockhash values must be separated by spaces.
+Prints a 16-character hexadecimal work value to standard output.
+If using --validate, prints 'true' or 'false' to standard output instead.
 All command options are optional.
 
   -h, --help                  show this dialog
@@ -18,7 +21,6 @@ All command options are optional.
   -t, --threshold <value>     override the minimum threshold value
   -v, --validate <value>      check an existing work value instead of searching for one
 
-Blockhash(es) must be 64-character hexadecimal values.
 If validating a nonce, it must be a 16-character hexadecimal value.
 Effort must be a decimal number between 1 - 32.
 Threshold must be a hexadecimal number between 0x0 - 0xFFFFFFFF.

diff --git a/nano-pow.1 b/nano-pow.1
index c9674388f5abd9bcf0054d2a1e2d52c62900a60d..f0a4afa2ee6ea76b8bd99b2bc7681697b973a99a 100644 (file)
--- a/nano-pow.1
+++ b/nano-pow.1
@@ -2,14 +2,25 @@
 \# SPDX-License-Identifier: GPL-3.0-or-later
 
 .TH nano-pow 1 2025-03-12 "nano-pow v3.1.0"
+
 .SH NAME
 nano-pow \- proof-of-work generation and validation for Nano cryptocurrency
+
 .SH SYNOPSIS
 \fBnano-pow\fR [\fIOPTION\fR]... \fIBLOCKHASH\fR...
+
 .SH DESCRIPTION
-Generate work for BLOCKHASH, or multiple work values for BLOCKHASH(es).
+Generate work for \fIBLOCKHASH\fR, or multiple work values for \fIBLOCKHASH\fR(es).
+Nano PoW documentation: <https://docs.nano.org/integration-guides/work-generation/\#work-calculation-details>
+.PP
+\fIBLOCKHASH\fR is a 64-character hexadecimal string.
 .PP
 Multiple blockhash values must be separated by spaces.
+.PP
+Prints a 16-character hexadecimal work value to standard output.
+.PP
+If \fB--validate\fR is used, prints 'true' or 'false' to standard output.
+
 .SH OPTIONS
 .TP
 \fB\-h\fR, \fB\-\-help\fR
@@ -22,26 +33,39 @@ Enable additional logging output.
 Increase demand on GPU processing. Must be between 1 and 32 inclusive.
 .TP
 \fB\-t\fR, \fB\-\-threshold\fR \fITHRESHOLD\fR
-Override the minimum threshold value. Must be in hexadecimal format between 0x0 and 0xFFFFFFFF.
+Override the minimum threshold value. Higher values increase difficulty. Must be in hexadecimal format between 0x0 and 0xFFFFFFFF.
 .TP
 \fB\-v\fR, \fB\-\-validate\fR \fIWORK\fR
 Check an existing work value instead of searching for one.
+
 .SH EXAMPLES
 Search for a work nonce for a blockhash using the default threshold 0xFFFFFFF8:
-\fBnano-pow 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
-.PP
+.EX
+nano-pow 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+.EE
+
 Search for a work nonce using a custom threshold and increased effort:
-\fBnano-pow \-t fffffe00 \-e 32 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
-.PP
+.EX
+nano-pow \-t fffffe00 \-e 32 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+.EE
+
 Search for multiple nonces from a file:
-\fBnano-pow $(cat /path/to/file.txt)\fR
-.PP
+.EX
+nano-pow $(cat /path/to/file.txt)
+.EE
+
 Validate an existing work nonce against a blockhash and show debugging output:
-\fBnano-pow \-d \-v fedcba9876543210 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
+.EX
+nano-pow \-d \-v fedcba9876543210 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+.EE
+
 .SH AUTHOR
 Written by Chris Duncan.
+
 .SH BUGS
 Email: <mailto:bug-nano-pow@zoso.dev>
+
 .SH COPYRIGHT
 Copyright \(co 2025 Chris Duncan <chris@zoso.dev>
+.PP
 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>