From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]); by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id a77d071e; for ; Sun, 14 Dec 2014 01:53:17 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:DHE_RSA_AES_256_CBC_SHA256:256) (envelope-from ) id 1Y033K-0007DF-Of; Sun, 14 Dec 2014 07:53:15 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1Y033K-0006Bz-I4; Sun, 14 Dec 2014 07:53:14 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Y033K-0007Cm-BQ; Sun, 14 Dec 2014 07:53:14 +0100 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1Y033K-0007jB-9n; Sun, 14 Dec 2014 07:53:14 +0100 Date: Sun, 14 Dec 2014 07:53:14 +0100 From: Ingo Schwarze To: Warren Block Cc: discuss@mdocml.bsd.lv Subject: Re: Formatting long commands in examples Message-ID: <20141214065314.GA13217@iris.usta.de> References: X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) 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/qemumips64static 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