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 0966BC433EF for ; Sat, 25 Jun 2022 17:13:07 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id D5B8984392; Sat, 25 Jun 2022 19:12:41 +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="W601YIHe"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 2887A843D1; Sat, 25 Jun 2022 19:12:32 +0200 (CEST) Received: from mail-qk1-x72c.google.com (mail-qk1-x72c.google.com [IPv6:2607:f8b0:4864:20::72c]) (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 986C983C97 for ; Sat, 25 Jun 2022 19:12:28 +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-qk1-x72c.google.com with SMTP id z12so4249975qki.3 for ; Sat, 25 Jun 2022 10:12:28 -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=75czXq3undb/O/a0jrKsSizS3r76/lTu5XJYXP8yIQk=; b=W601YIHesv3s66nhhsxl9QDweBcU9J/VZ88vthRPHCOahscvud8kvmn5XKoD1jCl+t OnjrOn6NESfPCLpwXRZijeTof4niYleYN2e1Jx8GEcAphVgNbfue3BzhMZoZT26XUb2T S7pv5jmlWMZshGVe+fiNZSPFLpAETmJIwP80nmZiE7v0Fy/VscSIEZBYY8+1cV7CRnk7 KZc5RulqAlhU9rpiWZ7cg1WcmPnYcMs1dI59a5DFBuA1TmNm5txv1xPLXpIYpAE7BdWu kGOyNWc5mDBd/bn0z4BT5NV84ZN4VQORcRNAvcHT5Ke99nQDMJSuAYA8eIsm4GjAztg9 fadw== 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=75czXq3undb/O/a0jrKsSizS3r76/lTu5XJYXP8yIQk=; b=1KrK3V4WK0Cc/DnEW87jgqWldRv0LJ8G3wT9JYbo0hH7iOZPRoEt5Ex2mOW3PXAEYe CY2jGDHNGE9dkL2TR2cRSsjftVFmTZaW+Gvt3NIEhcZ7RKPwr1kp6FvTi+mbqpiF8g/6 79zOFEj3oqJzIC/mbf0nzMnmX8RNgF00q6e8+0iqh/ncuZh11pWKKJj1jrCwUZtOT7lJ /xQneA77JEpx2hl05JxFj/mqNn8uTKqy32M8NFs7sMkLo3mqNKgEpe74TfhmIAWAmFxV UAERd2wyPwgz4ImtPo1CESn5zuH4yyEoHiVU4GBvbHiaDX/pvwuYQdyqcVUGxEmZ6Pko 5YwQ== X-Gm-Message-State: AJIora+tBywEyHjLtGZe+mkqoc4x1Jco6oAfP9I0YoTdvb7Z7GoATp2q 5G+J8uJnDDbuX9zhiQaku8GXlbqVOMQsdgMS X-Google-Smtp-Source: AGRyM1vFjuaIHI8G4urbtCDmMIgeMRLmyzb0Jjy7vbqFHCU2IKtGcTBEtxh9Wokb8L+KHwMkNhgRfA== X-Received: by 2002:a05:620a:44d5:b0:6a7:6244:e815 with SMTP id y21-20020a05620a44d500b006a76244e815mr3428151qkp.219.1656177147083; Sat, 25 Jun 2022 10:12:27 -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 bq32-20020a05620a46a000b006a785ba0c25sm4389153qkb.77.2022.06.25.10.12.26 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 25 Jun 2022 10:12:26 -0700 (PDT) From: Sean Anderson To: u-boot@lists.denx.de, Heinrich Schuchardt Cc: Simon Glass , Sean Anderson Subject: [PATCH v3 03/14] doc: mkimage: Reformat examples Date: Sat, 25 Jun 2022 13:12:10 -0400 Message-Id: <20220625171221.2391284-4-seanga2@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220625171221.2391284-1-seanga2@gmail.com> References: <20220625171221.2391284-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.6 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 --- (no changes since v2) 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 5cc2d2dc05..616fe4505d 100644 --- a/doc/mkimage.1 +++ b/doc/mkimage.1 @@ -269,78 +269,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