Formatting long commands in examples

Formatting long commands in examples

[Warren Block]

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

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, 
the hex strings are cut off.

.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

There might not be a good way to show these commands.  Is there a "least 
bad" way?  It would be preferable to wrap the long arguments rather than 
silently truncate them.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Formatting long commands in examples

[Ingo Schwarze]

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

Re: Formatting long commands in examples

[Warren Block]

On Sun, 14 Dec 2014, Ingo Schwarze wrote:

> 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.

Perfect!  Thank you!
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv