[PATCH v2 03/14] doc: mkimage: Reformat examples

[Sean Anderson]

This puts each example in a new paragraph and uses a hanging indent for
continued lines to increase clarity. We use tabs instead of .in or .RS for
the indent because it renders properly in both man and mandoc (which is
what many common HTML man pages use). The only nit is that the tab stops in
man default to something like 2", so reduce that to 1". We also escape
every "minus" as recommended by man-pages(7).

Signed-off-by: Sean Anderson <seanga2 at gmail.com>
---

Changes in v2:
- Escape minus signs in examples
- Indent things more robustly

 doc/mkimage.1 | 116 +++++++++++++++++++++++++++++---------------------
 1 file changed, 67 insertions(+), 49 deletions(-)

diff --git a/doc/mkimage.1 b/doc/mkimage.1
index be12843928..1015e21576 100644
--- a/doc/mkimage.1
+++ b/doc/mkimage.1
@@ -268,78 +268,96 @@ using the -f flag. But if the original input to mkimage is a binary file
 (already compiled) then the timestamp is assumed to have been set previously.
 .
 .SH EXAMPLES
-.
+.\" Reduce the width of the tab stops to something reasonable
+.ta T 1i
 List image information:
-.nf
-.B mkimage -l uImage
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-l uImage
+.EE
+.RE
 .P
 Create legacy image with compressed PowerPC Linux kernel:
-.nf
-.B mkimage -A powerpc -O linux -T kernel -C gzip \\\\
-.br
-.B -a 0 -e 0 -n Linux -d vmlinux.gz uImage
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-A powerpc \-O linux \-T kernel \-C gzip \\
+	\-a 0 \-e 0 \-n Linux \-d vmlinux.gz uImage
+.EE
+.RE
 .P
 Create FIT image with compressed PowerPC Linux kernel:
-.nf
-.B mkimage -f kernel.its kernel.itb
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-f kernel.its kernel.itb
+.EE
+.RE
 .P
 Create FIT image with compressed kernel and sign it with keys in the
-/public/signing-keys directory. Add corresponding public keys into u-boot.dtb,
+/public/signing\-keys directory. Add corresponding public keys into u\-boot.dtb,
 skipping those for which keys cannot be found. Also add a comment.
-.nf
-.B mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \\\\
-.br
-.B -c """Kernel 3.8 image for production devices""" kernel.itb
-.fi
-.
+.RS
 .P
-Add public keys to u-boot.dtb without needing a FIT to sign. This will also
+.EX
+\fBmkimage \-f kernel.its \-k /public/signing\-keys \-K u\-boot.dtb \\
+	\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
+.EE
+.RE
+.P
+Add public keys to u\-boot.dtb without needing a FIT to sign. This will also
 create a FIT containing an images node with no data named unused.itb.
-.nf
-.B mkimage -f auto -d /dev/null -k /public/signing-keys -g dev \\\\
-.br
-.B -o sha256,rsa2048 -K u-boot.dtb unused.itb
-.fi
-.
+.RS
+.P
+.EX
+\fBmkimage \-f auto \-d /dev/null \-k /public/signing\-keys \-g dev \\
+	\-o sha256,rsa2048 \-K u\-boot.dtb unused.itb
+.EE
+.RE
 .P
 Update an existing FIT image, signing it with additional keys.
-Add corresponding public keys into u-boot.dtb. This will resign all images
+Add corresponding public keys into u\-boot.dtb. This will resign all images
 with keys that are available in the new directory. Images that request signing
 with unavailable keys are skipped.
-.nf
-.B mkimage -F -k /secret/signing-keys -K u-boot.dtb \\\\
-.br
-.B -c """Kernel 3.8 image for production devices""" kernel.itb
-.fi
-.
+.RS
+.P
+.EX
+\fBmkimage \-F \-k /secret/signing\-keys \-K u\-boot.dtb \\
+	\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
+.EE
+.RE
 .P
 Create a FIT image containing a kernel, using automatic mode. No .its file
 is required.
-.nf
-.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\
-.br
-.B -c """Kernel 4.4 image for production devices""" -d vmlinuz kernel.itb
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
+	\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz kernel.itb
+.EE
+.RE
 .P
 Create a FIT image containing a kernel and some device tree files, using
 automatic mode. No .its file is required.
-.nf
-.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\
-.br
-.B -c """Kernel 4.4 image for production devices""" -d vmlinuz \\\\
-.B -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
+	\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz \\
+	\-b /path/to/rk3288\-firefly.dtb \-b /path/to/rk3288\-jerry.dtb kernel.itb
+.EE
+.RE
 .P
 Create a FIT image containing a signed kernel, using automatic mode. No .its
 file is required.
-.nf
-.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\
-.br
-.B -d vmlinuz -k /secret/signing-keys -g dev -o sha256,rsa2048 kernel.itb
-.fi
+.RS
+.P
+.EX
+\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
+	\-d vmlinuz \-k /secret/signing\-keys \-g dev \-o sha256,rsa2048 kernel.itb
+.EE
+.RE
 .
 .SH HOMEPAGE
 http://www.denx.de/wiki/U-Boot/WebHome
-- 
2.35.1