build on the inline macro example in the docs that resolves the page number

3 files changed, 115 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/advanced-inline-pagenum-macro.rb b/docs/modules/extend/examples/advanced-inline-pagenum-macro.rb
new file mode 100644
index 00000000..1713319e
--- /dev/null
+++ b/docs/modules/extend/examples/advanced-inline-pagenum-macro.rb
@@ -0,0 +1,30 @@
+Asciidoctor::Extensions.register do
+  inline_macro :pagenum do
+    format :short
+    parse_content_as :text
+    process do |parent, scope|
+      doc = parent.document
+      if scope == 'section'
+        if doc.nested?
+          inner_doc = doc
+          parent = (doc = doc.parent_document).find_by(context: :table_cell) do |it|
+            it.style == :asciidoc && it.inner_document == inner_doc
+          end.first
+        end
+        section = (closest parent, :section) || doc
+        physical_pagenum = section.attr 'pdf-page-start'
+      else
+        physical_pagenum = doc.converter.page_number
+      end
+      create_inline parent, :quoted, %(#{physical_pagenum + 1 - (start_page_number doc)})
+    end
+
+    def closest node, context
+      node.context == context ? node : ((parent = node.parent) && (closest parent, context))
+    end
+
+    def start_page_number doc
+      doc.converter.index.start_page_number
+    end
+  end
+end
diff --git a/docs/modules/extend/examples/inline-pageref-macro.rb b/docs/modules/extend/examples/inline-pageref-macro.rb
new file mode 100644
index 00000000..651c3d91
--- /dev/null
+++ b/docs/modules/extend/examples/inline-pageref-macro.rb
@@ -0,0 +1,36 @@
+Asciidoctor::Extensions.register do
+  inline_macro :pageref do
+    process do |parent, refid|
+      doc = (doc = parent.document).nested? ? doc.parent_document : doc
+      if (ref = doc.catalog[:refs][refid])
+        section = (closest ref, :section) || doc
+        unless (physical_pagenum = section.attr 'pdf-page-start')
+          doc.instance_variable_set :@pass, 1 unless (doc.instance_variable_get :@pass) == 2
+          next create_inline parent, :quoted, '00' # reserve space for real page number
+        end
+        attributes = { 'refid' => refid, 'fragment' => refid, 'path' => nil }
+        create_anchor parent, %(#{physical_pagenum + 1 - (start_page_number doc)}), { type: :xref, attributes: attributes }
+      else
+        create_inline parent, :quoted, '???'
+      end
+    end
+
+    def closest node, context
+      node.context == context ? node : ((parent = node.parent) && (closest parent, context))
+    end
+
+    def start_page_number doc
+      doc.converter.index.start_page_number
+    end
+  end
+
+  postprocessor do
+    process do |doc|
+      if (doc.instance_variable_get :@pass) == 1
+        doc.instance_variable_set :@pass, 2
+        doc.convert # WARNING: this may have side effects
+      end
+      doc.converter
+    end
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 19743373..bf91bde1 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -407,6 +407,7 @@ In this case, we're interested in retrieving the page number and inserting it in
 
 Let's create an inline macro named `pagenum` that inserts the current page number into the document when the macro is converted.
 
+.inline-pagenum-macro.rb
 [,ruby]
 ----
 include::example$inline-pagenum-macro.rb[]
@@ -422,6 +423,54 @@ Here's how this macro would be used.
 You're looking at page number pagenum:[].
 ----
 
+We can build on this extension to show the start page of the current section by adding support for a scope parameter.
+We can also have it show the page number label instead of the physical page number by subtracting the start page number (which is stored on the index catalog).
+
+.advanced-inline-pagenum-macro.rb
+[,ruby]
+----
+include::example$advanced-inline-pagenum-macro.rb[]
+----
+
+The macro can now be used to show the page number label for the current section:
+
+[,asciidoc]
+----
+= Document Title
+:doctype: book
+
+== Chapter A
+
+You're reading a section that begins on page pagenum:[section].
+----
+
+Taking inspiration from this extension, we develop another inline macro named `pageref` that resolves the page number of the closest parent section of a reference.
+
+.inline-pageref-macro.rb
+[,rb]
+----
+include::example$inline-pageref-macro.rb[]
+----
+
+The only caveat of this extension is that it has to convert the document a second time to resolve any forward references.
+That's because the page number of a section is not known until it is rendered.
+
+Here's how the `pageref` macro would be used:
+
+[,asciidoc]
+----
+= Document Title
+:doctype: book
+
+== Chapter A
+
+Content.
+
+== Chapter B
+
+Refer to <<_chapter_a>> on page pageref:_chapter_a[].
+----
+
 == Resources
 
 To find even more examples of how to override the behavior of the converter, refer to the extended converter in the {url-infoq-template}[InfoQ Mini-Book template^].