Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id B8EB5CCA473 for ; Sun, 12 Jun 2022 22:14:59 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id CAC0284444; Mon, 13 Jun 2022 00:14:31 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="nuSz3FwG"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 710EF84434; Mon, 13 Jun 2022 00:14:22 +0200 (CEST) Received: from mail-qv1-xf2e.google.com (mail-qv1-xf2e.google.com [IPv6:2607:f8b0:4864:20::f2e]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 1050F83E73 for ; Mon, 13 Jun 2022 00:14:19 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=seanga2@gmail.com Received: by mail-qv1-xf2e.google.com with SMTP id t6so1958437qvh.1 for ; Sun, 12 Jun 2022 15:14:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=bUu19OgpQwx+heI2GSE3T7UZQ6NLH2QhawzQvcXqXQk=; b=nuSz3FwGg0/7jeHzdBlWX6gWtV9vIFLl/JBS0weBU2yNkFlN2ynU9syxWIR8YcRMlb xLjLpn5LbYqeKSuVMTrOofLlDly3CKVpy9a4bgA27OZ6WN2F/eE8i34SX2tNOveE8QOf RD7ZrHfiqxe4NeukB7sMRo4P3I2hiO2HAz1Q7sewkg8Q7s1W4CkZeCEVNwrqmMeHARci GwHTa9/qv+a+nSBR/MeGb2Oqy9C0rRdpLAw6ucmMYQDv+G2yazrCVonyTssgRjp0Fa2R C1gQHyk19/x6Lu3J/bhsp1/8ySncdpINheCt2hva5uTfl2HWrZOgNfvVQ1cf7Pd+mJe6 zTPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=bUu19OgpQwx+heI2GSE3T7UZQ6NLH2QhawzQvcXqXQk=; b=TrEUO2NximY7oR8CjJFSnHdmGxdDrKjrk8SYIdn1APa4uOOk54794NptZ4Qk3ZdTu3 zH/skfOGNOa+sMiWHTjCP7d36ftiI7KaErOVCSvJrQmz4Uln1IqJ0MptjgNw7M8DRZEo DFQc89FUJHvs9MV/z++/xguKAXx2IQP/RjGT6+J98f3miKKyrgYk7AJU/4mAptgsfP3i Em82xL8lrBG8bYLv0KnBpH+/NYBWRKrmWwWZPAEYH851pG9b1rkN0f0y9ywtVWsvr2O8 dCxWEYTkjSVmA0dPXdVRZFd7eA+WhxxuhbUcxebJQiZpXdPKDPtZHh3nZebjuuecVOfe X/tw== X-Gm-Message-State: AOAM53166LCKIuHI36Ehc+dEvYM7zfRvvF3FosDa7NDmtZdjzCJ32m1H PXDZDLM/bce0dwafgquU5jVieDFnEuaOElST X-Google-Smtp-Source: ABdhPJzvcaURJr+JAFohNd8890IskuIqED/yfPil/+p164aYQJTi7QhjAZSSBqCSzHaAvQCklTyW+g== X-Received: by 2002:a05:6214:2245:b0:464:6b29:f443 with SMTP id c5-20020a056214224500b004646b29f443mr45645773qvc.99.1655072057551; Sun, 12 Jun 2022 15:14:17 -0700 (PDT) Received: from localhost (pool-173-73-95-180.washdc.fios.verizon.net. [173.73.95.180]) by smtp.gmail.com with UTF8SMTPSA id x13-20020ac8538d000000b00304ec60f711sm3738025qtp.39.2022.06.12.15.14.17 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 12 Jun 2022 15:14:17 -0700 (PDT) From: Sean Anderson To: u-boot@lists.denx.de, Heinrich Schuchardt Cc: Simon Glass , Sean Anderson Subject: [PATCH v2 03/14] doc: mkimage: Reformat examples Date: Sun, 12 Jun 2022 18:14:00 -0400 Message-Id: <20220612221411.1608406-4-seanga2@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220612221411.1608406-1-seanga2@gmail.com> References: <20220612221411.1608406-1-seanga2@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.5 at phobos.denx.de X-Virus-Status: Clean 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 --- 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