From patchwork Sun Aug 11 15:20:10 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13759766 Received: from mail-wm1-f53.google.com (mail-wm1-f53.google.com [209.85.128.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5D972EAE9 for ; Sun, 11 Aug 2024 15:20:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389619; cv=none; b=cqewzPzmSJCitk4WNgIc3qR1UAqYMCkZizNzR2f5X2XPBUaghReIk5/1j/5Rq7XiGwz+7SANemY5plEvdLbKBtJgUnVhGggawVRMki96L5fNU4Nsg05Nzv8jXc8Xq495x5BN4O4hyonO4a7FciUY2d3HzB8t/Q4aMVwyrDlwAg4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389619; c=relaxed/simple; bh=20pSkOmI4J8NlDI2OhZ8Jruc3/MkiGWz+hyTBZ4nTjs=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=V6LuUjjW8387LE8HmlTtnnbO+7lD6hskoO1CGy8xXqhigTateloexel9AjjVjTOMvoz0kdNmduqJBovf+Zk04DvfQt00vV16kMlhKYC2E9Aw70P1xdp2U4Xc/YUgKESHXbC5btxxWb5JKHEbbeXzEUQCepycF9F21lmlsIUY/dw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=WgsUOhL/; arc=none smtp.client-ip=209.85.128.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="WgsUOhL/" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-4266f3e0df8so24656885e9.2 for ; Sun, 11 Aug 2024 08:20:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1723389615; x=1723994415; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=2u/WbOBbN0ZFVzr77I3VUk1mvc5QNsLeAjJjo4K9qfA=; b=WgsUOhL/Y7DUmPLv3hfGub/RxsLhsIIkKv8TYYX49Vt067p992fjIJ5uSpKTyECEcF rIrCfRg2BfoFfPzb3FE4yLa7h7RJHFWjvIIXFTGZEHxuXRaGocGIhH3Zewyqb/G4wh/D 9zkclIVCb8/+89JFuIyzxuaAbGkJ3m6eLKqEuD7eFgb0x8wDBi9u35RTIgPquumGtpNR E7nAllhIshWjsl/wRlkw7buZUfPkiW3KakopTQBkluMRHp8VJsFC2N1TqE1Rl7n1VhaE gSbKijSDNTtPd0qwRmjZoKm7ElNFDrfNEzJfiVJy3jK+kmvIdLwruVcWK4F5tjk0Hp1M Fi/g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723389615; x=1723994415; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=2u/WbOBbN0ZFVzr77I3VUk1mvc5QNsLeAjJjo4K9qfA=; b=QAjZjZOMttsuZri1xdgvckFW4FSwSvplTOfhltmmF5jlGZzhASox23wPInxfYniatJ 8tv5WghQCxtLULeHsURPfJ6vF/Vtg9wxMC+qP8hRx3722+0jqNXSo1WxGNhwgNmgyong L5eQJFmImSRmqM3HVmhWqvGoVaDlPgty26Mrm9LfD+pQeUyTLA0iumAadQ17RFGVfmww 38ci8+ip+vEN4lFYOeptI1PiiUySxlhMxriMxOtWs6+cba5P+CrO7tn6dx1/FlqgLeqq Jij5CkueJIYfUxc89zqwoIxMzStfeuy9nzGNDMxtRF8XiPGpIiaxLG3rELNT/ziSDwGz +uyg== X-Gm-Message-State: AOJu0Yyi4rcVrWUM+CIchImXVd9HUXniBWyWYtkWJgrdaYB6hwJE8NLh 5JWjB/8MQH3PSsdQS1obIqL27ma2mwsdtRFZD+yXGjnaARlhMnoSROnzrw== X-Google-Smtp-Source: AGHT+IGl9g7Jw4nM49h5nPAiRID0aj9Y1XKH3x1GKqFps+06i253tQjDT5CfVKc9EA2BGX+fvCLQCw== X-Received: by 2002:a05:600c:190f:b0:427:d8f2:550 with SMTP id 5b1f17b1804b1-429c3a19f7cmr41357705e9.14.1723389614918; Sun, 11 Aug 2024 08:20:14 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4290c738947sm151729315e9.10.2024.08.11.08.20.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 11 Aug 2024 08:20:14 -0700 (PDT) Message-Id: <0d7c1dd8f26f8bdfd93bcbf981b5bb6a6041f069.1723389612.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 11 Aug 2024 15:20:10 +0000 Subject: [PATCH v3 1/3] doc: introduce a synopsis custom paragraph attribute Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= In order to follow the common manpage usage, the synopsis of the commands needs to be heavily typeset. A first try was performed with using native markup, but it turned out to make the document source almost unreadable, difficult to write and prone to mistakes with unwanted Asciidoc's role attributes. In order to both simplify the writer's task and obtain a consistant typesetting in the synopsis, a custom 'synopsis' paragraph type is created and the backends of asciidoc and asciidoctor take in charge to correctly add the required typesetting. additionally, a 's' macro ('s' standing for synopsis) is introduced to allow writers to freely apply automatic styling whereever required. Signed-off-by: Jean-Noël Avila --- Documentation/asciidoc.conf | 21 +++++++++++++++- Documentation/asciidoctor-extensions.rb | 33 +++++++++++++++++++++++++ t/t0450-txt-doc-vs-help.sh | 11 +++------ 3 files changed, 57 insertions(+), 8 deletions(-) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 60f76f43eda..04405453415 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -9,7 +9,7 @@ [macros] (?su)[\\]?(?Plinkgit):(?P\S*?)\[(?P.*?)\]= - +(?su)[\\]?(?Ps):(?P\S*?)\["(?P.*?)"\]= [attributes] asterisk=* plus=+ @@ -28,6 +28,9 @@ ifdef::backend-docbook[] {0#} {0#{target}{0}} {0#} + +[s-inlinemacro] +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1\2', '{attrlist}'))} endif::backend-docbook[] ifdef::backend-docbook[] @@ -56,4 +59,20 @@ ifdef::backend-xhtml11[] git-relative-html-prefix= [linkgit-inlinemacro] {target}{0?({0})} + +[s-inlinemacro] +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1\2', '{attrlist}'))} + +endif::backend-xhtml11[] + +ifdef::backend-docbook[] +ifdef::doctype-manpage[] +[paradef-default] +synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?+)!\\1\\2!g;s!<[-a-zA-Z0-9.]+>!\\0!g'" +endif::doctype-manpage[] +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[paradef-default] +synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?)!\\1\\2!g;s!<[-a-zA-Z0-9.]+>!\\0!g'" endif::backend-xhtml11[] diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index d906a008039..46cbbbbfd76 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -24,6 +24,21 @@ module Git end end + class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :s + match(/s:\["(.+?)"\]/) + + def process(parent, target, attrs) + l = target.gsub(/([\[\] |()]|^|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}') + .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') + .gsub(']', ']{empty}') + + create_inline parent, :quoted, l, attributes: { 'subs' => :normal } + end + end + class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor def process document, output if document.basebackend? 'docbook' @@ -39,10 +54,28 @@ module Git output end end + + class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor + + use_dsl + named :synopsis + parse_content_as :simple + + def process parent, reader, attrs + outlines = reader.lines.map do |l| + l.gsub(/([\[\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\1{empty}`\2`{empty}') + .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') + .gsub(']', ']{empty}') + end + create_block parent, :verse, outlines, attrs + end + end end end Asciidoctor::Extensions.register do inline_macro Git::Documentation::LinkGitProcessor, :linkgit + inline_macro Git::Documentation::SynopsisMacroProcessor + block Git::Documentation::SynopsisBlock postprocessor Git::Documentation::DocumentPostProcessor end diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh index 69917d7b845..f99a69ae1b7 100755 --- a/t/t0450-txt-doc-vs-help.sh +++ b/t/t0450-txt-doc-vs-help.sh @@ -56,14 +56,11 @@ txt_to_synopsis () { fi && b2t="$(builtin_to_txt "$builtin")" && sed -n \ - -e '/^\[verse\]$/,/^$/ { + -E '/^\[(verse|synopsis)\]$/,/^$/ { /^$/d; - /^\[verse\]$/d; - s/_//g; - s/++//g; - s/`//g; - s/{litdd}/--/g; - s/'\''\(git[ a-z-]*\)'\''/\1/g; + /^\[(verse|synopsis)\]$/d; + s/\{litdd\}/--/g; + s/'\''(git[ a-z-]*)'\''/\1/g; p; }' \ From patchwork Sun Aug 11 15:20:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13759768 Received: from mail-wr1-f45.google.com (mail-wr1-f45.google.com [209.85.221.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 58C4E14885E for ; Sun, 11 Aug 2024 15:20:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389620; cv=none; b=NoISG4vx77Utyx2y8vhAPmivab1wppYUm2W/0NAT2BJek60yQxj1ABUd30CysZxxOBIXIkFaxm4b8Qfxw753Mg7uk06clFDOGJQHdq02kBxIXt0qc5CPDq2JDztsh4UVF+O+VcV1WQgeIMB8kokGvebnU4WXz3nVTivrWD1HGCM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389620; c=relaxed/simple; bh=Mv8LLa9xkGpJCZgQ/e/AkUJaF+eIqI+xO6XvxwA9PnE=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=FSd0+Z14SILbU9TIkrs2bYcOvAGh6gKDFSI3d+I+0M9Ba/ZYMbfGiQZfHmGSxVOPPD/zuD7PXqftjAU2keusNr3qN9cBteUSs32zfv/FDg+qgdpJ3ovNOhETMdYC7wY7is9AyRTe8UwLzQmVc28h2gEm7mQ1v6M05wrPuA6cj5M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=bSXZtMwb; arc=none smtp.client-ip=209.85.221.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="bSXZtMwb" Received: by mail-wr1-f45.google.com with SMTP id ffacd0b85a97d-36fe10ec0d1so232317f8f.0 for ; Sun, 11 Aug 2024 08:20:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1723389616; x=1723994416; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=S3yfZwv+8ZcVgNDDaInR/7/FpU9PE0mw/yk3fhW6wYs=; b=bSXZtMwb+KtCkEkPuWwguPhBATsreUVv2zSoz4EFp2OagNCETiG2s+5K/E4UiUQq7E BVXMpnMfGFx/bScdsjOBQdTlktwpnZDhcfk/2NyseHgx8JmV9BVFH/nx6s4NpVdfeTg7 Xct8j32/D0OJ2bgZ7w4/KYRUr7x20lky3n52dFv+LOs8kOUlaeZ3PVGdXfw1y+3h2NGq pH7OUeRDcGp8LG4TA+6GttyIcQO3VWhsm02B+BjTZW89Mwno/1Cra8gy7y6oq9ICGZz8 5beU7R2HT+946DyC35WQ2KVDLFrNiCPjI09wa92DM/4dRHolk07hmZUSnXFgPardCgmj GEGA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723389616; x=1723994416; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=S3yfZwv+8ZcVgNDDaInR/7/FpU9PE0mw/yk3fhW6wYs=; b=ELhkg1+OB0lThULVJMl//vqA8RBPV3VP0goBcjaZI1Do+vEm+BI8iJ6o7i2zDC/rKi EGARhPSNiwOPcFoYFGIQ2Ss0WPcwhRyqT57X+tIlB6pdWjTwK9zkMbhtluyomQnua6sf RC/iDeGbWlRuR0SrhFq0w/LvXAhKgZKKbtcvTLmcEmSsGFgpq6pBCiRkPH+bdy5womXD hg0JJ7wPhxaLMd+hi0RKjPt7cEEl2mR8TXt2PgGZF0nUE45toxVlP10EyMCFMOjmMJ4B EV5ZhQP64V/lRJmTqumHFGyWIjeMQrPc3oZ+xb/lrqLlwmRR/fnVdHInMRlqwPS2DvR8 mc+Q== X-Gm-Message-State: AOJu0YxJxUfnIZrjZZbVwa3V+/A9UIFFzI3bNYJxatGpxiWDi21qLrFI wtEECTvzWX30Rm0RRzHuJVjbJjMtZc0kKknrir2q95zlhRBrsMBW7gKzwg== X-Google-Smtp-Source: AGHT+IEl6Mrs9CKZKk9xIsCx2UaCEAyTtLFH9u3aMn4M0qmOmVoPjZZKOum3rbXqJ9wl1bwzfaJiow== X-Received: by 2002:adf:f60d:0:b0:368:7adc:fbf9 with SMTP id ffacd0b85a97d-36d5e1c737emr5433165f8f.21.1723389615882; Sun, 11 Aug 2024 08:20:15 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c936ed8sm5133374f8f.26.2024.08.11.08.20.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 11 Aug 2024 08:20:15 -0700 (PDT) Message-Id: <92f3121cf4e719d1bd6f85e3af454a3ea7547930.1723389612.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 11 Aug 2024 15:20:11 +0000 Subject: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Signed-off-by: Jean-Noël Avila --- Documentation/CodingGuidelines | 54 ++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 1d92b2da03e..1c2d2ecbea9 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -746,70 +746,72 @@ Markup: __ When literal and placeholders are mixed, each markup is applied for - each sub-entity. If they are stuck, a special markup, called - unconstrained formatting is required. - Unconstrained formating for placeholders is ____ - Unconstrained formatting for literal formatting is ++like this++ - `--jobs` __ - ++--sort=++____ - ____++/.git++ - ++remote.++____++.mirror++ - - caveat: ++ unconstrained format is not verbatim and may expand - content. Use Asciidoc escapes inside them. + each sub-entity. If the formatting is becoming too hairy, you can use the + s:["foo"] formatting macro and let it format the groups for you. + `--jobs` __ or s:["--jobs "] + s:["--sort= + s:["/.git"] + s:["remote..mirror"] + s:["ssh://[@][:]/"] + +Note that the double-quotes are required by the macro. Synopsis Syntax - Syntax grammar is formatted neither as literal nor as placeholder. + The synopsis (a paragraph with [synopsis] attribute) is automatically + formatted by the toolchain and does not need typesetting. A few commented examples follow to provide reference when writing or modifying command usage strings and synopsis sections in the manual pages: Possibility of multiple occurrences is indicated by three dots: - __... + ... (One or more of .) Optional parts are enclosed in square brackets: - [__...] + [...] (Zero or more of .) - ++--exec-path++[++=++____] + An optional parameter needs to be typeset with unconstrained pairs + [] + + --exec-path[=] (Option with an optional argument. Note that the "=" is inside the brackets.) - [__...] + [...] (Zero or more of . Note that the dots are inside, not outside the brackets.) Multiple alternatives are indicated with vertical bars: - [`-q` | `--quiet`] - [`--utf8` | `--no-utf8`] + [-q | --quiet] + [--utf8 | --no-utf8] Use spacing around "|" token(s), but not immediately after opening or before closing a [] or () pair: - Do: [`-q` | `--quiet`] - Don't: [`-q`|`--quiet`] + Do: [-q | --quiet] + Don't: [-q|--quiet] Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: - Do: ++--track++[++=++(`direct`|`inherit`)]` - Don't: ++--track++[++=++(`direct` | `inherit`)] + Do: --track[=(direct|inherit)] + Don't: --track[=(direct | inherit)] Parentheses are used for grouping: - [(__ | __)...] + [(|)...] (Any number of either or . Parens are needed to make it clear that "..." pertains to both and .) - [(`-p` __)...] + [(-p )...] (Any number of option -p, each with one argument.) - `git remote set-head` __ (`-a` | `-d` | __) + git remote set-head (-a|-d|) (One and only one of "-a", "-d" or "" _must_ (no square brackets) be provided.) And a somewhat more contrived example: - `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]` + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] Here "=" is outside the brackets, because "--diff-filter=" is a valid usage. "*" has its own pair of brackets, because it can (optionally) be specified only when one or more of the letters is From patchwork Sun Aug 11 15:20:12 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13759769 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 64D5714A4ED for ; Sun, 11 Aug 2024 15:20:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389621; cv=none; b=cRfLn6EgnSAPyq7najhfv8MzDX7IDlErXiHMTQAbNcbGxTP8PA0KA4t7pINNi+FJTrm9r2FgqWrYODrWOQsVrIGInImKju56Q/uXAbsseJi6/VYP9kJcOde+xfzmbdm9aFJE8nEbDxgt9Fsj+fn6G31vC4z+4T/2HgVf73HhoFo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389621; c=relaxed/simple; bh=hSMXBBH0TBk/lNUe2k41G/KGXz8Qh0+A4PwqQE20FFI=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=NWf0N2mABFFVcqAjqRK8p/WNmHLWVs4jNVPkiSIvlkEEaLfgvBTE6J4P/Z1jq1l8XzStbf/3lq9IDeRQzNwO+mfmhMmHLdNmIwrYAvEH+6X98GXGqim4mkzkPLZDvoYflBXMwUQoSCL7BNL6BPx52gdnGYkiHSs5f8t95OCq4hk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=SS3tQrRl; arc=none smtp.client-ip=209.85.128.51 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="SS3tQrRl" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-428fb103724so25657585e9.1 for ; Sun, 11 Aug 2024 08:20:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1723389617; x=1723994417; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=zH8dZcHL43vGEGECx6mvn9kc0gCRdmf0wxxm7RDUq30=; b=SS3tQrRlXDClHrz+kJY448rf4YdXPCEtuggx+H/YturOYXqTxcDSjuBUd/gm/5hn7+ kEe7b26vC06xiaIdH9WF97Af++aiYzuMFErOCKq2tyeqluQ3H3Xy+c+keq4PsNhzlFaH 0y500BSyqtPQJXRGVXynxtPd/cH4b95Q9vnfLzqUAumqvCpCz+C792SpyByJLJVoNMgZ y4CtOIGWmLzHoh3o3LEJ1esCt+0WQyGpzMJkggU418i36ehiF+tioER5qlYy8W0Odpjp Glu40epsEy0wHjkcS1cCoLVyYThx3j21yYCVdAn+jGW/oPh58bCUa3gJdcmGSJKKio3S J7bQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723389617; x=1723994417; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=zH8dZcHL43vGEGECx6mvn9kc0gCRdmf0wxxm7RDUq30=; b=MWsQgP/PFx2Bn5wVEdVJSA4QAAVNPvGDf2At4cejjv9WRlQ3UXAtFDRcR9d5dmSMnx zVVyZQ3TGPek0NBvom+GDs4Hwiz7qGQSmsHO+jhtTdjv/qJBmwjhqpw3cj8YDAp2sdSR P26HoGED0kV6Ft1ndSuJq3Dvr9l8vNVHRiDY62VvPBS9RYUqjMJP6TWgGDQMzmtq/VZR 1KxKHpwUmCkCxjw+I54uiOPB3DiXckFJXHcqWifLMIadFQlob0dSULAbQXWt1pRzymTw Z1Zk/liEy8o8k1mzfrMfARckf2GyoPS8xm/wbQrzB04Wv4EV4MewY3Bstllij+m7+6bH XAFg== X-Gm-Message-State: AOJu0YzOUoPho2lJ0KpPBTM6ZJzeN76YPZYINOuVofxXxHISIpDu3TSx uw7o65zNBRCZBNA3R1kh5nF9bvB+iGfPBKCmNyKil1xXR7dIdPKRagsUTg== X-Google-Smtp-Source: AGHT+IG3AFwDSTyr/tyxj6RV3NUOvNESnifSKMaR2ilsKALt8fZP0r7QUomPrh6CW4eDcV4wbxWIPA== X-Received: by 2002:a05:600c:314c:b0:426:5fa7:b495 with SMTP id 5b1f17b1804b1-429c3b11b53mr53169685e9.15.1723389616777; Sun, 11 Aug 2024 08:20:16 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4290c738947sm151730505e9.10.2024.08.11.08.20.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 11 Aug 2024 08:20:16 -0700 (PDT) Message-Id: <02406b9189455cd376c1a9dd065760759b7a02e1.1723389612.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 11 Aug 2024 15:20:12 +0000 Subject: [PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= With the new synopsis formatting backend, no special asciidoc markup is needed. Signed-off-by: Jean-Noël Avila --- Documentation/git-clone.txt | 76 ++++++++++++++++++------------------- Documentation/git-init.txt | 33 +++++++--------- Documentation/urls.txt | 26 ++++++------- 3 files changed, 65 insertions(+), 70 deletions(-) diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 8e925db7e9c..f0d508ebf51 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- -[verse] -`git clone` [++--template=++____] - [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] - [`-o` __] [`-b` __] [`-u` __] [`--reference` __] - [`--dissociate`] [`--separate-git-dir` __] - [`--depth` __] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`] - [++--recurse-submodules++[++=++____]] [++--++[++no-++]{empty}++shallow-submodules++] - [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`] - [++--filter=++____] [`--also-filter-submodules`]] [`--`] __ - [__] +[synopsis] +git clone [--template=] + [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] + [-o ] [-b ] [-u ] [--reference ] + [--dissociate] [--separate-git-dir ] + [--depth ] [--[no-]single-branch] [--no-tags] + [--recurse-submodules[=]] [--[no-]shallow-submodules] + [--[no-]remote-submodules] [--jobs ] [--sparse] [--[no-]reject-shallow] + [--filter=] [--also-filter-submodules]] [--] + [] DESCRIPTION ----------- @@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic links. + *NOTE*: this operation can race with concurrent modification to the -source repository, similar to running `cp -r src dst` while modifying -`src`. +source repository, similar to running s:["cp -r "] while modifying +__. `--no-hardlinks`:: Force the cloning process from a repository on a local @@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. -`--reference`[`-if-able`] __:: +s:["--reference[-if-able] "]:: If the reference __ is on the local machine, automatically setup `.git/objects/info/alternates` to obtain objects from the reference __. Using @@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository. is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. -++--server-option=++__