From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS3215 2.6.0.0/16 X-Spam-Status: No, score=-3.5 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by dcvr.yhbt.net (Postfix) with ESMTP id 2F18F1F403 for ; Thu, 13 Oct 2022 15:39:50 +0000 (UTC) Authentication-Results: dcvr.yhbt.net; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="mX6xpLDy"; dkim-atps=neutral Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229723AbiJMPjs (ORCPT ); Thu, 13 Oct 2022 11:39:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42084 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229525AbiJMPjl (ORCPT ); Thu, 13 Oct 2022 11:39:41 -0400 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5E198C58B1 for ; Thu, 13 Oct 2022 08:39:35 -0700 (PDT) Received: by mail-wr1-x42b.google.com with SMTP id j7so3466965wrr.3 for ; Thu, 13 Oct 2022 08:39:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=RGzn+Xdtg++XHOYU/5c7xauynG3SHzS1630PFxp1q8Y=; b=mX6xpLDymEglCEbjYqctgFW3yunoEjxhwg883BfBlK841XLOhKgiSy4nK51TJNRhHc 6pYufzPwPcMW2nv/wC2PGcHRXYZz9pZf8Crky9Q336tLd1hMq8MCjkeNRT6KezNeM5t4 MuYFK2pxv447zuVLiAoZ2VITZJxwPUdxB1PhnFX+LwEZESgM3d8JnS3o8mgxmYTdKKIY RpWaul+W5JUjJkiuZniWypI6Q7qJDdYakuO9OCElpQ0++JP6df30i4ep36UgM6I3PUIu LEgW6ovm2Gnr7bTbHfdmcJNN4hTphFxazV9NtkuvjjfBgn0AUjB0WMVowJ3na0FFO9ki 3ddw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=RGzn+Xdtg++XHOYU/5c7xauynG3SHzS1630PFxp1q8Y=; b=aCd1KRcpTCQsC8pGyADXptR15gtr2IA3vgchlbToX78aKh5wbvZ1LoqAaFEIRmKwzS oIo/KQOZ2DoCGwRutxWc5EHxWOj9USJPusEJsL4RPzbwMZcSHuG28ncD/VLnaSueMmi7 rFrQi1UqOJu1AxNIuzmnyyXEl9m7adZuqki5YBpNZzjaQEte9EozWvX91w42+7AgYYeI e3/vCobrr980sr1FNeF7Wh0t9hYdEx6DwvSlMpHL2H5n6wnGhxzjgcXsmW40CncSgH1D ULMFeP7ZAEbfESyJLv31Mpj7kKt+jtMnqN1AalGlOv/fo+k4PFrfdjI8iExME81jmown gLGA== X-Gm-Message-State: ACrzQf1LEdURlz0/bGV0czWwVB/N/8LH3SAAvckR1Ww43TiuyNhBOs4D JdHrqvHtOBKTmv+f+PUMcDgZFPhVxJQQbA== X-Google-Smtp-Source: AMsMyM7G3WjGAcbXTgRzWuD6vCVYZmqYJl+ljRIuoRvcu4pr+GHxB4W6w1UVIsHDTldzoAblxtlCMA== X-Received: by 2002:a5d:5691:0:b0:22c:db35:7939 with SMTP id f17-20020a5d5691000000b0022cdb357939mr409743wrv.102.1665675573365; Thu, 13 Oct 2022 08:39:33 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id da12-20020a056000408c00b0022a3a887ceasm2258130wrb.49.2022.10.13.08.39.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Oct 2022 08:39:32 -0700 (PDT) From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= To: git@vger.kernel.org Cc: Junio C Hamano , Victoria Dye , Taylor Blau , Emily Shaffer , Jonathan Nieder , John Cai , Eric Sunshine , =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Subject: [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Date: Thu, 13 Oct 2022 17:38:54 +0200 Message-Id: X-Mailer: git-send-email 2.38.0.1085.gb7e61c3016c In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org We are currently wildly inconsistent in whether the SYNOPSIS in the manual page matches the first line of the -h output, and as we add new options we routinely forget to add them to one or the other (or both). Without a more complex approach it's hard to do something about the "or both" case. But we can rather easily test whether the -h output matches the *.txt version, and report differences. As this series shows that allows us to fix a lot of issues we've effectively already "fixed", we just fixed them in one version, but not the other. For the rest of the general overview (the first paragraphs are copy/pasted) see the v1 at: https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com For v3 see: https://lore.kernel.org/git/cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com/ Junio: A trivial v5 re your https://lore.kernel.org/git/xmqqlepvsgeo.fsf@gitster.g/; FWIW I saw that existing prose, but figured we could continue to use "any paths", but it's rephrased to incorporate "" here, no other changes. I'm aware of the minor merge conflict with the builtin/symbolic-ref.c topic of yours, but I see you've resolved it on your side, so this is still based on "master". Ævar Arnfjörð Bjarmason (34): tests: assert *.txt SYNOPSIS and -h output CodingGuidelines: update and clarify command-line conventions builtin/bundle.c: indent with tabs bundle: define subcommand -h in terms of command -h doc SYNOPSIS: don't use ' for subcommands doc SYNOPSIS: consistently use ' for commands built-ins: consistently add "\n" between "usage" and options doc txt & -h consistency: word-wrap doc txt & -h consistency: fix incorrect alternates syntax doc txt & -h consistency: add "-z" to cat-file "-h" doc txt & -h consistency: balance unbalanced "[" and "]" doc txt & -h consistency: correct padding around "[]()" stash doc SYNOPSIS & -h: correct padding around "[]()" doc txt & -h consistency: use "", not "..." doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" doc txt & -h consistency: fix mismatching labels doc txt & -h consistency: add or fix optional "--" syntax doc txt & -h consistency: make output order consistent doc txt & -h consistency: add missing options and labels doc txt & -h consistency: make "rerere" consistent doc txt & -h consistency: make "read-tree" consistent doc txt & -h consistency: make "bundle" consistent doc txt & -h consistency: use "git foo" form, not "git-foo" doc txt & -h consistency: add missing options doc txt & -h consistency: make "stash" consistent doc txt & -h consistency: make "annotate" consistent doc txt & -h consistency: use "[