From patchwork Thu Sep 5 21:52:04 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: 13793008 Received: from mail-ed1-f41.google.com (mail-ed1-f41.google.com [209.85.208.41]) (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 D05AC1A724A for ; Thu, 5 Sep 2024 21:52:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573132; cv=none; b=tY3U11zPdvrRF3N3lpB+tD5hG+zY+ahxTSZi7xMO4WnXf1kOCintIOrkT13ueeJPPyRtrsmbyk6D5XU5PNdsfzUh7P86hha+FpZmDPeL3hIMtWVxhSvvzCj56jVXzMQwaEWHh0PKz0islPMdeQOJCqPBUGWYDyOsT7XwwX0mN+g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573132; c=relaxed/simple; bh=0DcWNNcKfw1VHxegoWaZu8UCO8t9yD4IaDst8zacdjg=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=bhLsuW2fF7E0aIMdfdzHbm5k087UeAVbVkTSQc2nkaRkxB5DOYehmP54Zx5EdDc6mqrTbxmn8kIlFHo7Z8O8P1UVhTRmQ7jP3j5gtwBTyRRbpxVupTfjUoNSKphvYsGFs4BvhW+akqgh5uDAvuXX3SdeirZB4h+CvV4bfU/3oAw= 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=kxFYxbd6; arc=none smtp.client-ip=209.85.208.41 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="kxFYxbd6" Received: by mail-ed1-f41.google.com with SMTP id 4fb4d7f45d1cf-5c25554ec1eso1477956a12.1 for ; Thu, 05 Sep 2024 14:52:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1725573129; x=1726177929; 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=4cn27tu37xl+IkvUoHDmY/cNfH672Dp7mLXqJ5mSDT4=; b=kxFYxbd6QBsPyBVIrzOSyizIgO5txES1ukU8Y50+B8e6QKg52eGm7SPEvGISuD4mwN PXLvounCRW6B/bt0kji5sG/g+5NLG84LaGJhd/h2x9nOHyhe1K7y4+w/FoG5uPTYFOjG tvqofEdNuuCRR6zywNqpQTGzD0w6moUlKhO0R4czd5PCl165PYZDH0ebGItGEc3Di3NZ as8flnWPp4YrIwDjhfIu6Zd3D7KxKSq9yg7mT6ZJWfwn6gvlhaioTtMtBvll4q168NDD d4jFU1o/BY0IaYLUTiYR2WE8dwTWnNvUyrKmR0k6n0Tt8re9JhbKkdQ+Jx2R8UOaUYOC mhUw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725573129; x=1726177929; 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=4cn27tu37xl+IkvUoHDmY/cNfH672Dp7mLXqJ5mSDT4=; b=sBJ9CSqDzOLY0y9WrAFlEqX9IyippM1OTc1AqMug+ls7EvlIeNCnRhuyR3qbX4GNva m6Qw9U5G611saTnrPt9n9ZvHyBQQI3cPHbIOT89bXk/u1MhUPPsHtO0q3HrKEvgThZg3 y6s9XgfW1kHpM0CRlMMINk18qhOa9XhGpp+t0n2izx8JBgCEmf8QskkB1Rd9DtJ4yHYc DS6sac35thOMW7IE6VpCxKEw914Gmq47V18a7yP6m2rivLOu1/zXol1LwEuxVjO3M3fh 23Io8WAkXgO3cfDI9VTnD07c02PIo/7fCrdhA83hKRuaOTtdeQu6tyF3ZprmJQQLmh7h jx1g== X-Gm-Message-State: AOJu0YyNYLJY40xfKmYn0pPhIvWMxIE2K6AxdnyLo+6kZAxhntqDswv6 SZwIsyA0Xyisp5nm0ANgpTw/4oiKfyCbZlpZedZnsyafkwt/NmwaAeUSYg== X-Google-Smtp-Source: AGHT+IE74OKUeW3id246OYFqkWurfRrUAfJ5gNoKmkYcB3p692CeNcTpJUzMUPlIjKp4oOFvro3MSA== X-Received: by 2002:a17:907:6e88:b0:a8a:8cdb:838c with SMTP id a640c23a62f3a-a8a8cdbc1cdmr1677666b.53.1725573128575; Thu, 05 Sep 2024 14:52:08 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a8a62038dc1sm186117266b.56.2024.09.05.14.52.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 05 Sep 2024 14:52:08 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Thu, 05 Sep 2024 21:52:04 +0000 Subject: [PATCH v4 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 , =?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..75ae9f3da92 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 -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..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 Thu Sep 5 21:52:05 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: 13793010 Received: from mail-lj1-f176.google.com (mail-lj1-f176.google.com [209.85.208.176]) (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 7DA931B12CD for ; Thu, 5 Sep 2024 21:52:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.176 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573134; cv=none; b=hnxEvuDNado7sNc7z3LOzhm0DxtRUQdO9r/IwlvwCnrE6R+zI+ZP5eZj6J/p15ptpUnLrhAR4Ly+KPaG4zPCSsr9Gq+NP+Mmj2xSPlNBkbtXd2oH4xq4Wb9ffo/98SAGnuh289Fgk246ctKspLkrQXF6dtUJVTHwIykqpdJ0NT0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573134; c=relaxed/simple; bh=Sw5Zoox1wS11AVda86kU7lPpxL1cDrsRx5Lzxf0anNQ=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=FBFG8/YdxXD7R+RHwipgHZY7MexW6fwogabVtr3qR0LphVQ2UgC82Au+8OP9R3L5aOsjTfSnjfThqvxstlrHLTXwM2gHmg3hYBb5j3akW3qcEc4cMDYdhG3LF1TyrIPEY1vuqPDDRaae8wXfXcWNzqdqZ9XG6BfCQ+t3TIutiMM= 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=c+CnZ/vm; arc=none smtp.client-ip=209.85.208.176 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="c+CnZ/vm" Received: by mail-lj1-f176.google.com with SMTP id 38308e7fff4ca-2f3f0bdbcd9so14985281fa.1 for ; Thu, 05 Sep 2024 14:52:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1725573130; x=1726177930; 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=c+CnZ/vmwaINE6En1lhCB6z/tXT/2flni19JjOq6Qm1KAxj7jCZ2C8NAQhoHMElzer yyD1Lv+2pIovKLjjWzzh9E8Yi//oFTCqP+J7nO4m/cIV7JLDUefRfl2ZtOGZH68iQq6w X7zlNVr6Q8lCydMfUWQtrnbERRi85cz1XUuPHYbJNSWqlhh9/PIbvwm1l8kUfBlCBQjJ L1z28yrZHBDz9Oou6YeAyHQxhoYsP/28aGuRoidDQeA9B2PjyfpALFdJVXB7U6it6wd6 hHlkdSbw0rPn6IlGyutJc1iTqoiQcZ8qTlZoDGv+ES5akM6GPEsb8W/tJjr6LHNSjBYP faYA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725573130; x=1726177930; 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=hhhubuzQZGEh6sdzcA17vsviCrWKrl5C8rD0+hJjcgzL6iRV8GHKzy1ZecFBONMoOZ 7oyx3EU1MR9DklaAenknkqVS3WF4lcpxw6MrICEwAjSTIGREeIvB+A2rezNJYNU8SKfv qffdp3nmLjKuxbTWjI5YTQX9QBxUliAeAfkmnH5mT9ANGrvcviuAcWtpmFQhNYxa7K/Z N1aE2dtT58flqdSdFEOYg9irWxBhniX3uuNythWYb9wYHHgJdEi8JE383BQYbLZcPAQM 8FtW8VNFvG3KL75NDQQ1rVHWHAc3SnJqpsOWxne7Ys4DlfJfqE8vVl/iuTrZQFVulT4W Zd8g== X-Gm-Message-State: AOJu0YwbmylggcRFj4LQcUrsV8aj6gmSGafKFyjRcjNOpjwSaWkzLDld GgWFAXl595mHZl5atxDO0fpkbPqUuoJMHAJQ96Wp9EeWmLUsuOav+3be6w== X-Google-Smtp-Source: AGHT+IHlJelj7RAbF/xal/6ohy9G9c4xMiYYwxSIoBRGMTm4Ch/Vim3HNDlkOQeObJqbpVJvk8HPZg== X-Received: by 2002:a2e:4609:0:b0:2f7:51a2:96f2 with SMTP id 38308e7fff4ca-2f751eb2584mr2125651fa.8.1725573129373; Thu, 05 Sep 2024 14:52:09 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5c3cc528ecasm1692611a12.1.2024.09.05.14.52.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 05 Sep 2024 14:52:08 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Thu, 05 Sep 2024 21:52:05 +0000 Subject: [PATCH v4 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 , =?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 Thu Sep 5 21:52:06 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: 13793011 Received: from mail-lj1-f174.google.com (mail-lj1-f174.google.com [209.85.208.174]) (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 658121B1505 for ; Thu, 5 Sep 2024 21:52:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.174 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573135; cv=none; b=Iq+E2E2TZ8GqsRoGYK9FCYqg7YuZpIEKiyzcTogA9Mq1HZA05mtz9AW1zXM7r/l5hzwfDkw4xAhYsLjgPzzdjTnT7Rmm8GScqMDsF3/LOBuumyfVNea/RC9E3hntZ/gmLCiMi5rWrCjaAzD3POuQeWPvH1fGGkrI6RUL7EFJYvc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1725573135; 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=BxgSDhh2tQfiPUGVN5pE/ka/R71ErO6YCXFzX+SZinrhUWwa7fVKVfdLqUTHODmGjtO6bT+SRFc2G4vqpfUA0P6049iIE9cunJ83OWc14XAJTQO/P/pWvtX9eugniK5c3s0OPMALw1C3ZDP6o4yNcd8/Zu7XUZbkR3cugEARSus= 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=JDqABsQ4; arc=none smtp.client-ip=209.85.208.174 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="JDqABsQ4" Received: by mail-lj1-f174.google.com with SMTP id 38308e7fff4ca-2f50ca18a13so15933931fa.1 for ; Thu, 05 Sep 2024 14:52:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1725573131; x=1726177931; 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=JDqABsQ4Y5sMkSGzIIxi4lRI6ZfnK1ODpLiEzFIXSgJjplqS6jWGYFvhwIqzfbUmXD FkKEr5KTlAOP4G8xn+AIsFcSVMv4scmrNI4PCK8hFdZlwDLuUMWw1LDu8h/BBOSyImY3 9mw82cJOJz21h/8OCYgVcnYBzqmaYUTZ3ZMv7mDuu5Vcbi2hJmomRjfK0fT2ceBWbxys 8EF21Vf9kj/bpbyve0aZN3ue8h2G26t7uWGtfptLum7Ebr7+wnGJWC1mILla3YoSWVi7 rBQ/XBXIJMbpBUxnsEmG0Oq741JTSfxicZ4vs2lU7VqeM7KmMzz7WD3ahABY2rAl/YeA GRBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725573131; x=1726177931; 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=hREbHjO03y6MMO+XgALZSG5JO6ZWDXO6xT8NWKwsR0LipWdpvD7ohWtHU5nWAvWpZ8 JfO8zu56icNwnXQxjKyE2sxltUlSJACBbwA0PyzFU1AUaExtZkkM8TQc1YbYHbq81M9b jWEayuHgRiANgVsvjOmNvdriWgqR2ZS96NYzi1DjcTn90jniDmkFB70fF8lG0IAnOTW0 P93RR0keIOChRfqPTpvgmpegWmUqDoehCZsTLDAp0BNdBpNtsnHYRBrTLS2Rna4YN4P4 XHzfj9Whx1H+RKkXIM2xEE7VORVoN7t7kWwpnch4fM9C7pbCumVNtxGDYHnJ3R/U4Nq2 jXdQ== X-Gm-Message-State: AOJu0YyU4mTdM8LRTZUK7BBFRMMxp1hRaugfxFJ7MyIlnueDc2AYQjwQ tbtZCEz/wHKIXaZJtcZk2xxQwEbRoKjzPkkIyUAkYdOVTCJKdHxI0Yk5rw== X-Google-Smtp-Source: AGHT+IF5NiTF9Q8gKu090uKvFQF39InD0psbxJ5WRB5uqbxMG7yYqFdM3mZeg02sx/7rwQL+ykk5Qw== X-Received: by 2002:a05:651c:b13:b0:2f1:6cb1:44c0 with SMTP id 38308e7fff4ca-2f61038c633mr195528401fa.6.1725573130398; Thu, 05 Sep 2024 14:52:10 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5c3cc56d405sm1680401a12.50.2024.09.05.14.52.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 05 Sep 2024 14:52:09 -0700 (PDT) Message-Id: <719188da711f9e2f66dea706b3df28e4930fa060.1725573126.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Thu, 05 Sep 2024 21:52:06 +0000 Subject: [PATCH v4 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 , =?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=++__