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-]+>!<emphasis>\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\1</literal>!g'" -+synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1<literal>\\2</literal>!g;s!(<\\;[a-zA-Z0-9-.]+>\\;)!<emphasis>\\1</emphasis>!g'" -+#synopsis-style=template="verseparagraph" ++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])([-=a-zA-Z0-9:+.]+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!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<code>\\2</code>!g;s!(<\\;[a-zA-z0-9-.]+>\\;)!<em>\\1</em>!g'" ++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])([-=a-zA-Z0-9:+.]+)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!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++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`] - [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`] - [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ -- [_<directory>_] -+ [__<directory>__] - - DESCRIPTION - ----------- - - ## Documentation/git-init.txt ## -@@ Documentation/git-init.txt: SYNOPSIS - [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] - [++--ref-format=++__<format>__] - [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] -- [++--shared++[++=++__<permissions>__]] [_<directory>_] -+ [`--shared`[++=++__<permissions>__]] [__<directory>__] - - - 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` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_] - [`--dissociate`] [`--separate-git-dir` _<git-dir>_] -- [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`] -- [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`] -- [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`] +- [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`] +- [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++] +- [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`] - [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ -- [__<directory>__] +- [_<directory>_] +[synopsis] +git clone [--template=<template-directory>] + [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti - [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] - [++--ref-format=++__<format>__] - [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] -- [`--shared`[++=++__<permissions>__]] [__<directory>__] +- [++--shared++[++=++__<permissions>__]] [_<directory>_] +[synopsis] +git init [-q | --quiet] [--bare] [--template=<template-directory>] + [--separate-git-dir <git-dir>] [--object-format=<format>] -- gitgitgadget
