tweak man page

1 files changed, 38 insertions, 11 deletions

diff --git a/uxd.1 b/uxd.1
index 55c7b59..d9fb7d4 100644
--- a/uxd.1
+++ b/uxd.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "UXD" 1 "2024-12-12" "0.0.1" "Urchlay's Utilities"
+.TH "UXD" 1 "2024-12-13" "0.0.1" "Urchlay's Utilities"
 .SH NAME
 uxd \- UTF-8 hex dumper
 .SH SYNOPSIS
@@ -50,6 +50,10 @@ Output is written to standard output, which is normally a
 terminal. It\(aqs assumed that the terminal supports ANSI\-style color and
 UTF\-8. See \fBTERMINAL SUPPORT\fP below. If you want to pipe the output
 to a pager, try \fBless \-R\fP\&.
+.SH OPTIONS
+.sp
+There are no options yet.
+.SH OUTPUT FORMAT
 .sp
 Each line of output consists of eighteen columns: the offset from the
 start of the file (in hex; minimum 4 digits), 16 bytes of hex
@@ -60,9 +64,23 @@ The hex bytes and human\-readable data are colorized to make it obvious
 which bytes make up each character. Since UTF\-8 is a variable\-width
 encoding, this means that one character may be composed of up to
 4 bytes.
-.SH OPTIONS
 .sp
-There are no options yet.
+The hex bytes that make up one character are displayed in the same
+color, which alternates between yellow and green for successive
+characters. In addition, they have dashes instead of spaces between
+them. An example would be \fBc3\-b1\fP (for an ñ character).
+.sp
+The 16\-byte hex display always has an extra "spacer" column in the
+center. Normally this is a space, but if a multibyte character spans
+it, it will be a dash (so there\(aqll be two dashes: \fBc3\-\-b1\fP).
+.sp
+Since the output lines are always 16 hex bytes, multibyte characters
+can span two lines. When this happens, the character itself will be
+printed on the first line, along with the first byte(s) on hex. The
+last hex byte will be followed by a dash, and the next line of hex
+dump will have the remaining bytes (in the same color as the first
+bytes and character). This sounds complicated, but it\(aqs easy to
+understand once you see it a few times.
 .SH EXAMPLE
 .sp
 It\(aqs hard to give a proper example, since man pages don\(aqt support
@@ -89,13 +107,14 @@ The colors are indicated by G/Y/P, for green, yellow, and purple. The
 character above each letter is displayed in that color.
 .sp
 From the colorization, and from the dashes between the bytes, it\(aqs
-obvious that the "c2 a5" is the hex representation of the first ¥
+obvious that "c2 a5" is the hex representation of the first ¥
 character, and that the ǥ is represented by "c7 a5".
 .sp
 The newline is displayed in purple because it\(aqs not a regular
 printable character. Its human\-readable representation is ↵. Note
 that if a regular ↵ character appears in the input, it\(aqll be
-rendered in either green or yellow (as a regular character).
+rendered in either green or yellow (so you can tell it\(aqs not just
+another newline).
 .SH COLORS
 .INDENT 0.0
 .TP
@@ -133,19 +152,27 @@ Codepoints above U+10FFFF, which are disallowed by RFC 3629.
 \fBuxd\fP should work with any modern terminal that supports color,
 ANSI\-style escape sequences, Unicode, and UTF\-8 rendering.
 .sp
-The author\(aqs testing is done primarily with \fBurxvt\fP(1).  Other
-terminals aren\(aqt tested as often.
+The author\(aqs testing is done primarily with \fBurxvt\fP(1). Other
+terminals aren\(aqt tested as often. Some terminals may need UTF\-8
+enabled, if it\(aqs not on by default (e.g. xterm).
 .sp
 Known to work: urxvt, xterm, st, xfce4\-terminal, gnome\-terminal, kitty, the Linux console (but
 see \fBFONTS\fP, below).
 .sp
-Known \fBnot\fP to work: rxvt (doesn\(aqt support Unicode at all).
+Known \fBnot\fP to work: rxvt (doesn\(aqt support Unicode at all), and its
+derivatives such as aterm.
 .SH FONTS
 .sp
 For the human\-readable column to display correctly, you\(aqll need a font
-with lots of glyphs. Try \fIDeja Vu Sans Mono\fP, \fISymbola\fP, \fIQuivira\fP\&.
-If you use urxvt, it searches for glyphs in multiple fonts, so you can
-use all of the above at once.
+with lots of glyphs. Try \fIDeja Vu Sans Mono\fP, \fISymbola\fP, or \fIQuivira\fP
+(although it\(aqs not really a terminal font). If you use urxvt, it
+searches for glyphs in multiple fonts, so you can use all of the above
+at once.
+.sp
+Any glyph your font lacks, you\(aqll see as a dotted box, or perhaps
+a solid block. This isn\(aqt something \fBuxd\fP can do anything about;
+you\(aqll have to use a different font, or (if you use urxvt) add another
+font to your URxvt*font resource.
 .sp
 The Linux console is capable of rendering UTF\-8, but it\(aqs incapable
 of displaying more than 512 glyphs. Most console fonts only define