From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from wonkity.com (wonkity.com [67.158.26.137]);
	by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id ab2b3b8d;
	for <discuss@mdocml.bsd.lv>;
	Sat, 13 Dec 2014 20:15:13 -0500 (EST)
Received: from wonkity.com (localhost [127.0.0.1])
	by wonkity.com (8.14.9/8.14.9) with ESMTP id sBE1FBSp047462
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO)
	for <discuss@mdocml.bsd.lv>; Sat, 13 Dec 2014 18:15:11 -0700 (MST)
	(envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
	by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id sBE1F7ts047458
	for <discuss@mdocml.bsd.lv>; Sat, 13 Dec 2014 18:15:11 -0700 (MST)
	(envelope-from wblock@wonkity.com)
Date: Sat, 13 Dec 2014 18:15:07 -0700 (MST)
From: Warren Block <wblock@wonkity.com>
To: discuss@mdocml.bsd.lv
Subject: Formatting long commands in examples
Message-ID: <alpine.BSF.2.11.1412131800260.6198@wonkity.com>
User-Agent: Alpine 2.11 (BSF 23 2013-08-11)
X-Mailinglist: mdocml-discuss
Reply-To: discuss@mdocml.bsd.lv
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Sat, 13 Dec 2014 18:15:11 -0700 (MST)

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