discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Warren Block <wblock@wonkity.com>
Cc: discuss@mdocml.bsd.lv
Subject: Re: Formatting long commands in examples
Date: Sun, 14 Dec 2014 07:53:14 +0100	[thread overview]
Message-ID: <20141214065314.GA13217@iris.usta.de> (raw)
In-Reply-To: <alpine.BSF.2.11.1412131800260.6198@wonkity.com>

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

  reply	other threads:[~2014-12-14  6:53 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-12-14  1:15 Warren Block
2014-12-14  6:53 ` Ingo Schwarze [this message]
2014-12-15 23:28   ` Warren Block

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20141214065314.GA13217@iris.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mdocml.bsd.lv \
    --cc=wblock@wonkity.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).