From patchwork Tue Sep 24 07:08:48 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: 13810229 Received: from mail-ej1-f44.google.com (mail-ej1-f44.google.com [209.85.218.44]) (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 2D01B12C52E for ; Tue, 24 Sep 2024 07:08:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.218.44 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161737; cv=none; b=SMJbbkaqk+1M4sF+e3WBNe5LpNDaLokRTrQw8nnKuXEKOPY7OuEi9PkPraETu3Z0Ic7dodgI77fvdaJqRZytC17lBOf3HKzB3fN/9dn9656uEGjJMhG/X3h3Gwc+L9oaJHwkA+vId2N6bqSuPY0SMxH4m730Gf+0WMSDMR2rfWY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161737; c=relaxed/simple; bh=OBMTxRyxg64A3jWaQfuePtY7M/3WxM7kgz2mzJTKMYI=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=kMX7567E8iHhL3e6K/cuezZS41hIxKpXBFGWZXTSxel9xxv688stp/nyXN8DB3e0BrJlUNjhs2lg6yQNyhNc7jm10Pfdq8NPkhItWPizFjnEg0jH7lt/okIMJp10EyZF3InOJT6+vtqg8q1UU4CU9EO+sfwWwZC1Y5rm5Vsch7o= 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=ZlTlrxJp; arc=none smtp.client-ip=209.85.218.44 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="ZlTlrxJp" Received: by mail-ej1-f44.google.com with SMTP id a640c23a62f3a-a90188ae58eso650854966b.1 for ; Tue, 24 Sep 2024 00:08:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1727161733; x=1727766533; 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=YaYvYbxgPrgJfyOYE8fgTUzwMfpBTi0rPkAGEufOXBw=; b=ZlTlrxJpV694WCLZBQyRRsWBEKEUZpQryAWcTMKGSmlcte9L9LHgIu4ZBTUDNCEgYA qfIQDsb5yc7VNiLdqkkbwaxnk8Jv7CSBr085e/fsUJRB12LbcAotvULBg7wTVAai0arN pWhYGJ71h8Cst0eHErmfl73K5AzSialhkq7J7rA1EgQMx1iRaHoM7g57iTTT3W3RnGEs zgYex0sumI6APk0W1hD9I85mioWFDH+rFnWuShURrNOLOaaUPBlkQ59Z00bV2ysQZEl1 C3b2xfvxlHqxXDXVZl4TDkGvMQEtwvngYXNrQMcKBjuTA6lCS/dOzOV1SGzVWbfNWeYJ 945w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1727161733; x=1727766533; 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=YaYvYbxgPrgJfyOYE8fgTUzwMfpBTi0rPkAGEufOXBw=; b=QkpMjeCp4+ipUqr7gnNN9ivCrrO5RYDmHK6xfyqhqGYTJlzsG0n94bVTemx3/dFPPB CwqzFavdpVGU4rsEkQwqaz1bTnnya6HJNFv9j6fbZDDSXstHi2FUvwM+zgj3vnciCyxp wsoIaIznTETQYvw+NOg51h3ESKDq6i4DRYkK2FiCDejtyoDIai8m569SFWHtFc+WfiGQ /u1cu5JUsfgdB3tjp9NpqXSVhZVIgrSDzIMtOYA4GHGC2VFnMMJ2evqSeUwtNSLrmQi6 tDSH0ml9wAB4H2IqTRV5scvW3tWhjdj5hk9rV7uSvRc2+td+27z8klnJ4MP2zXAx+/GE X1OQ== X-Gm-Message-State: AOJu0Yw2Eu9mCS/hQ8I5ZD2qdTGRWcyou7dJijqHFNXD6+Fohu6Cxefs w9h22qOSbDWyGbOZUUig/ejFRJN6GPknSL3Lbtq36WWKSHVVXGTDHbOfoQ== X-Google-Smtp-Source: AGHT+IGPWbsirVnbXVNFXosGNyFvk+Vlfewx2Bpjs2vywtIsikMI/yqxSToKtoMCGljllxpCU9Aojg== X-Received: by 2002:a17:906:fe4a:b0:a8d:286f:7b5c with SMTP id a640c23a62f3a-a90d572c19fmr1432420666b.27.1727161732848; Tue, 24 Sep 2024 00:08:52 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a93930f786dsm47973666b.170.2024.09.24.00.08.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Sep 2024 00:08:52 -0700 (PDT) Message-Id: <2946cc80314aa2b3f653c83e34ccb7aeb1db44d8.1727161730.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Tue, 24 Sep 2024 07:08:48 +0000 Subject: [PATCH v5 1/3] doc: introduce a synopsis typesetting 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: Eric Sunshine , Josh Steadmon , Chris Torek , =?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 processor for backticked text are modified. The backends of asciidoc and asciidoctor take in charge to correctly add the required typesetting. Signed-off-by: Jean-Noël Avila --- Documentation/asciidoc.conf | 20 ++++++ Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++ ci/install-dependencies.sh | 1 + t/t0450-txt-doc-vs-help.sh | 11 ++-- 4 files changed, 112 insertions(+), 7 deletions(-) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 60f76f43eda..f6da6d1fbd2 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -28,6 +28,10 @@ ifdef::backend-docbook[] {0#} {0#{target}{0}} {0#} + +[literal-inlinemacro] +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} + endif::backend-docbook[] ifdef::backend-docbook[] @@ -56,4 +60,20 @@ ifdef::backend-xhtml11[] git-relative-html-prefix= [linkgit-inlinemacro] {target}{0?({0})} + +[literal-inlinemacro] +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} + +endif::backend-xhtml11[] + +ifdef::backend-docbook[] +ifdef::doctype-manpage[] +[paradef-default] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;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 's!…\\(\\]\\|$\\)!\\0!g;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..cb24480b63d 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -1,5 +1,7 @@ require 'asciidoctor' require 'asciidoctor/extensions' +require 'asciidoctor/converter/docbook5' +require 'asciidoctor/converter/html5' module Git module Documentation @@ -39,10 +41,95 @@ 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(/(\.\.\.?)([^\]$.])/, '`\1`\2') + .gsub(%r{([\[\] |()>]|^)([-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 + + class GitDBConverter < Asciidoctor::Converter::DocBook5Converter + + extend Asciidoctor::Converter::Config + register_for 'docbook5' + + def convert_inline_quoted node + if (type = node.type) == :asciimath + # NOTE fop requires jeuclid to process mathml markup + asciimath_available? ? %(#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}) : %() + elsif type == :latexmath + # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math + %() + elsif type == :monospaced + node.text.gsub(/(\.\.\.?)([^\]$.])/, '\1\2') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1\2') + .gsub(/(<[-a-zA-Z0-9.]+>)/, '\1') + else + open, close, supports_phrase = QUOTE_TAGS[type] + text = node.text + if node.role + if supports_phrase + quoted_text = %(#{open}#{text}#{close}) + else + quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close}) + end + else + quoted_text = %(#{open}#{text}#{close}) + end + node.id ? %(#{quoted_text}) : quoted_text + end + end + end + + # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis + class GitHTMLConverter < Asciidoctor::Converter::Html5Converter + + extend Asciidoctor::Converter::Config + register_for 'html5' + + def convert_inline_quoted node + if node.type == :monospaced + node.text.gsub(/(\.\.\.?)([^\]$.])/, '\1\2') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1\2') + .gsub(/(<[-a-zA-Z0-9.]+>)/, '\1') + + else + open, close, tag = QUOTE_TAGS[node.type] + if node.id + class_attr = node.role ? %( class="#{node.role}") : '' + if tag + %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close}) + else + %(#{open}#{node.text}#{close}) + end + elsif node.role + if tag + %(#{open.chop} class="#{node.role}">#{node.text}#{close}) + else + %(#{open}#{node.text}#{close}) + end + else + %(#{open}#{node.text}#{close}) + end + end + end + end end end Asciidoctor::Extensions.register do inline_macro Git::Documentation::LinkGitProcessor, :linkgit + block Git::Documentation::SynopsisBlock postprocessor Git::Documentation::DocumentPostProcessor end diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh index 4781cd20bb0..3e3ae39cbb1 100755 --- a/ci/install-dependencies.sh +++ b/ci/install-dependencies.sh @@ -107,6 +107,7 @@ Documentation) test -n "$ALREADY_HAVE_ASCIIDOCTOR" || sudo gem install --version 1.5.8 asciidoctor + sudo gem install concurrent-ruby ;; esac 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 Tue Sep 24 07:08:49 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: 13810230 Received: from mail-ej1-f51.google.com (mail-ej1-f51.google.com [209.85.218.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 CE4AD12C544 for ; Tue, 24 Sep 2024 07:08:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.218.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161738; cv=none; b=sNdUPBrLQ/Xz7+tGi9OWDwTCjV58/7vtQzsVWjCD73Vu4VVpW/Dk5Hltq6SZ31fzRnzsebVJrKJnzIg6dF+GrCM85NxIh6pswGhMM6LAxM6dwSO8nFkiWzXpo1aqUVUbJlRLfgq8D0dTpxp9JoCihDcKBKKYhZFhi7qr0JR6qoU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161738; c=relaxed/simple; bh=Sw5Zoox1wS11AVda86kU7lPpxL1cDrsRx5Lzxf0anNQ=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=R2lNpwrbDWfY0CJAX1agemNrGCKf+CyGQUBVgmPd2GDdRGpTotwpprUBhAIb7m0d/7e1u2LW+uFSbEWds4zNbn+dFDHkouP3zoL1QWw3X1hXA42V24c2OVb+FzBGoJ9CvrYgNj1lLodNZi9DUdXVSYy6P0L0AkzQbvOqCQ4VSUk= 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=EVPVsWoK; arc=none smtp.client-ip=209.85.218.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="EVPVsWoK" Received: by mail-ej1-f51.google.com with SMTP id a640c23a62f3a-a8a789c4fc5so161014366b.0 for ; Tue, 24 Sep 2024 00:08:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1727161735; x=1727766535; 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=BD/05PhIVrHN/74im8C/+sMenNig6tZVrRnSWf10004=; b=EVPVsWoKTz3WAzY51aU3D50wJHXjTv7/cbMZ547Lkph1UzyS6peWf+CB9+goGrqIaf XwesJ12Q2r371dacMnmXkbvO6PxYUjk17h1R1sgWu60SC3RqXDK89UlCTeviBU+sNtqP XS02cSe5uEGQIAvMchtJvxq2Baj7bQDxc/p7bqUd9YSno/BCgeX7L8XqiGYc2864U9Qx jA53JDr9EVKMNeGlYDqxbIjvZQTDnDZa2LfNKXstOcrd5xVndWy7CLWTqOwVs6wiAZe/ Zk7Wm5q7NKOD2Zq9gSEIiq7vHheb7n1ZaO9f48JE+/SfbQrNclxjU05Z0FQ5t40J+xvF p6Vw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1727161735; x=1727766535; 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=BD/05PhIVrHN/74im8C/+sMenNig6tZVrRnSWf10004=; b=hpmilV/s9YCQFfl8vUBBK/tJjuqtWh4j5jJtHVqzO7wyOjLXdI3A6GeEqNY5CHCqz1 iJVDvuBIMfUL59xOrb1LqlCEZv3UTgrSO2U+9yUebGxSzSpxjWpmdtFKtV2ahtxQzSeC Ir1I2wwl10JCoMMmtLRjFFnjNdsFk4x1JxBqBfgIDu0ti5ZcxZ0xvrKAB8PFu62Y9Fuy sjKCsmWmfq/AA5uun36YQxGy3Kv2QvIwSfcdn6Mb12hpP6n/Ei+sJCZCfypS/l7pFZe/ N2bkMZ4VSh5HApsrVizxKHYy+MU8aUtL6gL206E3S9sb7mxF23OqznsNT2ToxmrwJUz8 eH9Q== X-Gm-Message-State: AOJu0YxrWwTEQGCf/l5l7c1jIK2TVqRjc11lSMvZvDWMdUz1PWh14WDY YnqK8tgFp8ZGFZtuq+Z2v707NS0r7M0kx2m5yG0eqgJ8kQiMfIH7nT0dSA== X-Google-Smtp-Source: AGHT+IGrX2oP1eUN2AZVU/l7EcqagIWOrZnFUM1tKseOThrWAYJOCg7qUFJgf+JoGLrPid/Ll7pPMw== X-Received: by 2002:a17:907:7da6:b0:a91:1592:f5c5 with SMTP id a640c23a62f3a-a92c4810e00mr235762066b.10.1727161734436; Tue, 24 Sep 2024 00:08:54 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a93930caf50sm47906166b.106.2024.09.24.00.08.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Sep 2024 00:08:53 -0700 (PDT) Message-Id: <06b8fff6a57642aa0f6853528c00b8c30896842d.1727161730.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Tue, 24 Sep 2024 07:08:49 +0000 Subject: [PATCH v5 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: Eric Sunshine , Josh Steadmon , Chris Torek , =?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 | 58 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index ccaea39752c..13cbcf1d7a5 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -820,78 +820,80 @@ Markup: __ __ - A placeholder is not enclosed in backticks, as it is not a literal. - When needed, use a distinctive identifier for placeholders, usually made of a qualification and a type: __ __ - 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++ + Git's Asciidoc processor has been tailored to treat backticked text + as complex synopsis. When literal and placeholders are mixed, you can + use the backtick notation which will take care of correctly typesetting + the content. + `--jobs ` + `--sort=` + `/.git` + `remote..mirror` + `ssh://[@][:]/` - caveat: ++ unconstrained format is not verbatim and may expand - content. Use Asciidoc escapes inside them. +As a side effect, backquoted placeholders are correctly typeset, but +this style is not recommended. 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 Tue Sep 24 07:08:50 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: 13810231 Received: from mail-lf1-f51.google.com (mail-lf1-f51.google.com [209.85.167.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 0FBA712DD95 for ; Tue, 24 Sep 2024 07:08:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.167.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161740; cv=none; b=ms3jh4jKUEboC0hp08a7qq8UKdpKtsiTDdS1WqvNJj4qUfVSvwEzZtty+ZxqJaxG3T9SKUdSMFPL54h7XM3oAA751HHvv6BVGTH9bWDULuysVdpM5Mnh9q0ZVSRo0POFi62bXIF4vW1dYkM8gIAl500BpOR0v/3swqvcVz7sR/M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727161740; c=relaxed/simple; bh=Eaqgis0uSVGgXcr2Jmt79yrqrhPXTWxp+V+pT+l53MY=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=qviLO9d91R/gZvx0WI4rCihGT0oQXbLHMfsGhS90veEIBGnH4BUjeN+UN80kgC7wXp9iXG6/QCHFIrx+ULcfE7hPBZ0gWrrzvESEb9UCUg+nLcpOYCgHdt4oPtInihasVZ03h+zVad3heUcKYTgYucfCw85cLAuXDSXsisQdQ9Q= 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=EbEEACg5; arc=none smtp.client-ip=209.85.167.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="EbEEACg5" Received: by mail-lf1-f51.google.com with SMTP id 2adb3069b0e04-5365aa568ceso6015433e87.0 for ; Tue, 24 Sep 2024 00:08:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1727161736; x=1727766536; 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=/qrMXREWBZ2YGOF2rrmabikA8Un0b7umLT0leYeINvA=; b=EbEEACg5PZZRtB+GIzoSX3UcIjo6VTv+gQI44Y5j45DNePSOBMcaOYphqZrKmtEohG Da+k/fSq64T4evfb5kUJF/p04BaHKI1KNETN/lfKZB8AzvzFi06NwpfGRYUYepxmHWxU QXXgHlckDL9e1XOjwxIFxPMcvbmG/Y9DZ51giZFRthxAY4TW+EkoV2ZiI/t7ICi1YQRl d4+7TqFUyngJv/ktp6bCY3BgGOPIVmfsaQXAYHSCvtflkdg0wdMkCy3lxtmZRG3dCfXR D2umxCrTj2NrogTLv2bVtE89PZ1Ed+AJD1vn/VHQOnAwIhGVFNkWUSbPRG+3LTlEkqQW AxPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1727161736; x=1727766536; 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=/qrMXREWBZ2YGOF2rrmabikA8Un0b7umLT0leYeINvA=; b=XMEQDzLRolErv4R8B1klzduoTUxKwerTFbilMcBuUhqOXSrX/TmznFcUp31KwIbmhF jsp5taSrlPQRWFZ4/Vt+Kqrve2BR+so9S5oIsg5y8eutKpg/sDINZ1F0V5mlmywT2Uuh Y6I3pyNjJPRMNuuYlIrOae9Lpfl9D2Q4ycNNg5D++rVO8EC0ykqsAfNy5l9rMrrhyd4Q OIMvynsK1zECcVAIy9CyJEhMxno3Wa+m0oCa4hWc4AvoGlOcvA+8px95DUaj91puaWDV W5vJoGB8ZomZhHLn38yFS2P/tUE6AZv37JS8fQnM3KacnBP4DWFQi1HEMdORckPH1rEm bqmA== X-Gm-Message-State: AOJu0YwZK1VN00DVTYgaYdjXLnruuglw8nuP9PeFkmAyNzHzLXhDY+NQ Z6neXYliN/EusUIpa+HmV/+fr9HptCVUlUKuVU8fj/WHsCvV+QNJ26xBvA== X-Google-Smtp-Source: AGHT+IE6eH49HiziPIy2bqHqIm3A6e5NDPLE1dEpbuA6Q/TukwLtNsTU2qnUrQM1H1pM8lTC57gLOw== X-Received: by 2002:a05:6512:6d1:b0:52c:d628:c77c with SMTP id 2adb3069b0e04-536ac32f044mr9626223e87.43.1727161735249; Tue, 24 Sep 2024 00:08:55 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a9392f4f8b1sm48187166b.53.2024.09.24.00.08.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Sep 2024 00:08:54 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Tue, 24 Sep 2024 07:08:50 +0000 Subject: [PATCH v5 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: Eric Sunshine , Josh Steadmon , Chris Torek , =?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 | 78 ++++++++++++++++++------------------- Documentation/git-init.txt | 35 +++++++---------- Documentation/urls.txt | 26 ++++++------- 3 files changed, 67 insertions(+), 72 deletions(-) diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 8e925db7e9c..9c13f847da3 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 ----------- @@ -52,7 +52,7 @@ OPTIONS to save space when possible. + If the repository is specified as a local path (e.g., `/path/to/repo`), -this is the default, and --local is essentially a no-op. If the +this is the default, and `--local` is essentially a no-op. If the repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular @@ -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 `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`] __:: +`--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=++__