From patchwork Wed Jul 24 21:06:16 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: John Cai via GitGitGadget X-Patchwork-Id: 13741359 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 5A9AC446DB for ; Wed, 24 Jul 2024 21:06:23 +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=1721855185; cv=none; b=mrvjF5PT+SeLsgHI1lTwMEH1CH3c633AN20HPd2TZiDFjHs1f3DGI8LyXgNxXcwidAtuEboNt7mBYRilq5emF4eYdmI0FH64qt+hKKFbjprJfg3mxCh9pfZ8qmi37UkkHEp5cqt5rKXnMhXPkVNdquGfVjhQhwVScnnowGX1qig= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721855185; c=relaxed/simple; bh=+cJ/e8NBGOT1cdANp8mb8EtV8LhpRWnzR8WFlxPyOo4=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=hqL0n7Pg7X4eF4j592zBOuMQ5WBd+shJ7AWKemZD90HxJlYu6+7ty5R/hYPiogl1UPie9o3XrlY4RlJ3Xy0iOoeMqob1sYeEhv/o25wJPzzg39j8Tqm9Hih8sBNWlwfB6JKoINnKa10eqJJL3vDV6nmKmLEDA65Ke6uR4tc36Zg= 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=l1xfG2SA; 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="l1xfG2SA" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-42803bbf842so1935365e9.1 for ; Wed, 24 Jul 2024 14:06:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1721855181; x=1722459981; 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=Uti0VoYedz1V3c6dfX/HWis1KcuKgV5wOLqhF1qZoK8=; b=l1xfG2SATqP/q+l0iaNvTzxEBww7pJHrW47btb15kfYT9nJWBFh5fHs/IAN8vUX2V5 2WYJTQw6cbTmgfpbm28fd66oKIz7B86ape1HaV7deCoNoXQIhtbpFgeGiR+Yp160uRpx Bn4DzrAXYzLmoUdOb38ghPXjFOK5vHIiLQP6yFJnQw+m890OifeI8gzC3MyxxnKx+l/x kzAuuQnE2La9g7nS5a5Urxxk9LcqaU2P68o8sVaMJrH/qtc9Og+BcnLuJqBDfnQUh01L ywgWKpZ7ItNzZZf2fXn5oqAI1DjC197d/4mfTFkp4rMyKC1evwVcFEbhYrMcmD1l02up 9Ycw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721855181; x=1722459981; 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=Uti0VoYedz1V3c6dfX/HWis1KcuKgV5wOLqhF1qZoK8=; b=qbRIlGtum16ovx2MBYOWSvniDzn+F/cR3AN5j0tBsU7++i1kuRJ1+BrnmWp8JqpDyq LCd0LuWEMJwHFSrMwF4qUOYifWsyP6MXzkfLCig/vENkXo9v8XW+N1jXNx4V3rC9ES9s j/7opqppfC+VUyCX/2FpMv1vzWY1d4MyGfZsnStA2gfP5Ue6tw/nNn1eeL0zNhsFkCdb o/qt8YKxCt53Kw4QsGy3TVnAWG9w5TrIG421n68zycqHh3+ES8lIa70wojGzUu7utc20 Bt8F57O3diK4lfv98y8Wr9YFZfmrvWy611DqYefvujYUIpES/2UagLeSLE5LeO3c2Lgi zYWg== X-Gm-Message-State: AOJu0YxB1QulBmuYpOUrATFnt7x9SVFaXzjpNdVCrTYRSid6znCfetF4 9g0XrjvAaqqNhppXX87HicnPCYjCQNgsSM+q0vp5KWCh8JrVsjEYVHTHkg== X-Google-Smtp-Source: AGHT+IEy4GCio9zTGpNzFcYrCqEh+hX05wr6d/a/pNHxXCfAcdo++3PfY5mlxnnqlXYFUAfHo9gnnA== X-Received: by 2002:a05:600c:a05:b0:426:6ed5:fcb with SMTP id 5b1f17b1804b1-42805504209mr1864555e9.4.1721855180974; Wed, 24 Jul 2024 14:06:20 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-368787eceb0sm15364614f8f.99.2024.07.24.14.06.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 24 Jul 2024 14:06:20 -0700 (PDT) Message-Id: In-Reply-To: References: From: " =?utf-8?q?Jean-No=C3=ABl?= Avila via GitGitGadget" Date: Wed, 24 Jul 2024 21:06:16 +0000 Subject: [PATCH v2 0/3] doc: introducing synopsis para 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 Following several issues with the way the formatting of synopsis is done in the manpages that were recently reworked, this patch series introduces the processing of a new custom paragraph attribute 'synopsis'. This extension is added to asciidoc and asciidoctor and lets write the synopsis of the commands without any typeset. The git-init and git-clone manpages are converted to this new system. Changes since V1: * switch to sed for asciidoc filter and refine the regex for support under macOS Jean-Noël Avila (3): doc: introduce a synopsis custom paragraph attribute doc: update the guidelines to reflect the current formatting rules doc: apply synopsis simplification on git-clone and git-init Documentation/CodingGuidelines | 34 ++++++++++++++----------- Documentation/asciidoc.conf | 12 +++++++++ Documentation/asciidoctor-extensions.rb | 17 +++++++++++++ Documentation/git-clone.txt | 20 +++++++-------- Documentation/git-init.txt | 12 ++++----- t/t0450-txt-doc-vs-help.sh | 11 +++----- 6 files changed, 68 insertions(+), 38 deletions(-) base-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1766 Range-diff vs v1: 1: 704f0333ef1 ! 1: aba144f4ff3 doc: introduce a synopsis custom paragraph attribute @@ Documentation/asciidoc.conf: git-relative-html-prefix= +ifdef::backend-docbook[] +ifdef::doctype-manpage[] +[paradef-default] -+#synopsis-style=template="verseparagraph",filter="sed -E 's!<[a-z-]+>!\\0!g' -E 's!([a-z-]+)!\\1!g'" -+synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1\\2!g;s!(<\\;[a-zA-Z0-9-.]+>\\;)!\\1!g'" -+#synopsis-style=template="verseparagraph" ++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="perl -pe 's!([\[\] |()>]|^)([+a-zA-Z0-9-:+=]+)!\\1\\2!g;s!(<\\;[a-zA-z0-9-.]+>\\;)!\\1!g'" ++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[] ## Documentation/asciidoctor-extensions.rb ## @@ Documentation/asciidoctor-extensions.rb: module Git + + 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__') ++ 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 @@ Documentation/asciidoctor-extensions.rb: module Git postprocessor Git::Documentation::DocumentPostProcessor end - ## Documentation/git-clone.txt ## -@@ Documentation/git-clone.txt: SYNOPSIS - [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`] - [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`] - [++--filter=++____] [`--also-filter-submodules`]] [`--`] __ -- [__] -+ [____] - - DESCRIPTION - ----------- - - ## Documentation/git-init.txt ## -@@ Documentation/git-init.txt: SYNOPSIS - [`--separate-git-dir` __] [++--object-format=++____] - [++--ref-format=++____] - [`-b` __ | ++--initial-branch=++____] -- [++--shared++[++=++____]] [__] -+ [`--shared`[++=++____]] [____] - - - DESCRIPTION - ## t/t0450-txt-doc-vs-help.sh ## @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () { fi && b2t="$(builtin_to_txt "$builtin")" && sed -n \ - -e '/^\[verse\]$/,/^$/ { -+ -e '/^\[\(verse\|synopsis\)\]$/,/^$/ { ++ -E '/^\[(verse|synopsis)\]$/,/^$/ { /^$/d; - /^\[verse\]$/d; - s/_//g; - s/++//g; - s/`//g; -+ /^\[\(verse\|synopsis\)\]$/d; - s/{litdd}/--/g; - s/'\''\(git[ a-z-]*\)'\''/\1/g; +- s/{litdd}/--/g; +- s/'\''\(git[ a-z-]*\)'\''/\1/g; ++ /^\[(verse|synopsis)\]$/d; ++ s/\{litdd\}/--/g; ++ s/'\''(git[ a-z-]*)'\''/\1/g; + p; + }' \ 2: b0547422e5c = 2: b6387bef40d doc: update the guidelines to reflect the current formatting rules 3: 3bcbe455747 ! 3: 2a61e0945de doc: apply synopsis simplification on git-clone and git-init @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory - [`-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`] +- [`--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] @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti - [`--separate-git-dir` __] [++--object-format=++____] - [++--ref-format=++____] - [`-b` __ | ++--initial-branch=++____] -- [`--shared`[++=++____]] [____] +- [++--shared++[++=++____]] [__] +[synopsis] +git init [-q | --quiet] [--bare] [--template=] + [--separate-git-dir ] [--object-format=]