From patchwork Sun Aug 11 15:20:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Derrick Stolee via GitGitGadget X-Patchwork-Id: 13759767 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 DE85AD29E for ; Sun, 11 Aug 2024 15:20:16 +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=SM7TSTsfcrumoDPHipXsv48hgUZqof5V7axr5hQBsIzqIFcY2JbMkVdMVxe6mNVBLnXd0A4uPVcZmCSCCvclqgMzku4Drp673zV0QkqA8y5Md/fvx8EoRtLKbA1WZaSgVZCiKukqkbqGgfqxKWv2ABYVT+NNQTh2xEYXOPMx8sQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1723389619; c=relaxed/simple; bh=F7zJBalsIEmP+joUVJ/BaLVVyxIjWyg3LSHGF0/q5Hg=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=HDre58aTRHSliVigRNvbXtngYXbSYSHvg3leR5cVDN5epERf7YkVHo1Pg0E9L8Cw8k94brplsjGBp3V9bVRLhHocfetixPwdaSIYTXfCF/4N8vmVQWUZti3Iyn6A5EXGG0tuPRQlemXfl0pORPP/aG4JR6K5ozT+xVVFXeadkDk= 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=Bkx+P5pf; 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="Bkx+P5pf" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-42803bbf842so34679845e9.1 for ; Sun, 11 Aug 2024 08:20:16 -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=tJgSigznHMP7NzHStgwwsxpLbayZmCFyZX7tRAc58iw=; b=Bkx+P5pfAqKoJ0sgVKMpi+FF2jec5NpTcAd50Ubk7Nq0i84RH7aLZOCjkv556zDbMA vQFGahwrBh42SkEJRy33aUsPKrvJiRDJX9HlbPyYgnWl2QOlipIvWFHySdb8txO7K8NW zBCyBDh7UiBy7a3g9Ri2owtFFJmfxAsACmoz/bJRLZh6U04uuF03deu24Q9B03omub4n FtuyWlv4TS4zsRtbhM+09paWM+Keo3sy7/i9lRPad2AssAqdG1qYbXy3bMZ4mxoZD94f d/9Tft2H9X5qFCu8IuOp6DeJ9Y2/pgKPq7tXuWWqXmHf5ptNsye7AP+9SlEDWP02FrIc l80A== 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=tJgSigznHMP7NzHStgwwsxpLbayZmCFyZX7tRAc58iw=; b=DSLup2nmkr5AJW6J1ODQxOdkXkOh1KCm2gX1qygwmsZxQq89nT+yFTTmVGVBvWz5NL QwKLm0f9AJFzXEzLbCSYqVtBTu7hintlnDvIP96ZMFkscMwpJPO1OJUYfXlSpTEj35A8 ngfq0dCOwoutDgW9ntHBOlRWYAIUvFsBMKx/U4dxEJUqm9vwaWz48sXub0ro24CD1tKa BAYc/StqOiODYxLq9/01FugIJgnSE8VSBNEUZj93MQsr4ikjwLhuAGzRfBCPGy7f5fBW XOY+vy1o9Kl+r/zoG2txgAXLBxEt4ToihlNbhFMAPgyTRiR0KVWRD8ELzksVCYWRWyF6 m+gQ== X-Gm-Message-State: AOJu0YxdpaOEq8y9iD/Ar0hMUI1eYI68lv9oZ8VkVk8zDmb77r98+a8N aA32h49Ec69jIqT3urxtVl0zc2qfWdyGeRiJNqPTakqjLu3092lmrXRZ9A== X-Google-Smtp-Source: AGHT+IFdp94UEjOf8Wq9iYBdaQt4KHmZAzIH8TISIVYA1EUB2WWrRGidPKZL3YQKISBJtCAUjsnF/w== X-Received: by 2002:a05:6000:1844:b0:367:90cc:fe8b with SMTP id ffacd0b85a97d-36d5e7fd9c6mr5756634f8f.27.1723389614157; 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 ffacd0b85a97d-36e4ecc7b2asm5078110f8f.102.2024.08.11.08.20.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 11 Aug 2024 08:20:13 -0700 (PDT) Message-Id: In-Reply-To: References: From: " =?utf-8?q?Jean-No=C3=ABl?= Avila via GitGitGadget" Date: Sun, 11 Aug 2024 15:20:09 +0000 Subject: [PATCH v3 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'. Additionally, as s macro is introduce to apply the same rules freely in the text. 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 Changes since V2: * introduce the s macro to freely apply synopsis styling wherever needed, without formatting hassle. 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 | 54 +++++++++--------- Documentation/asciidoc.conf | 21 ++++++- Documentation/asciidoctor-extensions.rb | 33 +++++++++++ Documentation/git-clone.txt | 76 ++++++++++++------------- Documentation/git-init.txt | 33 +++++------ Documentation/urls.txt | 26 ++++----- t/t0450-txt-doc-vs-help.sh | 11 ++-- 7 files changed, 150 insertions(+), 104 deletions(-) base-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1766 Range-diff vs v2: 1: aba144f4ff3 ! 1: 0d7c1dd8f26 doc: introduce a synopsis custom paragraph attribute @@ Commit message 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 ## -@@ Documentation/asciidoc.conf: git-relative-html-prefix= +@@ + + [macros] + (?su)[\\]?(?Plinkgit):(?P\S*?)\[(?P.*?)\]= +- ++(?su)[\\]?(?Ps):(?P\S*?)\["(?P.*?)"\]= + [attributes] + asterisk=* + plus=+ +@@ Documentation/asciidoc.conf: 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[] +@@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[] + git-relative-html-prefix= [linkgit-inlinemacro] {target}{0?({0})} - endif::backend-xhtml11[] ++ ++[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'" ++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[] ++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 + 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' @@ Documentation/asciidoctor-extensions.rb: module Git output end @@ 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}') ++ l.gsub(/([\[\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\1{empty}`\2`{empty}') + .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') + .gsub(']', ']{empty}') + end @@ Documentation/asciidoctor-extensions.rb: module Git Asciidoctor::Extensions.register do inline_macro Git::Documentation::LinkGitProcessor, :linkgit ++ inline_macro Git::Documentation::SynopsisMacroProcessor + block Git::Documentation::SynopsisBlock postprocessor Git::Documentation::DocumentPostProcessor end 2: b6387bef40d ! 2: 92f3121cf4e doc: update the guidelines to reflect the current formatting rules @@ Commit message ## Documentation/CodingGuidelines ## @@ Documentation/CodingGuidelines: 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 3: 2a61e0945de ! 3: 02406b91894 doc: apply synopsis simplification on git-clone and git-init @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory DESCRIPTION ----------- +@@ Documentation/git-clone.txt: 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 +@@ Documentation/git-clone.txt: 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 +@@ Documentation/git-clone.txt: 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=++__