From mboxrd@z Thu Jan 1 00:00:00 1970 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 mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4EE5EC433F5 for ; Tue, 26 Oct 2021 18:21:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2E1056103C for ; Tue, 26 Oct 2021 18:21:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236522AbhJZSX4 convert rfc822-to-8bit (ORCPT ); Tue, 26 Oct 2021 14:23:56 -0400 Received: from mail-ed1-f41.google.com ([209.85.208.41]:45736 "EHLO mail-ed1-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238205AbhJZSXr (ORCPT ); Tue, 26 Oct 2021 14:23:47 -0400 Received: by mail-ed1-f41.google.com with SMTP id m17so11822edc.12 for ; Tue, 26 Oct 2021 11:21:23 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=B8ZyIeh0cZ5pnJd3J9O2CzU5rVhkTxax74aPKerwp8I=; b=XorQMo11BBv3UdBCUTzrtEnzqPhYPAR6FG3EU/tQhjrNbUYB7YelG5Xq3RJEIsRApi +P0YhJoB+5qmjVowy1ALOArAnNhenlRaxu8Hl0bpSgdtpugfoQUMhClqo7elzLUh1dix B5TkbD/2NiAtCjeaidI2oQYsg9rQ0S5Un29pd05KW94NrHxdVGm+HMywQG1yX5yXtYM2 8YJfrahXnmBHkSA2RrGRrxYTeEfZ3FV84zuG//YQD9Zc5rceIFpuB7tf2KrBmVTJH9x2 HeIC+eJdXFWM8HEiwHWIW43yIeVYc8G2wYs2EK0ObmiMQ8a32OvwV4hsEcqEPDVLkeFl vntQ== X-Gm-Message-State: AOAM532ygdfNk2kwpgiqORLu/pwxyOR/nrMiebl5nZuGpmasez4SmIS6 zS87vJzB6e8yM0wuJhoEP796j3lN34RAxLEz5k8= X-Google-Smtp-Source: ABdhPJyfSFqqZ7716yJ6m2Rb2RnN0WDwI9IFP73HZDcwgqMwSiS7Aj1meFyn2dCY9xE/lKk9QW99v0iMT0sbAReRWl8= X-Received: by 2002:a17:906:39b:: with SMTP id b27mr1812653eja.568.1635272481703; Tue, 26 Oct 2021 11:21:21 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Eric Sunshine Date: Tue, 26 Oct 2021 14:21:10 -0400 Message-ID: Subject: Re: [PATCH] doc: fix grammar rules in commands'syntax To: =?UTF-8?Q?Jean=2DNo=C3=ABl_Avila_via_GitGitGadget?= Cc: Git List , =?UTF-8?Q?Jean=2DNo=C3=ABl_Avila?= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8BIT Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org On Tue, Oct 26, 2021 at 11:11 AM Jean-Noël Avila via GitGitGadget wrote: > doc: fix grammar rules in commands'syntax Missing space. > According to the coding guidelines, the placeholders must: > * be in small letters > * enclosed in angle brackets > > Some other rules are also applied. Perhaps just mention them here? * use hyphens rather than underscores or spaces between words * indicate repetition with `...` rather than `*` were some that I saw while reading. Overall, the patch looks good. One or two notes below... > Signed-off-by: Jean-Noël Avila > --- > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > @@ -11,7 +11,7 @@ SYNOPSIS > -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] [] > +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] [] Nice to see this attention to detail. > @@ -43,7 +43,7 @@ You could omit ``, in which case the command degenerates to > -'git checkout' -b|-B []:: > +'git checkout' -b|-B []:: Likewise. > @@ -145,11 +145,11 @@ as `ours` (i.e. "our shared canonical history"), while what you did > --b :: > +-b :: > Create a new branch named `` and start it at > ``; see linkgit:git-branch[1] for details. The names in the description need fixing too: s/_/-/g > --B :: > +-B :: > Creates the branch `` and start it at ``; > if it already exists, then reset it to ``. This is > equivalent to running "git branch" with "-f"; see Likewise: s/_/-/g > diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt > @@ -9,20 +9,20 @@ git-config - Get and set repository or global options > -'git config' [] [--type=] [-z|--null] --get-urlmatch name URL > +'git config' [] [--type=] [-z|--null] --get-urlmatch The commit message talks about using lowercase, so perhaps? s/URL/url/ > @@ -102,7 +102,7 @@ OPTIONS > ---get-urlmatch name URL:: > +--get-urlmatch :: > When given a two-part name section.key, the value for > section..key whose part matches the best to the > given URL is returned (if no such key exists, the value for Ditto. In fact, lowercase is already used in the description, but not in the item line. If wanting to match other documentation files, this would also be typeset as `` rather than in the description text, but that change may be well outside the scope of this patch. > @@ -145,7 +145,7 @@ See also <>. > --f config-file:: > +-f :: > --file config-file:: Need to apply brackets around `config-file` for the `--file` option too, just as you did for short `-f`. > @@ -246,7 +246,7 @@ Valid ``'s include: > ---get-colorbool name [stdout-is-tty]:: > +--get-colorbool []:: > > Find the color setting for `name` (e.g. `color.diff`) and output > "true" or "false". `stdout-is-tty` should be either "true" or Should you wrap `stdout-is-tty` within angle brackets within the description too? > @@ -257,7 +257,7 @@ Valid ``'s include: > ---get-color name [default]:: > +--get-color []:: > > Find the color configured for `name` (e.g. `color.diff.new`) and > output it as the ANSI color escape sequence to the standard And here? rather than `name`? > diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt > @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials > -git credential > +git credential [fill|approve|reject] The original was indeed wrong but the revised text is also slightly misleading. The square brackets suggest that the "action" is optional, but in fact it's not, so this should be using parentheses: git credential (fill|approve|reject) Also, the usage text in builtin/credential.c is wrong: % git credential usage: git credential [fill|approve|reject] It should be using parentheses, as well, but fixing that may be outside the scope of this patch (and can be done later). > diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt > @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate > -'git cvsimport' [-o ] [-h] [-v] [-d ] > +'git cvsimport' [-o ] [-h] [-v] [-d ] > [-A ] [-p ] [-P ] > - [-C ] [-z ] [-i] [-k] [-u] [-s ] > + [-C ] [-z ] [-i] [-k] [-u] [-s ] > [-a] [-m] [-M ] [-S ] [-L ] > - [-r ] [-R] [] > + [-r ] [-R] [] I wonder if should be changed to ? > diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt > @@ -12,7 +12,7 @@ SYNOPSIS > 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] > [--[no-]full] [--strict] [--verbose] [--lost-found] > [--[no-]dangling] [--[no-]progress] [--connectivity-only] > - [--[no-]name-objects] [