include revnumber in extended converter that adds document details af…

…ter document title; revise explanations in callouts

docs/modules/extend/examples/pdf-converter-article-title-with-author-and-date.rb

@@ -22,18 +22,19 @@ def ink_document_title title, opts
         inline_format_opts = [{ inherited: inherited }]
       end
       typeset_text_opts = { color: @font_color, inline_format: inline_format_opts }.merge opts
-      typeset_text title, (calc_line_metrics (opts.delete :line_height) || @base_line_height), typeset_text_opts 
+      typeset_text title, (calc_line_metrics (opts.delete :line_height) || @base_line_height), typeset_text_opts
     end
   end
 
   def ink_document_details doc, opts
-    revremark = doc.attr 'revremark' # <5>
-    if doc.author || doc.revdate || revremark # <6>
+    revnumber = doc.attr 'revnumber' # <5>
+    if doc.author || doc.revdate || revnumber # <6>
       move_down @theme.heading_h1_details_margin_top || 0 # <7>
       theme_font_cascade [:base, :heading_h1_details] do # <8>
         author_date_separator = doc.author && doc.revdate ? %( #{EmDash} ) : '' # <9>
-        revremark_separator = (doc.author || doc.revdate) && revremark ? ' | ' : '' # <10>
-        ink_prose %(#{doc.author}#{author_date_separator}#{doc.revdate}#{revremark_separator}#{revremark}), align: opts[:align] # <11>
+        revision = (doc.attr? 'revremark') ? %(#{revnumber} | #{doc.attr 'revremark'}) : revnumber if revnumber
+        revision_separator = revision && (doc.author || doc.revdate) ? %( #{EmDash} ) : '' # <10>
+        ink_prose %(#{doc.author}#{author_date_separator}#{doc.revdate}#{revision_separator}#{revision}), align: opts[:align] # <11>
       end
     end
   end

docs/modules/extend/pages/use-cases.adoc

@@ -57,38 +57,40 @@ The method `stroke_horizontal_rule` draws a horizontal line using the specified
 The method `ink_prose` is provided by Asciidoctor PDF to make writing text to the page easier.
 Finally, the method `convert` will convert and render the Asciidoctor node that is passed to it, in this case a block image.
 
-== Custom document header without a title page
+== Custom article title with document details
 
-Documents rendered as articles by Asciidoctor PDF don't have a title page by default.
-Instead their document title is shown on the first content page above the actual content.
+Documents rendered as articles (i.e., `doctype=article`) by Asciidoctor PDF don't have a title page by default.
+Instead the document title is shown on the first content page above the main content.
 
-Other than in articles rendered by Asciidoctor to HTML, and other than when rendered with a title page (e.g. document type book), the author, date and revision remark won't be shown by default.
-To get them included anyway, we can hook into the method `ink_general_heading`, which renders the document title.
-As `ink_general_heading` is also responsible for rendering other "headers" (e.g. section titles), we let it fall back to the default implementation for all headers that aren't the document title.
+The document details, which includes the author, date, and revision information (revnumber and revremark), are not shown in this mode.
+To insert them below the document title (similar to what the built-in HTML converter does), we can use an extended converter.
+To do so, we hook into the method `ink_general_heading`, which renders the document title.
+Since this method is also responsible for rendering other headings (e.g. section titles), we allow it fall back to the default implementation unless it is processing the document title of an article.
 
-.Extended converter with author, date and revision remark below the document title of document types without a title page
+.Extended converter that renders the document details below the document title of an article
 [,ruby]
 ----
 include::example$pdf-converter-article-title-with-author-and-date.rb[]
 ----
 <.> Fall back to default implementation unless handling the document title.
 <.> Render the document title.
 See the definition of `ink_document_title` for details.
-<.> Render author, date and revision remark, if they're available.
+<.> Render the author, date, and revision information, if available.
 See the definition of `ink_document_details` for details.
-<.> Render a vertical gap between the title section (incl. author, date and revision remark) and the body of the document.
-<.> The revision remark isn't available as a field of `doc`, so we have to retrieve it using the method `doc.attr` instead.
-Because we'll use the revision remark multiple times, we store it in a local variable.
-<.> Only include the additional line if there's actually content for it, so we don't end up with unused vertical space.
-<.> Render a vertical gap between the document title and the line with author, date and revision remark if the theme sets a size of that gap.
-Otherwise, fall back to a zero-height "`gap`".
-<.> When we get here, a heading-specific style will already be set.
-(This is ensured by the methods that call `ink_general_heading`.)
-As we don't want author, date and revision remark to look like a heading, we first have to reset to the default style using the `:base` category.
-Then, we can apply the `heading_h1_details` category.
-<.> An em-dash to be put between author and date, but only if both aren't empty.
-<.> A vertical bar to be put before the revision remark, but only if it isn't empty and there's actually something else (author, date or both) in front of it.
-<.> Put author, date, revision remark and the separators together using Ruby string interpolation and render the resulting string.
+<.> Render a vertical gap between the header and body of the document.
+<.> The revnumber isn't available as a field of `doc`, so we have to retrieve it using the method `doc.attr` instead.
+Because we'll use the revnumber multiple times, we store it in a local variable.
+<.> Only include the additional line if there's actually content for it so we don't end up with unused vertical space.
+<.> Insert a vertical gap between the document title and the line with author, date, and revision information if the theme sets a size of that gap.
+Otherwise, don't insert a gap.
+<.> When we get here, a heading-specific style will already be set by the code that calls `ink_general_heading`.
+Since we don't want the document details to use the heading font, we first have to revert to the base font using the `:base` category.
+Then, we can apply the `heading_h1_details` category from the theme.
+<.> Build the revision information if the revnumber is set.
+If a revmark is specified, add it after the revnumber, separating the two by a vertical bar.
+<.> An em dash is put before the between author and date, but only if either are set.
+<.> An em dash is put before the revision, but only if it isn't empty and there's content in front of it.
+<.> Put the author, date, and revision information and their separators together using Ruby string interpolation and render the resulting string.
 
 == Custom part title