Revert "Merge branch 'ja/doc-synopsis-markup' into next"

This reverts commit d471154, reversing
changes made to 578e378, as it was
reported that the new formatting would not work due to lack of "sed -E"
in some environments.

See threads starting from <[email protected]> for details.

Author: gitster

Documentation/CodingGuidelines

@@ -828,80 +828,78 @@ Markup:
    _<new-branch-name>_
    _<template-directory>_
 
+ 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:
    _<git-dir>_
    _<key-id>_
 
- 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 <n>`
-   `--sort=<key>`
-   `<directory>/.git`
-   `remote.<name>.mirror`
-   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+ 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 __<like-this>__
+ Unconstrained formatting for literal formatting is ++like this++
+   `--jobs` _<n>_
+   ++--sort=++__<key>__
+   __<directory>__++/.git++
+   ++remote.++__<name>__++.mirror++
 
-As a side effect, backquoted placeholders are correctly typeset, but
-this style is not recommended.
+ caveat: ++ unconstrained format is not verbatim and may expand
+ content. Use Asciidoc escapes inside them.
 
 Synopsis Syntax
 
- The synopsis (a paragraph with [synopsis] attribute) is automatically
- formatted by the toolchain and does not need typesetting.
+ Syntax grammar is formatted neither as literal nor as placeholder.
 
  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:
-   <file>...
+   _<file>_...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [<file>...]
+   [_<file>_...]
    (Zero or more of <file>.)
 
- An optional parameter needs to be typeset with unconstrained pairs
-   [<repository>]
-
-   --exec-path[=<path>]
+   ++--exec-path++[++=++__<path>__]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [<patch>...]
+   [_<patch>_...]
    (Zero or more of <patch>.  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:
-   [(<rev>|<range>)...]
+   [(_<rev>_ | _<range>_)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(-p <parent>)...]
+   [(`-p` _<parent>_)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   git remote set-head <name> (-a|-d|<branch>)
+   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
    (One and only one of "-a", "-d" or "<branch>" _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

Documentation/asciidoc.conf

@@ -28,10 +28,6 @@ ifdef::backend-docbook[]
 {0#<citerefentry>}
 {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
 {0#</citerefentry>}
-
-[literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\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[]
@@ -60,20 +56,4 @@ ifdef::backend-xhtml11[]
 git-relative-html-prefix=
 [linkgit-inlinemacro]
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
-
-[literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\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<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'"
 endif::backend-xhtml11[]

Documentation/asciidoctor-extensions.rb

@@ -1,7 +1,5 @@
 require 'asciidoctor'
 require 'asciidoctor/extensions'
-require 'asciidoctor/converter/docbook5'
-require 'asciidoctor/converter/html5'
 
 module Git
   module Documentation
@@ -41,95 +39,10 @@ def process document, output
         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? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
-        elsif type == :latexmath
-          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
-          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
-        elsif type == :monospaced
-          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
-              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
-        else
-          open, close, supports_phrase = QUOTE_TAGS[type]
-          text = node.text
-          if node.role
-            if supports_phrase
-              quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
-            else
-              quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
-            end
-          else
-            quoted_text = %(#{open}#{text}#{close})
-          end
-          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{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(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
-              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
-
-        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
-              %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
-            end
-          elsif node.role
-            if tag
-              %(#{open.chop} class="#{node.role}">#{node.text}#{close})
-            else
-              %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
-            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