From ec1150407869211a0d4607419986a5f185cd8d30 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 13 Dec 2024 06:06:12 -0500 Subject: tweak man page --- uxd.rst | 51 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 11 deletions(-) (limited to 'uxd.rst') diff --git a/uxd.rst b/uxd.rst index 8aa04fe..35bf9eb 100644 --- a/uxd.rst +++ b/uxd.rst @@ -38,6 +38,14 @@ terminal. It's assumed that the terminal supports ANSI-style color and UTF-8. See **TERMINAL SUPPORT** below. If you want to pipe the output to a pager, try **less -R**. +OPTIONS +======= + +There are no options yet. + +OUTPUT FORMAT +============= + 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 data (or empty cells, if the last line of the dump is for fewer than @@ -48,10 +56,22 @@ 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. -OPTIONS -======= +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 **c3-b1** (for an ñ character). -There are no options yet. +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'll be two dashes: **c3--b1**). + +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's easy to +understand once you see it a few times. EXAMPLE ======= @@ -72,13 +92,14 @@ The colors are indicated by G/Y/P, for green, yellow, and purple. The character above each letter is displayed in that color. From the colorization, and from the dashes between the bytes, it's -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". The newline is displayed in purple because it's not a regular printable character. Its human-readable representation is ↵. Note that if a regular ↵ character appears in the input, it'll be -rendered in either green or yellow (as a regular character). +rendered in either green or yellow (so you can tell it's not just +another newline). COLORS ====== @@ -112,21 +133,29 @@ TERMINAL SUPPORT **uxd** should work with any modern terminal that supports color, ANSI-style escape sequences, Unicode, and UTF-8 rendering. -The author's testing is done primarily with **urxvt**\(1). Other -terminals aren't tested as often. +The author's testing is done primarily with **urxvt**\(1). Other +terminals aren't tested as often. Some terminals may need UTF-8 +enabled, if it's not on by default (e.g. xterm). Known to work: urxvt, xterm, st, xfce4-terminal, gnome-terminal, kitty, the Linux console (but see **FONTS**, below). -Known **not** to work: rxvt (doesn't support Unicode at all). +Known **not** to work: rxvt (doesn't support Unicode at all), and its +derivatives such as aterm. FONTS ===== For the human-readable column to display correctly, you'll need a font -with lots of glyphs. Try *Deja Vu Sans Mono*, *Symbola*, *Quivira*. -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 *Deja Vu Sans Mono*, *Symbola*, or *Quivira* +(although it's 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. + +Any glyph your font lacks, you'll see as a dotted box, or perhaps +a solid block. This isn't something **uxd** can do anything about; +you'll have to use a different font, or (if you use urxvt) add another +font to your URxvt*font resource. The Linux console is capable of rendering UTF-8, but it's incapable of displaying more than 512 glyphs. Most console fonts only define -- cgit v1.2.3