WIP resolves Issue 3884: extension documentation

docs/modules/api/pages/options.adoc

@@ -1,5 +1,7 @@
 = API Options
 
+These options may be passed in a hash to the Asciidoctor load and convert methods as a second argument.
+
 [cols="~,~,30%,~"]
 |===
 |Name |Description |Default value |Allowed values
@@ -53,13 +55,14 @@ _(Experimental)._
 |`erb`, `erubis`
 
 |`:extensions`
-|A Ruby block that registers (and possibly defines) xref:extensions:register.adoc[Asciidoctor extensions] for this instance of the processor.
+|Specifies a xref:extensions:register.adoc#groups[processor extension group] to be registered globally for this instance of the processor.
 |_not set_
-|A Ruby block that conforms to the Asciidoctor extensions API (the same code that would be passed to the `Extensions.register` method).
+|A Ruby block, class, or instance that provides a processor extension group (the same code that would be passed to the `Extensions.register` method).
 
 |`:extension_registry`
-|Overrides the extensions registry instance.
-Instead of providing a Ruby block containing extensions to register, this option lets you replace the extension registry itself, giving you complete control over how extensions are registered for this processor.
+|Specifies an explicit xref:extensions:glossary.adoc#id_registry[extensions registry] instance.
+This registry instance can be configured independently of any groups registered globally using the :extensions option.
+All processors registered by globally registered groups will also be added to the registry instance upon activation.
 |_not set_
 |`Extensions::Registry` instance
 

docs/modules/extensions/examples/block-collapsible-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -s -r ./block-collapsible-extension.rb ./block-collapsible-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/block-collapsible-extension-sample.adoc

@@ -0,0 +1,7 @@
+.Show JSON
+[collapsible,json]
+----
+{
+   "foo": "bar"
+}
+----

docs/modules/extensions/examples/block-collapsible-extension-sample.html

@@ -0,0 +1,12 @@
+<details>
+<summary class="title">Show JSON</summary>
+<div class="content">
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-json" data-lang="json">{
+   "foo": "bar"
+}</code></pre>
+</div>
+</div>
+</div>
+</details>

docs/modules/extensions/examples/block-collapsible-extension.rb

@@ -0,0 +1,29 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class CollapsibleBlock < Asciidoctor::Extensions::BlockProcessor
+  enable_dsl
+
+  named :collapsible
+  contexts :listing
+  positional_attributes 'language'
+
+  def process parent, reader, attrs
+    lang = attrs.delete 'language'
+    attrs['title'] ||= 'Show Listing'
+    example = create_example_block parent, [], attrs, content_model: :compound
+    example.set_option 'collapsible'
+    listing = create_listing_block example, reader.readlines, nil
+    if lang
+      listing.style = 'source'
+      listing.set_attr 'language', lang
+      listing.commit_subs
+    end
+    example << listing
+    example
+  end
+end
+
+Asciidoctor::Extensions.register do
+  block CollapsibleBlock
+end

docs/modules/extensions/examples/block-macro-gist-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -s -r ./block-macro-gist-extension.rb ./block-macro-gist-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/block-macro-gist-extension-sample.adoc

@@ -0,0 +1,2 @@
+.My Gist
+gist::123456[]

docs/modules/extensions/examples/block-macro-gist-extension-sample.html

@@ -0,0 +1,6 @@
+<div class="openblock gist">
+<div class="title">My Gist</div>
+<div class="content">
+<script src="https://gist.github.com/123456.js"></script>
+</div>
+</div>

docs/modules/extensions/pages/block-macro-processor.adoc → docs/modules/extensions/examples/block-macro-gist-extension.rb

@@ -1,32 +1,14 @@
-= Block Macro Processor Extension Example
-:navtitle: Block Macro Processor
-
-Purpose::
-Create a block macro named `gist` for embedding a gist.
-
-== sample-with-gist-macro.adoc
-
-[source,asciidoc]
-----
-.My Gist
-gist::123456[]
-----
-
-== GistBlockMacro
-
-[source,ruby]
-----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
 class GistBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
-  use_dsl
+  enable_dsl
 
   named :gist
 
   def process parent, target, attrs
     title_html = (attrs.has_key? 'title') ?
-        %(<div class="title">#{attrs['title']}</div>\n) : nil
+                   %(<div class="title">#{attrs['title']}</div>\n) : nil
 
     html = %(<div class="openblock gist">
 #{title_html}<div class="content">
@@ -37,15 +19,8 @@ def process parent, target, attrs
     create_pass_block parent, html, attrs, subs: nil
   end
 end
-----
-
-== Usage
 
-[source,ruby]
-----
+# Self-registering
 Asciidoctor::Extensions.register do
   block_macro GistBlockMacro if document.basebackend? 'html'
 end
-
-Asciidoctor.convert_file 'sample-with-gist.adoc', safe: :safe
-----

docs/modules/extensions/examples/block-shout-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -s -r ./block-shout-extension.rb ./block-shout-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/block-shout-extension-sample.adoc

@@ -0,0 +1,5 @@
+[shout]
+The time is now. Get a move on.
+
+[shout,4]
+I mean it.

docs/modules/extensions/examples/block-shout-extension-sample.html

@@ -0,0 +1,6 @@
+<div class="paragraph">
+<p>THE TIME IS NOW! GET A MOVE ON!</p>
+</div>
+<div class="paragraph">
+<p>I MEAN IT!!!!</p>
+</div>

docs/modules/extensions/examples/block-shout-extension.rb

@@ -0,0 +1,23 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class ShoutBlock < Asciidoctor::Extensions::BlockProcessor
+  PeriodRx = /\.(?= |$)/
+
+  enable_dsl
+
+  named :shout
+  contexts :paragraph
+  positional_attributes 'vol'
+  content_model :simple
+
+  def process parent, reader, attrs
+    volume = ((attrs.delete 'vol') || 1).to_i
+    create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs
+  end
+end
+
+# self-registering
+Asciidoctor::Extensions.register do
+  block ShoutBlock
+end

docs/modules/extensions/examples/docinfo-google-analytics-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -r ./docinfo-google-analytics-extension.rb -a google-analytics-account=UA-ABCXYZ123  -a linkcss=true -a reproducible=true ./docinfo-google-analytics-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/docinfo-google-analytics-extension-sample.adoc

@@ -0,0 +1,3 @@
+= Silly Page
+
+Who would look at this content?

docs/modules/extensions/examples/docinfo-google-analytics-extension-sample.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 2.0.13.dev">
+<title>Silly Page</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
+<link rel="stylesheet" href="./asciidoctor.css">
+</head>
+<body class="article">
+<div id="header">
+<h1>Silly Page</h1>
+</div>
+<div id="content">
+<div class="paragraph">
+<p>Who would look at this content?</p>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+</div>
+</div>
+<script>
+(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+ga('create','UA-ABCXYZ123','auto');
+ga('send','pageview');
+</script>
+</body>
+</html>

docs/modules/extensions/pages/docinfo-processor.adoc → docs/modules/extensions/examples/docinfo-google-analytics-extension.rb

@@ -1,15 +1,8 @@
-= Docinfo Processor Extension Example
-:navtitle: Docinfo Processor
+require 'asciidoctor'
+require 'asciidoctor/extensions'
 
-Purpose::
-Appends the Google Analytics tracking code to the bottom of an HTML document.
-
-== GoogleAnalyticsDocinfoProcessor
-
-[source,ruby]
-----
 class GoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor
-  use_dsl
+  enable_dsl
   at_location :footer
   def process document
     return unless (ga_account_id = document.attr 'google-analytics-account')
@@ -23,15 +16,8 @@ def process document
 </script>)
   end
 end
-----
 
-== Usage
-
-[source,ruby]
-----
+# Self-registering
 Asciidoctor::Extensions.register do
   docinfo_processor GoogleAnalyticsDocinfoProcessor
 end
-
-Asciidoctor.convert_file 'sample.adoc', safe: :safe, attributes: 'UA-ABCXYZ123'
-----

docs/modules/extensions/examples/extensions-test.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+for test in *-runner.sh
+do
+  ./$test
+done
+
+git diff *-sample.html

docs/modules/extensions/examples/include-uri-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -s -r ./include-uri-extension.rb ./include-uri-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/include-uri-extension-sample-source.adoc

@@ -0,0 +1,5 @@
+.Gemfile
+[source,ruby]
+----
+/include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
+----

docs/modules/extensions/examples/include-uri-extension-sample.adoc

@@ -0,0 +1,5 @@
+.Gemfile
+[source,ruby]
+----
+include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
+----

docs/modules/extensions/examples/include-uri-extension-sample.html

@@ -0,0 +1,35 @@
+<div class="listingblock">
+<div class="title">Gemfile</div>
+<div class="content">
+<pre class="highlight"><code class="language-ruby" data-lang="ruby">source 'https://rubygems.org'
+
+# Look in asciidoctor.gemspec for runtime and development dependencies
+gemspec
+
+group :development do
+  gem 'asciimath', ENV['ASCIIMATH_VERSION'] if ENV.key? 'ASCIIMATH_VERSION'
+  gem 'pygments.rb', ENV['PYGMENTS_VERSION'] if ENV.key? 'PYGMENTS_VERSION'
+  gem 'rouge', ENV['ROUGE_VERSION'] if ENV.key? 'ROUGE_VERSION'
+  gem 'haml', '~&gt; 4.0' if RUBY_ENGINE == 'truffleruby'
+end
+
+group :docs do
+  gem 'yard'
+  gem 'yard-tomdoc'
+end
+
+# enable this group to use Guard for continuous testing
+# after removing comments, run `bundle install` then `guard`
+#group :guardtest do
+#  gem 'guard'
+#  gem 'guard-test'
+#  gem 'libnotify'
+#  gem 'listen', :github =&gt; 'guard/listen'
+#end
+
+group :ci do
+  gem 'simplecov', '~&gt; 0.16.0'
+  gem 'json', '~&gt; 2.2.0' if RUBY_ENGINE == 'truffleruby'
+end</code></pre>
+</div>
+</div>

docs/modules/extensions/examples/include-uri-extension.rb

@@ -0,0 +1,20 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require 'open-uri'
+
+class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+  def handles? target
+    (target.start_with? 'http://') or (target.start_with? 'https://')
+  end
+
+  def process doc, reader, target, attributes
+    content = (open target).readlines
+    reader.push_include content, target, target, 1, attributes
+    reader
+  end
+end
+
+# Self-registering
+Asciidoctor::Extensions.register do
+  include_processor UriIncludeProcessor
+end

docs/modules/extensions/examples/inline-man-extension-runner.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+#tag::runner[]
+asciidoctor -s -r ./inline-man-extension.rb ./inline-man-extension-sample.adoc
+#end::runner[]

docs/modules/extensions/examples/inline-man-extension-sample.adoc

@@ -0,0 +1 @@
+See man:gittutorial[7] to get started.

docs/modules/extensions/examples/inline-man-extension-sample.html

@@ -0,0 +1,3 @@
+<div class="paragraph">
+<p>See <a href="gittutorial.html(7)">gittutorial</a> to get started.</p>
+</div>