fix examples

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/pre-front-matter-extension-sample.adoc

@@ -1,3 +1,4 @@
+---
 tags: [announcement, website]
 ---
 = Document Title

docs/modules/extensions/examples/pre-front-matter-extension-sample.html

@@ -1,16 +1,11 @@
 <div class="paragraph">
-<p>tags: [announcement, website]
----
-= Document Title</p>
-</div>
-<div class="paragraph">
 <p>content</p>
 </div>
 <div class="literalblock">
 <div class="title">Captured front matter</div>
 <div class="content">
 <pre>---
-{front-matter}
+tags: [announcement, website]
 ---</pre>
 </div>
 </div>

docs/modules/extensions/examples/pre-front-matter-extension.rb

@@ -3,20 +3,16 @@
 
 class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
   def process document, reader
-    lines = reader.lines # get raw lines
+    lines = reader.lines # get copy of raw lines
     return reader if lines.empty?
     front_matter = []
     if lines.first.chomp == '---'
-      original_lines = lines.dup
       lines.shift
       while !lines.empty? && lines.first.chomp != '---'
         front_matter << lines.shift
       end
 
-      if (first = lines.first).nil? || first.chomp != '---'
-        lines = original_lines
-      else
-        lines.shift
+      if (first = lines.first) && first.chomp == '---'
         document.attributes['front-matter'] = front_matter.join.chomp
         # advance the reader by the number of lines taken
         (front_matter.length + 2).times { reader.advance }

docs/modules/extensions/pages/block-example.adoc

@@ -13,6 +13,7 @@ Here's the code for the block processor:
 include::example$nestable-extension-class.rb[]
 ----
 
+[sidebar]
 This extension takes the block content, expressed as a paragraph or example block, and converts it unmodified to an open block.
 The purpose is to allow nested open blocks, which are not yet directly available through Asciidoc syntax (see https://github.com/asciidoctor/asciidoctor/issues/1121).
 This extension allows you to lay out your content in arbitrarily nested `div` elements, with specified css classes (mapped from the block role).
@@ -46,8 +47,7 @@ The other choices are to write it as a block or a class instance, covered in the
 
 `extend_dsl` causes an appropriate DSL module for the type of processor to  be mixed in, defining class methods to tell Asciidoctor about our extension.
 
-The next three lines use the DSL to specify the block name, the contexts in which it is allowed, and the positional parameter 'role'.
-Since 'role' is an attribute Asciidoctor already recognizes and maps to css class, specifying `[nestable,myrole]` will give the output div the class 'myrole'.
+The next two lines use the DSL to specify the block name and the contexts in which it is allowed.
 
 In the extension class, finally, is the `process` method, which is called with the `reader` parameter set to the contents of the block.
 This is where the extension does its work.

docs/modules/extensions/pages/index.adoc

@@ -10,25 +10,25 @@ Extensions are central to the power of AsciiDoc because they open up the languag
 To implement this critical functionality, Asciidoctor provides an extension API that offers a set of extension points.
 Extensions in Asciidoctor are easy to write, powerful, and simple to distribute.
 
-Asciidoctor also allows extensions to be written using the full power of the programming language of your Asciidoctor variant: Ruby, Java or other JVM based languages, or Javascript.
+Asciidoctor allows extensions to be written using the full power of the programming language of your Asciidoctor variant: Ruby, Java or other JVM based languages, or Javascript.
 An extension may be included in custom code or packaged and distributed using a language-standard mechanism such as RubyGems, Jars/Maven, or npm packages.
 
 There are two general types of processors:
 
 Document Processor::
-  A processor that operates on the document as text as an array of lines or as a string, or, for tree processors, as a block tree.
-Document processors are invoked at several stages of processing, before, during, and after conversion.
-A document processor does not have an explicit invocation in the document.
+A document processor does not have an explicit invocation in the document,
+but is invoked at one of several stages of processing, before, during, and after conversion.
+  A document processor operates on the document as text as an array of lines or as a string, or, for tree processors, as a block tree as a whole.
 Syntax Processor::
-  A processor that operates on the document as a DOM/AST tree.
 A syntax processor has a name and is invoked when that name is encountered in the document.
+  A syntax processor operates on the document as a DOM/AST tree, at the location in the tree corresponding to the invocation in the source.
 
 == Available extension points
 
 Asciidoctor provides the following extension points, shown in the order of invocation, interleaved with a description of Asciidoctor processing stages.
 To be more specific, these are types of Processor, and a concrete implementation extends the corresponding Processor subclass.
 
-. Asciidoctor starts with a source document and starts reading it into an array of lines and preprocessing it. First, as `include::` directives are processed as they are encountered.
+. Asciidoctor starts with a source document and starts reading it into an array of lines and preprocessing it. First, `include::` directives are processed as they are encountered.
 
 xref:processors/include-processor.adoc[] (Document)::
 Processes the `include::<target>[attributes]` directive for targets it handles.

docs/modules/extensions/pages/processors/block-processor.adoc

@@ -18,6 +18,10 @@ include::page$processor.adoc[tag=syntaxproc]
 Sets the contexts allowed for this block.
 The choices are:
 
+////
+TODO: put this table somewhere more appropriate
+////
+
 [cols=2,opts=headers]
 |===
 | Context
@@ -33,7 +37,7 @@ The choices are:
 | `----`
 
 | `:literal`
-| `....`
+| `\....`
 
 | `:example`
 | `====`
@@ -140,9 +144,9 @@ include::example$block-collapsible-extension-runner.sh[tag=runner]
 === Input
 
 [source,adoc]
-----
+------
 include::example$block-collapsible-extension-sample.adoc[]
-----
+------
 
 === Output
 

docs/modules/extensions/pages/processors/docinfo-processor.adoc

@@ -18,11 +18,12 @@ Asciidoctor::Extensions::DocinfoProcessor
 include::page$processor.adoc[tag=docproc]
 
 `at_location`::
-When called with `footer`, the supplied content will be added to the footer of the document.
+Specifies the location for insertion of the added content.
 
-NOTE: The default location is `:head`.
-The recognized values for html5 are `:head` and `:footer`.
-The recognized values for docbook5 are `:header` and `:footer`.
+* The default location is `:head`.
+* The recognized values for html5 are `:head`, `:header`, and `:footer`.
+* The recognized values for docbook5 are `:header` and `:footer`.
+* Other environments, such as `jekyll-asciidoc`, may allow arbitrary custom locations.
 
 == Process method
 

docs/modules/extensions/pages/processors/include-processor.adoc

@@ -40,19 +40,6 @@ Include a file from a URI.
 
 TIP: Asciidoctor supports including content from a URI out of the box if you set the `allow-uri-read` attribute (not available if the safe mode is `secure`).
 
-== sample-with-uri-include.adoc
-
-[source,asciidoc]
-....
-:source-highlighter: coderay
-
-.Gemfile
-[source,ruby]
-----
-\include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
-----
-....
-
 === UriIncludeProcessor
 
 [source,ruby]
@@ -70,9 +57,9 @@ include::example$include-uri-extension-runner.sh[tag=runner]
 === Input
 
 [source,adoc]
-----
-include::example$include-uri-extension-sample.adoc[]
-----
+------
+include::example$include-uri-extension-sample-source.adoc[]
+------
 
 === Output
 

docs/modules/extensions/pages/processors/preprocessor.adoc

@@ -28,7 +28,7 @@ The document has not yet been parsed.
 The reader is positioned at the "start" of the document, which may be the actual beginning of the source available to the Reader or a position advanced by a preceding Preprocessor.
 Depending on the circumstances, the reader may be the reader originally created to read the source for the document or a reader from a preceding Preprocessor.
 
-The `process` method should a Reader or nil.
+The `process` method should return a Reader or nil.
 The returned reader can be an entirely new Reader or the original reader, perhaps advanced, as in the example.
 
 == Example