* Re: Formatting long commands in examples
2014-12-14 1:15 Formatting long commands in examples Warren Block
@ 2014-12-14 6:53 ` Ingo Schwarze
2014-12-15 23:28 ` Warren Block
0 siblings, 1 reply; 3+ messages in thread
From: Ingo Schwarze @ 2014-12-14 6:53 UTC (permalink / raw)
To: Warren Block; +Cc: discuss
Hi Warren,
Warren Block wrote on Sat, Dec 13, 2014 at 06:15:07PM -0700:
> We've had a request to add long commands with long literal values to
> a man page.
>
> For an example, see the "magic" and "mask" values at
> https://wiki.freebsd.org/QemuUserModeHowTo
>
> .Bd -ragged -offset indent takes some liberties with wrapping the
> quoted literal values, and does not produce a warning.
>
> .Bd -ragged -offset indent
> # binmiscctl add mips64elf --interpreter "/usr/local/bin/qemu-mips64-static"
> --magic "\\x7f\\x45\\x4c\\x46\\x02\\x02\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x08"
> --mask "\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xfe\\xff\\xff"
> --size 20 --set-enabled
> .Ed
Even though it happens to work in this example, do not use \\ in roff,
use \e. The former is likely to break once you get near macros and
copy mode. See mandoc_char(7), "Backslashes".
> That produces an 80-column output like this:
>
> # binmiscctl add mips64elf --interpreter "/usr/local/bin/qemu-
> mips64-static" --magic
> "\x7f\x45\x4c\x46\x02\x02\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
> --mask
> "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xff
> --size 20 --set-enabled
>
> In addition to the undesirable wrapping of the value in the first
> line,
According to gmdiff, output from groff and mandoc is byte-for-byte
identical in this example. You may not desire hyphenating gemu-mips64,
but what you are telling mdoc(7) with .Bd -ragged is "display this as
normal text, no special formatting, please". And in normal text, it
is allowed to hyphenate words at existing hyphens, even if .hy is
switched off.
In mandoc, i can prevent the hyphenation by using either of these:
qemu\&-mips64
qemu-\&mips64
qemu\(hymips64
Arguably, that's a bug in mandoc, because none of these prevent
hyphenation in groff.
Another bad idea would be using Unicode, specifically \[u2011],
NON-BREAKING HYPHEN. While that works fine in groff and mandoc -Tutf8
and -Thtml output mode, it produces
/usr/local/bin/qemu<?>mips64<?>static
in mandoc -Tascii and
/usr/local/bin/qemumips64static
in groff -Tascii. Besides, Unicode character names are not portable
across roff implementations.
Arguably, character definitions should be added to groff and mandoc
for this character, but even then, portability will be limited.
> the hex strings are cut off.
Cannot reproduce, happily produces overlong lines here.
Is this maybe a problem with your (virtual?) terminal?
Some terminals wrap overlong lines, some truncate, some
allow horizontal scrolling, some allow switching among various
different ways to handle overlong lines...
What does
mandoc ... | hexdump -C
tell you?
> .Dl does not like this much, either. One very long line:
>
> .Dl "# binmiscctl add mips64elf --interpreter \"/usr/local/bin/qemu-mips64-static\" --magic \"\\x7f\\x45\\x4c\\x46\\x02\\x02\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x08\" --mask \"\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xfe\\xff\\xff\" --size 20 --set-enabled"
>
> Whether or not the parameter is quoted, it only produces this:
>
> # binmiscctl add mips64elf --interpreter
Confirmed, and again, byte-for-byte identical output from groff
and mandoc.
Note that \" introduces a comment in roff, so i'm not really that
surprised. The roffly-correct way to escape double quotes in
double-quoted macro arguments is to double them, see roff(7).
Once you replace \" with "", mandoc output is closer to what you
want, but now groff indeed freaks out about the \\ on the macro
line, as i threatened above. Replacing \\ with \e, like this,
.Dd December 14, 2014
.Dt TEST 1
.Os
.Sh NAME
.Nm test
.Nd for Warren
.Sh DESCRIPTION
.Dl "# binmiscctl add mips64elf --interpreter ""/usr/local/bin/qemu-mips64-static"" --magic ""\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08"" --mask ""\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff"" --size 20 --set-enabled"
produces byte by byte identical output with groff and mandoc, except that -
groff again hyphenates qemu-mips64, while mandoc does not.
> There might not be a good way to show these commands.
My recommendation for displaying complete example command lines,
in general, is indeed .Dl. When that gets too long and wraps,
you can sometimes improve formatting by breaking it into a multi-line
literal display, in a way permitted by the syntax of the target
language, in this case, sh(1). So my recommendation would be:
.Dd December 14, 2014
.Dt TEST 1
.Os
.Sh NAME
.Nm test
.Nd for Warren
.Sh DESCRIPTION
.Bd -literal -offset indent
binmiscctl add mips64elf \e
--interpreter "/usr/local/bin/qemu-mips64-static" \e
--magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e
\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e
--mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
\exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
--size 20 --set-enabled
.Ed
> Is there a "least bad" way?
The above seems good rather than least bad, does it?
It is fully portable and formats byte-for-byte identically
with groff and mandoc.
Yours,
Ingo
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 3+ messages in thread