manpages: prepare for new manpage format

This commit adds a upcoming manpage format to the AsciiDoc
backend. The new format changes are:

 * The synopsis is now a section with a dedicated style. This
 "synopsis" style allows to automatically format the keywords as
 monospaced and <placeholders> as italic.
 * the backticks are now used to format synopsis-like syntax in inline
 elements.

All the manpages are processed with this format. It may upset the
formatting for older manpages, making it not consistent across a page,
but this will be a mild side effect, as this was not really consistent
before.

Signed-off-by: Jean-Noël Avila <[email protected]>

Author: jnavila

script/asciidoctor-extensions.rb

@@ -0,0 +1,63 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require 'asciidoctor/converter/html5'
+
+module Git
+  module Documentation
+    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(/(<([[:word:]]|[-0-9.])+>)/, '__\\1__')
+           .gsub(']', ']{empty}')
+        end
+        create_block parent, :verse, outlines, attrs
+      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;([[:word:]]|[-0-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
+  block Git::Documentation::SynopsisBlock
+end

script/update-docs.rb

@@ -9,6 +9,7 @@
 require 'yaml'
 require 'diffy'
 require_relative "version"
+require_relative 'asciidoctor-extensions'
 
 SITE_ROOT = File.join(File.expand_path(File.dirname(__FILE__)), '../')
 DOCS_INDEX_FILE = "#{SITE_ROOT}external/docs/content/docs/_index.html"