doc/Guidebook.mn: Completely revamp Figure 3

This is my attempt to revise the figure by working _with_ tbl(1)
and nroff(1)/troff(1) features instead of fighting them or enduring
suffering and significant maintenance challenges.

* Stop using mn(7) display macros; the other two figures didn't and they
  don't appear to be buying much.
* Use `tr` character translation feature to temporarily remap characters
  for clarity of input.  It's convenient to input ordinary characters
  here since the table's contents are (mostly) character-cell art.
  Remap `-` to minus sign and `@` to the "reverse solidus" special
  character.  (`\` is the default *roff escape character.  It can be
  changed, but attempting that seems hopeless inside a tbl(1) table.)
  Revert the translations after the table.  (There's nothing special
  about `@`; you could choose any other character that isn't otherwise
  needed in the table.)
* Use `box` region option as with Figures 1 and 2.  Perhaps this wasn't
  done because those are meant to depict a terminal window, but Figure 2
  depicts only part of one, so its top border is a fib.
* Use `expand` region option to obtain roughly the same spread-out
  effect that the table was laboriously using empty columns and the `e`
  column modifier for.
* Consequently, reduce the column count to 2; both have real content.
* Annotate both keycap diagrams--in part for clarity, but also to make
  it more obvious that the columns will balance in width.

These changes don't require GNU extensions to *roff or tbl except,
arguably, the \(rs special character.  But support for that special
character identifier is easily added to any device-independent troff;
see §23.2 of CSTR #54 (Kernighan 1992 revision) or groff_font(5).  Or I
can prepare a patch--just ask me.  But given that no one seems to have
complained about the disaster that AT&T tbl/nroff must have been making
of Figures 1 and 2 for decades, I'm guessing this isn't a practical
concern.  Any if it _is_ a problem, `\e` can be used instead of `\(rs`.
(I didn't use it because what is wanted is the backslash glyph
specifically [to mirror `/`], not "the escape character".  But given the
constraints imposed by use of tbl(1), it's an academic point.)
This commit is contained in:
G. Branden Robinson
2023-11-06 13:13:24 -06:00
parent 9658f6769d
commit 0571cb395e

View File

@@ -617,32 +617,23 @@ If you sense or remember a monster there, you will fight the monster
instead.
Only these one-step movement commands cause you to fight monsters; the
others (below) are \(lqsafe.\(rq
.SD n
.\" note: the two number pad layouts are separated by a tab on each line;
.\" [that's out of date; it's now tab,backslash,space,tab]
.\" converting those tabs to spaces will screw up the formatting;
.\" the '(if ... set)' line starts with <backslash><space><tab>
.\" and is intended to line up with the right hand layout rather
.\" than be centered. Second column forces the label to be evenly
.\" spaced between first and third; Phantom fourth column forces
.\" the whole to shift left since fully centered doesn't look good.
.\" "Figure 3 " includes a trailing space to shift left a little.
.ft CR
.tr -\-@\(rs
.TS
center;
ce c ce ce.
y k u \ 7 8 9\ \"
\\ | / \ \\ | /\ \"
h\- . \-l \ 4\- . \-6\ \"
/ | \\ \ / | \\\ \"
b j n \ 1 2 3\ \"
\fR\ \ (if \fBnumber_pad\fR is set)\ \"
box center expand;
C C.
y k u 7 8 9
@ | / @ | /
h- . -l 4- . -6
/ | @ / | @
b j n 1 2 3
\fR(\fBnumber_pad\fP off) \fR(\fBnumber_pad\fP on)
.TE
.tr --@@
.ft R
.if t .sp 0.5v
.ce 1
Figure 3
.ED
.
.lp [YUHJKLBN]
Go in that direction until you hit a wall or run into something.