[PATCH v5 0/3] doc: introducing synopsis para

["Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>]

In the continuation of the simplification of manpage editing, the synopsis
processing that was developed for synopsis paragraph style is also applied
to all inline backquoted texts.

Refining the magic regexp took more time than expected, but this one should
really enhance writers'experience. I had to fight a bit more with
asciidoctor, due to discrepancies between version 2.0 on my laptop and the
1.5.6 used by Github actions.

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.

Changes since V3:

 * replace s macro by direct processing of literal text at the level of
   output processors.

Changes since V4:

 * used BRE in sed filter
 * rework the processing of three dots

Jean-Noël Avila (3):
  doc: introduce a synopsis typesetting
  doc: update the guidelines to reflect the current formatting rules
  doc: apply synopsis simplification on git-clone and git-init

 Documentation/CodingGuidelines          | 58 +++++++++--------
 Documentation/asciidoc.conf             | 20 ++++++
 Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
 Documentation/git-clone.txt             | 78 +++++++++++-----------
 Documentation/git-init.txt              | 35 +++++-----
 Documentation/urls.txt                  | 26 ++++----
 ci/install-dependencies.sh              |  1 +
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 8 files changed, 209 insertions(+), 107 deletions(-)


base-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/1766

Range-diff vs v4:

 1:  c09968d7ccb ! 1:  2946cc80314 doc: introduce a synopsis typesetting
     @@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
      +ifdef::backend-docbook[]
      +ifdef::doctype-manpage[]
      +[paradef-default]
     -+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?+)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<emphasis>\\0</emphasis>!g'"
     ++synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!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<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<em>\\0</em>!g'"
     ++synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
       endif::backend-xhtml11[]
      
       ## Documentation/asciidoctor-extensions.rb ##
 2:  c48649ccd63 = 2:  06b8fff6a57 doc: update the guidelines to reflect the current formatting rules
 3:  719188da711 = 3:  a76998d6443 doc: apply synopsis simplification on git-clone and git-init

-- 
gitgitgadget