RubyGems - asciidoctor-rhrev - Versions diffs - 1.0.1 → 1.2.0 - Mend

asciidoctor-rhrev 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

checksums.yaml +4 -4
data/CHANGELOG.adoc +5 -0
data/README.adoc +11 -67
data/USAGE.adoc +4 -643
data/lib/asciidoctor/rhrev/change_bars.rb +147 -0
data/lib/asciidoctor/rhrev/converter.rb +51 -20
data/lib/asciidoctor/rhrev/rhrev_html.rb +13 -13
metadata +2 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1c1b7deda1e8161597bdc0ce03b140c59c38316210828ee0bd3fb3f7fdc2aba
-  data.tar.gz: a39f100dcbb08ad20c297b0c0eef9676db5d0420ea8a54e5e562c4667c152245
+  metadata.gz: ba4b787b526a584c23e8d5c890cfc0459711552efb13b11e483b2847706f018e
+  data.tar.gz: 5e740bd4af7144bcc3ad461ddadfc402883354395f372c1336439e87d498547f
 SHA512:
-  metadata.gz: 6eb46d1c65c0d87b0313ba8e4dc302fe26f1f546bf45af94d8e667262484e78065c2b1a138a3d8024d7360eb1f00066a0293eabe89c3186f58c4bf68174de917
-  data.tar.gz: 87e3db66058d9f5a0c5a271494aaf3aa5df90554f7c887d366078bfa8a276cbc8fc8a1284fcb64cf5780de38acb430e98b4d993ea13134f6b02547d90c1e8c1c
+  metadata.gz: 9ad667cf9c86e5462ca177eae98fddad13335354c26083fb15cfe5639630b7044e0e623b7e5b1f5f069fe4689403e6c382246db47c7127aafe89d2f1fa204853
+  data.tar.gz: fca906ea2b5256d3d141828ee39ef3298fb9420dbea437f424e6cac633035e8dec6463ca2bdd30c76d86c73e08125bb7620c94fdff4015970cc9b65fa837f764

data/CHANGELOG.adoc CHANGED Viewed

@@ -1,5 +1,10 @@
 = Changelog
+== 1.2.0 (2026-07-07)
+* Fix document-level `-all`/`-cover` entries being ignored for revisions with more than two segments (e.g. `1-2-0`): revisions are now discovered from `*-prevrev` attributes instead of enumerating `major-minor` pairs (PDF and HTML backends)
+* Add PDF change bars: with `:rhrev-change-bars:` set, a vertical bar is inked in the page margin next to every tracked block (section, floating title, example, listing, table, image) marked with the current revision (`revnumber` 1.2 → `rhrev1-2`). Styled via the `rhrev_change_bars` PDF theme category — `color` (default `FF0000`), `width` (default `2`), `offset` (default `16`), and `side` (`outer`/`inner`/`left`/`right`; defaults to `outer` for prepress media, `right` otherwise) — overridable per document with the matching `rhrev-change-bars-*` attributes
 == 1.0.1 (2026-05-15)
 * Fix `convert_section` method signature to accept optional `opts` keyword arguments for compatibility with converters that pass them

data/README.adoc CHANGED Viewed

@@ -2,7 +2,9 @@
 rhrev is a comprehensive revision history tracking system for the AsciiDoc and Antora ecosystems which automatically creates a grouped, formatted table of document changes.
-It supports several converters/backends:
+https://baiyibai-antora.gitlab.io
+== Supported Backends
 * asciidoctor-pdf
 +
@@ -19,18 +21,11 @@ image::resources/nodejs-html5-output.png[width=50%]
 +
 * Antora-Assembler to asciidoctor-pdf
-== Features
+include::doc/modules/ROOT/pages/introduction.adoc[tag=why]
+include::doc/modules/ROOT/pages/introduction.adoc[tag=features]
-* *Automatic revision tracking* with version-based grouping
-* *Dynamic version labels* using `:version-label:` attribute
-* *Localization support* for multiple languages
-* *Export to AsciiDoc* for inclusion in other documents
-* *Flexible placement* (auto or manual via macro)
-* *Extensive customization* options for styling and formatting
-* [PDF] *Clickable page references* that link to actual document locations
-* [PDF] *Flexible xrefstyle support* (full, short, basic) for all block types
-* [PDF] *Custom captions* for Examples, Tables, Listings, and Figures
-* *FAST*
+include::doc/modules/ROOT/pages/introduction.adoc[tag=quick-start]
 == Inspiration
@@ -42,62 +37,11 @@ This extension draws inspiration from:
 The goal was to bring similar automated revision tracking capabilities to the Asciidoctor ecosystem, with the added benefit of clickable page references and flexible customization options tailored for PDF technical documentation.
-== Quick Start
-=== Installation
-The asciidoctor-pdf-rhrev extension is available as a Ruby Gem.
-https://rubygems.org/gems/asciidoctor-pdf-rhrev[^]
-Complete these steps to use:
-. Install the required Gems:
-+
-[source,bash]
-----
-gem install asciidoctor
-gem install asciidoctor-pdf
-gem install asciidoctor-pdf-rhrev
-----
-+
-. Render your document:
-+
-[source,bash]
-----
-asciidoctor-pdf -r asciidoctor-pdf-rhrev document.adoc
-----
-=== Basic Usage
-[source,asciidoc]
-----
-= My Document
-:doctype: book
-:revnumber: 1.1
-:rhrev:
-:version-label: Version
-// 1.0 Metadata
-:1-1-prevrev: 1.0
-:1-1-prevrevdate: 2024-02-01
-:rhrev1-1-all: Feature update
-[rhrev1-1="Updated introduction"]
-== Introduction
-Content here...
-----
 == Documentation
-See link:USAGE.adoc[] for complete documentation including:
+Full documentation is published at https://baiyibai-antora.gitlab.io.
-* Configuration options
-* Advanced features
-* Localization
-* Export functionality
-* xrefstyle support
-* Examples and use cases
+For configuration details, see link:doc/modules/ROOT/pages/usage.adoc[].
 == Testing
@@ -114,7 +58,7 @@ This will generate PDFs for all test cases in the `tests/` directory.
 [source,bash]
 ----
-gem build asciidoctor-pdf-rhrev.gemspec
+gem build asciidoctor-pdf-rhrev.gemspec
 gem install ./asciidoctor-pdf-rhrev-1.0.0.gem
 ----
@@ -128,7 +72,7 @@ Contributions welcome! Please ensure all tests pass before submitting changes.
 == Copyright
-Copyright (C) 2025-present 白一百 baiyibai
+Copyright (C) 2025-present 白一百 baiyibai
 * The image _The «Public Domain Mark» icon from Creative Commons with transparent background._ is in the public domain and taken from: +
 https://commons.wikimedia.org/wiki/File:Cc-public_domain_mark.svg[^]

data/USAGE.adoc CHANGED Viewed

@@ -5,649 +5,10 @@ A comprehensive revision history tracking system for AsciiDoctor and Antora that
 toc::[]
-== Key Features
+include::doc/modules/ROOT/pages/introduction.adoc[tag=why]
+include::doc/modules/ROOT/pages/introduction.adoc[tag=features]
-* [x] *Revision Grouping* +
-Organize changes by revision number (1-1, 1-2, 2-1, etc.)
-* [x] *AST Pre-scanning* +
-Collects entries before rendering (like ToC) for accurate page allocation
-* [x] *Automatic Page Allocation* +
-Properly allocates multi-page tables without overprinting
-* [x] *Clickable Page Numbers* +
-Page numbers link directly to changed content
-* [x] *Bullet Point Lists* +
-Changes formatted as proper bullet lists with nesting
-* [x] *Bold Headers* +
-"Major changes since..." headers are bold and clear
-* [x] *Document-Level Entries* +
-Special "all" and "cover" page entries
-* [x] *Block-Level Tracking* +
-Sections, examples, listings, tables, and figures
-* [x] *Multiple Placement Options* +
-Auto placement or manual with `rhrev::[]` macro
-* [x] *Flexible Display* +
-Render as section or standalone table
-* [x] *Table Styling* +
-Control frame, grid, stripes, alignment, and caption
-* [x] *Localization* +
-Customize all labels and text
-* [x] *Export to .adoc* +
-Export revision history to separate file
-* [x] *Pre/Post Content* +
-Add custom content before/after the table
-* [x] *TOC-like Syntax* +
-Use `:rhrev: macro` just like `:toc: macro`
+include::doc/modules/ROOT/pages/introduction.adoc[tag=quick-start]
-== Basic Usage
-[source,asciidoc]
-----
-= My Document
-:doctype: book
-:rhrev:
-----
-=== Define Revision Metadata
-[source,asciidoc]
-----
-// Revision 1.1 metadata
-:1-1-prevrev: 1.0
-:1-1-prevrevdate: 2024-01-01
-:rhrev1-1-all: * Initial document structure * Added core sections * Setup formatting
-:rhrev1-1-cover: * Updated cover design * New logo
-----
-[IMPORTANT]
-*All revision attributes must be defined in the document header* - before the first blank line after the document title.
-Asciidoctor only loads attributes from the header section.
-Attributes that are placed after a blank line do not appear in the revision history.
-.Correct ✅
-[source,asciidoc]
-----
-= My Document
-:doctype: book
-:rhrev:
-:version-label: Version
-// Revision 1.0 metadata
-:1-1-prevrev: 1.0
-:1-1-prevrevdate: 2024-01-01
-:rhrev1-1-all: Initial release
-== Chapter One
-----
-.Incorrect ❌
-[source,asciidoc]
-----
-= My Document
-:doctype: book
-:rhrev:
-:version-label: Version
-// ❌ This blank line ends the header!
-:1-1-prevrev: 1.0              // ❌ These attributes will be IGNORED
-:rhrev1-1-all: Initial release // ❌ They won't appear in output
-== Chapter One
-----
-Pro Tip:: Use comments like `// Revision 1.0 metadata` between revision groups instead of blank lines to keep everything in the header while maintaining readability.
-=== Mark Content Blocks
-[source,asciidoc]
-----
-[rhrev1-1="Created introduction section * Added
-overview"]
-== Introduction
-Content here...
-[rhrev1-1="Added installation guide * Included prerequisites"]
-[rhrev1-2="Re-ordered the installation steps * Added overview"]
-== Getting Started
-More content...
-----
-That's it! The extension performs several actions:
-. Pre-scans the document AST to collect all revision entries
-. Allocates proper space for the revision history table
-. Renders content normally and capture page numbers
-. Fills in the revision history table with actual data and clickable links
-== Understanding Revisions
-Revisions use a hierarchical numbering system: `major-minor` (e.g., 1-1, 1-2, 2-1).
-Each revision groups changes into:
-Document-level "all" entry:: Overall changes for the entire document
-Document-level "cover" entry:: Cover page changes (PDF only, not in HTML)
-Block-level entries:: Specific changes to sections, examples, etc.
-== Configuration Attributes
-The extension is highly-configurable.
-.Core Settings
-[%header,cols="25,75"]
-|===
-|Attribute
-|Description
-|`:rhrev:`
-|Enable the feature
-|`:rhrev: macro`
-|Enable with macro placement, +
-similar to the +
-`:toc: macro` +
-`toc::[]`
-|`:rhrev-block-type:`
-a|
-* `section` (default)
-* `table`
-|`:rhrev-discrete:`
-|Exclude from the Table of Contents +
-(`:rhrev-block-type: section` only)
-|`:rhrev-suppress-new-page-after:`
-a|Suppress automatic new page after revision history table +
-* Allows content to continue on the same page.
-|`:rhrev-disable-caption:`
-a|
-* Disable "Table N." caption prefix
-|`:rhrev-table-caption: <Custom Caption>`
-|Custom table caption text
-|`:rhrev-description-xrefstyle: basic`
-a|Sets the `xrefstyle` inside the description column.
-* `full`
-* `short`
-* `basic`
-* `short basic` +
-Like `full`, but without comma, italics, or bold styling.
-|`:rhrev-customization-xrefstyleshort-remove-trailling-period:`
-|Removes the trailing period from xrefstyleshort.
-|`:rhrev-initial-handling:`
-a|Controls behavior when revnumber is 1.0 or 1
-* `initial-release` (default) - Renders simplified table with "Initial release" text
-* `skip` - Completely skip revision history rendering
-* `normal` - Render normally even for version 1.0
-|`:rhrev-customization-title:`
-a|Custom title for revision history section +
-Default: "{version-label} History" +
-Set to empty string to suppress title
-|===
-.Localization and Customization
-[%header,cols="25,75"]
-|===
-|Attribute
-|Default
-|`:rhrev-table-caption:`
-|Custom Caption
-|`:rhrev-localization-page:`
-|Page
-|`:rhrev-localization-major-changes:`
-|Major changes since
-|`:rhrev-localization-all:`
-|All
-|`:rhrev-localization-cover:`
-|Cover
-|`:rhrev-localization-initial-release:`
-|Initial release
-|`:rhrev-customization-prevrev-include-date:`
-a|Include date in revision headers +
-When set, date appears after revision: "Version 1.0 2024-01-15" +
-When unset, only version: "Version 1.0" (default)
-|`:rhrev-customization-date-format:`
-|Date format string for prevrev dates +
-Default: %Y-%m-%d +
-Example: %B %d, %Y → January 15, 2025
-|`:rhrev-customization-initial-release-text:`
-|Text to display for initial release (v1.0) +
-Default: Initial Release
-|===
-.Advanced Options
-[%header,cols="25,75"]
-|===
-|Attribute
-|Description
-|`:revhistoryprefix:`
-a|Override the default attribute prefix +
-Default: rhrev +
-Example: `:revhistoryprefix: rev` changes `rhrev1-1` to `rev1-1`
-[WARNING]
-Changing this value may have adverse effects.
-|`:rhrev-customization-description-format:`
-a|Control what appears in description column +
-Options:
-* `xref,desc` (default) - Show xref and description
-* `xref` - Show only xref
-* `desc` - Show only description
-|`:rhrev-debug:`
-|Enable debug logging for troubleshooting +
-Outputs to stderr or logger
-|===
-.Table Styling
-[%header,cols="25,75"]
-|===
-|Attribute
-|Default
-|`:rhrev-table-column-width:`
-|30,70
-|`:rhrev-table-frame:`
-a|Table frame styling
-* all
-* sides
-* ends
-* none
-|`:rhrev-table-grid:`
-a|Table grid styling
-* all
-* rows
-* cols
-* none
-|`:rhrev-table-stripes:`
-a|Table stripe styling
-* even
-* odd
-* none
-|`:rhrev-table-stripes-color:`
-a|Table stripe color
-* Hex color for stripes (default: 'EEEEEE')
-|`:rhrev-table-extra-blank-row:`
-a|Add blank row at end of table +
-(Uses non-breaking spaces for proper height)
-|===
-The <<table-inserted-row>> attributes allow the author to insert a custom row into the table.
-All support full AsciiDoc markup (bold, italic, admonitions, lists, etc.)
-NOTE: Custom first row is supported in both embedded output and exported .adoc files.
-[#table-inserted-row]
-.Inserted Row
-[%header,cols="25,75"]
-|===
-|Attribute
-|Default
-|`:rhrev-customization-first-row:`
-|Content to add to the first row which spans both columns
-|`:rhrev-customization-first-row-left:`
-|Content for left cell of first row
-|`:rhrev-customization-first-row-right:`
-|Content for right cell of first row
-|`:rhrev-export-to-file:`
-|Enable export to .adoc file
-|`:rhrev-adoc-output:`
-|Output filename +
-default: revhistory.adoc
-|`:rhrev-export-format:`
-a|Export format:
-* 'xref' (default) - exports with the `xref:anchor[page]` macro in the left column
-* 'pagerhref' - exports with the `pagerhref:anchor[]` macro in the left column
-NOTE: Antora Assembler beta.15 xref format (`xref:file/path:::anchor[]`) xrefs are automatically converted to standard format (`xref:filename.adoc#anchor[]`) during export
-|===
-=== Theme Support
-rhrev supports three asciidoctor theme keys for styling output:
-* `rhrevpage`
-* `rhrevdescription`
-* `pagerhref`
-== Initial Release Handling
-When `:revnumber:` is set to `1.0` or `1`, the extension provides special handling:
-.Default Behavior (`:rhrev-initial-handling: initial-release`)
-Renders a simplified table with "Initial release" text instead of showing empty revision history.
-[source,asciidoc]
-----
-= My Document
-:revnumber: 1.0
-:rhrev:
-:rhrev-initial-handling: initial-release
-----
-This produces a clean table showing:
-[cols="30,70"]
-|===
-a|*Page* | a|*Initial release*
-| {nbsp} | {nbsp}
-|===
-.Skip Rendering (`:rhrev-initial-handling: skip`)
-Completely skip revision history rendering for initial release.
-Use `:rhrev: macro` to avoid a blank page being inserted at the beginning of the document.
-[source,asciidoc]
-----
-:revnumber: 1.0
-:rhrev: macro
-:rhrev-initial-handling: skip
-----
-.Normal Rendering (`:rhrev-initial-handling: normal`)
-Render revision history normally even for version 1.0:
-[source,asciidoc]
-----
-:revnumber: 1.0
-:rhrev:
-:rhrev-initial-handling: normal
-:1-0-prevrev: 0.9
-:rhrev1-0-all: First stable release
-----
-== Manual Mode (`:rhrev: manual`)
-Manual mode allows authors to hand-craft revision history tables, while still leveraging the rhrev extension's anchor cataloging functionality.
-This allows authors to use the `pagerhref` macro to resolve page numbers, which eliminates the need to manually track page numbers.
-Use manual mode when these requirements are needed:
-* *Full control* over table structure and formatting
-* *Custom grouping* of changes by version/date
-* *Flexible layout* not constrained by auto-generation
-* *Clickable page number links* via `pagerhref` macro
-What it does not do:
-* Does *NOT* build a revision history table
-* Does *NOT* collect or process revision attributes
-* Does *NOT* create automatic revision entries
-=== Usage Example
-[source,asciidoc]
-----
-= My Document
-:doctype: book
-:rhrev: manual
-== Revision History
-.Version History
-[cols="1,3"]
-|===
-|Page
-|Changes
-a|pagerhref:_introduction[]
-a| xref:_introduction[Introduction]
-* Created new section
-a|pagerhref:_features[]
-a|xref:_features[Features]
-* Added advanced features
-|===
-== Introduction
-Content here...
-== Features
-More content...
-----
-=== How pagerhref Works
-The `pagerhref:anchor[]` macro uses *deferred rendering* to resolve both forward and backward references:
-1. *First Pass*: Tables with `pagerhref` macros are measured and space is allocated
-2. *Cataloging*: All sections/blocks with anchors are cataloged with their page numbers during rendering
-3. *Re-rendering*: After document rendering completes, tables are re-rendered with actual page numbers
-4. *Result*: Clickable page number links that work for all references
-=== Benefits vs. Auto Mode
-[cols="1,2,2"]
-|===
-| Aspect | Auto Mode | Manual Mode
-| Table Generation
-| Automatic
-| Hand-crafted
-| Flexibility
-| Structured format
-| Complete control
-| Page Links
-| Automatic
-| Via `pagerhref` macro
-| Best For
-| Standard revision tracking
-| Custom layouts, specific requirements
-|===
-== Usage Examples
-Refer to the /tests folder to see real examples.
-== Troubleshooting
-* Page numbers show as "???"
-** Ensure images resolve
-* Bullets render as asterisks
-** Check for syntax errors in bullet formatting
-** Ensure asterisks have spaces: `* item` not `*item`
-** Nested bullets need multiple asterisks: `** nested`
-== Antora Assembler (PDF Extension) Compatibility and Configuration
-Using the rhrev extension with either the default embedded, `rhrev: ''` or `macro` mode requires no additional configuration.
-Using  `rhrev: manual` mode with content which contains the `rhrev-export-format: pagerhref` requires additional steps:
-. [`antora-assembler.yml`] Add the rhrev extension as the last item (`-r `) in the `build/command`. +
-This is required to ensure the extension overrides the table rendering so that it can provide page numbers to the catalog.
-. [`antora-playbook.yml`] Add the Antora-Assembler `antora-rhrev-assembler-pagerhref.js` script to the `antora/extensions` section. +
-This extension overwrites the pagerhref macros in exported in the assembly file to allow page lookup in the catalog.
-The recommended approach is to add some rhrev entires in the document, export the revision history to an .adoc file, and then examine it to see how to copy and re-import the content.
-== Antora Usage
-Until the extension is available on npm or yarn, the extensions must be manually configured in the `antora-playbook.yml` file.
-. Add these lines to the  `antora-playbook.yml`:
-+
-[source,yaml]
-----
-asciidoc:
-  extensions:
-    - ./antora-extension/antora-rhrev-asciidoc.js
-antora:
-  extensions:
-  - '@antora/pdf-extension'
-  # Select only one
-  - require: ./antora-extension/antora-rhrev-html.js
-  - require: ./antora-extension/antora-rhrev-placeholder.js
-  # Required if using rhrev: manual w/pagerhref macros:
-  - require: ./antora-extension/antora-rhrev-assembler-pagerhref.js
-----
-+
-. Add the desired configuration settings into the appropriate .yml file; antora-assembler.yml for PDF and antora-playbook.yml for HTML.
-. For best results, use the `rhrev: macro` attribute in the document.
-== The Tao of Revision History
-=== Writing Good Revision Descriptions
-A good revision history is not a list of "updated" and "fixed bugs."
-It's a narrative that respects the reader's time and helps them understand what changed without comparing two versions.
-. Use simple past tense verbs with specificity
-** [x] "Added OAuth 2.0 authentication"
-** [x] "Changed timeout from 30s to 60s"
-** [x] "Removed deprecated API endpoints"
-** ❌ "Updated authentication"
-** ❌ "Fixed issues"
-** ❌ "Improvements made"
-. Describe the transition (from → to):
-** [x] "Changed default port from 8080 to 3000"
-** [x] "Renamed 'config.yaml' to 'settings.yaml'
-** ❌ "Port updated"
-** ❌ "Config file changed"
-. Keep simple styling and avoid too many hyperlinks.
-. Keep changes next to the context.
-=== Why Use Block Attributes?
-When placed `[rhrev1-2="Added validation"]` directly on a section about user input, the editor immediately knows WHAT was validated and WHERE. This is better than a separate changelog that says "Added validation" with no context.
-The problem with separate changelogs::
-* The author must remember what changed
-* The reader must hunt through document to find the change
-* Vague entries like "updated section 3.2" are useless
-* Maintaining two files is error-prone
-The solution with inline attributes::
-* The change description is right at the change location
-* This forces author to think about the change while making it
-* The reader gets a descriptive preview of the change in advance
-* There is a single source of truth
-== The Frustration This Avoids
-When maintaining a 200-page technical manual, tracking changes in a separate file becomes a nightmare:
-* "Which section did I update?"
-* "Was it the API reference or the examples?"
-* "What exactly changed in chapter 5?"
-With inline `[rhrev]` attributes, the change description lives with the change.
-=== Document-Level vs Block-Level Entries
-Document-level "all" Entries::
-* Structural changes (added new chapter, reorganized sections)
-* Format updates (changed heading styles, updated templates)
-* Global find-replace operations
-* Overall improvements that touch many places
-Block-level Entries:::
-* Specific content changes (added example, updated diagram)
-* Localized fixes (corrected formula, fixed typo)
-* New content (added section on X)
-* Targeted updates (revised explanation of Y)
-=== The Asterisk System
-Asterisks create hierarchy in the changes:
-[source,asciidoc]
-----
-:rhrev1-2-all: Added security chapter * Authentication ** OAuth 2.0 ** API keys * Authorization ** Role-based access ** Permissions
-----
-This renders as:
-* Added security chapter
-* Authentication
-** OAuth 2.0
-** API keys
-* Authorization
-** Role-based access
-** Permissions
-One bullet per change, subbullets for more detail
-=== Minimal Styling is Better
-Revision histories should be scannable, not distracting:
-* Plain text is best for change descriptions
-* Bold headers (automatic) help separate revisions
-* Bullet points (automatic) organize changes
-* Clickable page numbers (automatic) for navigation
-* That's it. No colors, no icons, no fancy formatting.
-The goal is clarity, not decoration. Your readers are looking for information, not entertainment.
-=== Teaching Better Documentation
-This extension teaches authors to think more deeply about their changes:
-* What exactly changed?
-* Why did it change?
-* How would I explain this to someone who doesn't have the previous version?
-This discipline improves documentation quality overall.
+include::doc/modules/ROOT/pages/usage.adoc[tag=content]

data/lib/asciidoctor/rhrev/change_bars.rb ADDED Viewed

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+module Asciidoctor
+  module PDF
+    module Rhrev
+      # Inks a vertical change bar in the page margin next to blocks marked
+      # with the current revision (revnumber 1.2 => attribute rhrev1-2).
+      # Enabled by the rhrev-change-bars document attribute.
+      #
+      # Styling comes from the PDF theme by default (rhrev_change_bars category:
+      # color, width, offset, side), overridable per document via the
+      # rhrev-change-bars-color/-width/-offset/-side attributes.
+      module ChangeBars
+        def init_change_bars doc
+          @change_bar_attr = nil
+          @change_bar_settings = nil
+          return unless doc.attr? 'rhrev-change-bars'
+          # Without a revnumber there is no "current" revision to match
+          return unless (revnumber = doc.attr 'revnumber')
+          @change_bar_attr = %(#{@revision_prefix}#{revnumber.to_s.tr '.', '-'})
+          # Capture attribute values only; holding the Document in an ivar here
+          # would leak it into the scratch prototype, which must stay marshalable
+          @change_bar_overrides = {
+            color: (doc.attr 'rhrev-change-bars-color'),
+            width: (doc.attr 'rhrev-change-bars-width'),
+            offset: (doc.attr 'rhrev-change-bars-offset'),
+            side: (doc.attr 'rhrev-change-bars-side'),
+          }
+          @change_bar_starts = {}
+        end
+        # Resolved lazily on first ink: the theme (and @media/@folio_placement)
+        # are not loaded yet when init_change_bars runs; upstream
+        # convert_document sets them up after rhrev's pre-super initialization.
+        # Precedence: document attribute > theme key > built-in default.
+        def change_bar_settings
+          @change_bar_settings ||= begin
+            overrides = @change_bar_overrides || {}
+            theme = @theme
+            side = overrides[:side] || theme&.rhrev_change_bars_side ||
+              (@media == 'prepress' ? 'outer' : 'right')
+            {
+              color: (overrides[:color] || theme&.rhrev_change_bars_color || 'FF0000').to_s.delete_prefix('#').upcase,
+              width: (overrides[:width] || theme&.rhrev_change_bars_width || 2).to_f,
+              offset: (overrides[:offset] || theme&.rhrev_change_bars_offset || 16).to_f,
+              side: side.to_s,
+            }
+          end
+        end
+        def change_bar? node
+          @change_bar_attr && node.respond_to?(:attributes) &&
+            node.attributes && (node.attributes.key? @change_bar_attr)
+        end
+        def record_change_bar_start node
+          @change_bar_starts[node] = { page: page_number, cursor: cursor }
+        end
+        def take_change_bar_start node
+          @change_bar_starts&.delete node
+        end
+        # The offset measures the gap between the text edge and the near edge
+        # of the bar. Sides recto/verso are determined by the physical page
+        # number (honoring pdf-folio-placement inversion), matching prepress
+        # physical folio placement.
+        def change_bar_x pgnum, settings
+          case settings[:side]
+          when 'right'
+            on_right = true
+          when 'outer', 'inner'
+            recto = (page_side pgnum, @folio_placement && @folio_placement[:inverted]) == :recto
+            on_right = settings[:side] == 'outer' ? recto : !recto
+          end
+          on_right ? bounds.right + settings[:offset] : bounds.left - settings[:offset] - settings[:width]
+        end
+        # Paints the bar page by page; from/to are { page:, cursor: }.
+        # Called immediately after the block is rendered, so all spanned pages exist.
+        def ink_change_bar from, to
+          return if scratch? || from.nil? || to.nil?
+          return if to[:page] < from[:page]
+          return if to[:page] == from[:page] && to[:cursor] >= from[:cursor]
+          settings = change_bar_settings
+          float do
+            (from[:page]..to[:page]).each do |pgnum|
+              go_to_page pgnum unless page_number == pgnum
+              top = pgnum == from[:page] ? from[:cursor] : bounds.top
+              bottom = pgnum == to[:page] ? to[:cursor] : 0
+              next if (height = top - bottom) <= 0
+              bounding_box [(change_bar_x pgnum, settings), top], width: settings[:width], height: height do
+                fill_bounds settings[:color]
+              end
+            end
+          end
+        end
+        def ink_change_bar_for_extent extent
+          return unless extent
+          ink_change_bar({ page: extent.from.page, cursor: extent.from.cursor },
+            { page: extent.to.page, cursor: extent.to.cursor })
+        end
+        # Examples and listings are arranged blocks: the extent yielded here is
+        # exact across page breaks. Tables and images never reach this hook with
+        # their own node, so they are handled in the converter overrides instead.
+        def arrange_block node, &block
+          if @change_bar_attr && !scratch? &&
+              (node.context == :example || node.context == :listing) && (change_bar? node)
+            super node do |extent|
+              if scratch?
+                # measurement pass: upstream instance_execs this wrapper on the scratch
+                # document, so re-bind the original block to it the same way
+                instance_exec(&block)
+              else
+                block.call extent
+                ink_change_bar_for_extent extent
+              end
+            end
+          else
+            super
+          end
+        end
+        # The heading ink methods run after arrange_heading / start_new_chapter
+        # have settled the page, so this is the first accurate start position.
+        def ink_general_heading node, title, opts = {}
+          record_change_bar_start node if @change_bar_attr && !scratch? && (change_bar? node)
+          super
+        end
+        def ink_chapter_title node, title, opts = {}
+          record_change_bar_start node if @change_bar_attr && !scratch? && (change_bar? node)
+          super
+        end
+        # Upstream defines ink_part_title as an alias copy of ink_chapter_title,
+        # so it must be overridden separately
+        def ink_part_title node, title, opts = {}
+          record_change_bar_start node if @change_bar_attr && !scratch? && (change_bar? node)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/rhrev/converter.rb CHANGED Viewed

@@ -5,6 +5,7 @@ require_relative 'catalog'
 require_relative 'renderer'
 require_relative 'exporter'
 require_relative 'processors'
+require_relative 'change_bars'
 module Asciidoctor
   module PDF
@@ -19,6 +20,7 @@ module Asciidoctor
         include Helpers
         include Renderer
         include Exporter
+        include ChangeBars
         def initialize *args
           super
@@ -37,7 +39,8 @@ module Asciidoctor
         def convert_document node
           @revision_prefix = node.attr 'revhistoryprefix', 'rhrev'
+          init_change_bars node
           # Check if we're in manual mode (pagerhref support needed)
           @manual_mode = node.attr('rhrev') == 'manual'
@@ -86,8 +89,13 @@ module Asciidoctor
             # Link destination to page for revision history
             revision_history.link_dest_to_page node.id, page_number, 1, y: cursor
           end
-          super
+          result = super
+          # Start position was captured at heading-ink time (after any page advance)
+          if @change_bar_attr && !scratch? && (start_pos = take_change_bar_start node)
+            ink_change_bar start_pos, { page: page_number, cursor: cursor }
+          end
+          result
         end
         def convert_table node
@@ -112,8 +120,17 @@ module Asciidoctor
           if has_pagerhref
             allocate_pagerhref_table_extent node
           else
+            # Skip recording when the upstream table-container rewrap will trigger
+            # (condition replicated from asciidoctor-pdf convert_table); the
+            # re-entrant conversion of the attribute-preserving dup records instead
+            if @change_bar_attr && !scratch? && (change_bar? node) &&
+                !(!at_page_top? && ((node.option? 'unbreakable') ||
+                  ((node.option? 'breakable') && (node.id || node.title?))))
+              bar_from = { page: page_number, cursor: cursor }
+            end
             result = super
             catalog_block_anchor node
+            ink_change_bar bar_from, { page: page_number, cursor: cursor } if bar_from
             result
           end
         end
@@ -122,8 +139,19 @@ module Asciidoctor
           # Skip collect during render if prescan already did it
           collect_revision_entries node unless @prescan_complete
           update_revision_entry_metadata node
+          # PDF targets import whole pages; there is no cursor flow to mark
+          if @change_bar_attr && !scratch? && (change_bar? node) &&
+              !((node.attr 'target').to_s.downcase.end_with? '.pdf')
+            bar_from = { page: page_number, cursor: cursor }
+          end
           result = super
           catalog_block_anchor node
+          if bar_from
+            bar_to = { page: page_number, cursor: cursor }
+            # Images never split; a page change means the image moved wholesale
+            bar_from = { page: bar_to[:page], cursor: bounds.top } if bar_to[:page] > bar_from[:page]
+            ink_change_bar bar_from, bar_to
+          end
           result
         end
@@ -151,6 +179,9 @@ module Asciidoctor
           update_revision_entry_metadata node
           result = super
           catalog_block_anchor node
+          if @change_bar_attr && !scratch? && (start_pos = take_change_bar_start node)
+            ink_change_bar start_pos, { page: page_number, cursor: cursor }
+          end
           result
         end
@@ -390,23 +421,23 @@ module Asciidoctor
         def collect_document_level_entries doc
           return if @document_entries_collected
           @document_entries_collected = true
-          (0..9).each do |major|
-            (0..9).each do |minor|
-              revision = "#{major}-#{minor}"
-              prevrev_attr = "#{revision}-prevrev"
-              if doc.attr(prevrev_attr)
-                all_attr_name = "#{@revision_prefix}#{revision}-all"
-                if (all_value = doc.attr(all_attr_name))
-                  revision_history.add_all_entry revision, all_value
-                end
-                cover_attr_name = "#{@revision_prefix}#{revision}-cover"
-                if (cover_value = doc.attr(cover_attr_name))
-                  revision_history.add_cover_entry revision, cover_value
-                end
-              end
+          # Discover revisions from *-prevrev attributes so any number of
+          # segments works (1-1, 1-2-0, ...), not just major-minor
+          doc.attributes.each_key do |key|
+            key_str = key.to_s
+            next unless key_str.end_with?('-prevrev')
+            revision = key_str.delete_suffix('-prevrev')
+            next unless revision.match?(/\A\d+(?:-\d+)*\z/)
+            all_attr_name = "#{@revision_prefix}#{revision}-all"
+            if (all_value = doc.attr(all_attr_name))
+              revision_history.add_all_entry revision, all_value
+            end
+            cover_attr_name = "#{@revision_prefix}#{revision}-cover"
+            if (cover_value = doc.attr(cover_attr_name))
+              revision_history.add_cover_entry revision, cover_value
             end
           end
         end

data/lib/asciidoctor/rhrev/rhrev_html.rb CHANGED Viewed

@@ -155,20 +155,20 @@ module Asciidoctor
         prefix = doc.attr 'revhistoryprefix', 'rhrev'
         # Collect document-level entries (-all)
-        (0..9).each do |major|
-          (0..9).each do |minor|
-            revision = "#{major}-#{minor}"
-            prevrev_attr = "#{revision}-prevrev"
-            if doc.attr(prevrev_attr)
-              all_attr_name = "#{prefix}#{revision}-all"
-              if (all_value = doc.attr(all_attr_name))
-                catalog.add_all_entry revision, all_value
-              end
-              # Skip -cover entries for HTML
-            end
+        # Discover revisions from *-prevrev attributes so any number of
+        # segments works (1-1, 1-2-0, ...), not just major-minor
+        doc.attributes.each_key do |key|
+          key_str = key.to_s
+          next unless key_str.end_with?('-prevrev')
+          revision = key_str.delete_suffix('-prevrev')
+          next unless revision.match?(/\A\d+(?:-\d+)*\z/)
+          all_attr_name = "#{prefix}#{revision}-all"
+          if (all_value = doc.attr(all_attr_name))
+            catalog.add_all_entry revision, all_value
           end
+          # Skip -cover entries for HTML
         end
         # Collect block-level entries by scanning document

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-rhrev
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - 白一百 baiyibai
@@ -38,6 +38,7 @@ files:
 - lib/asciidoctor-rhrev.rb
 - lib/asciidoctor/rhrev.rb
 - lib/asciidoctor/rhrev/catalog.rb
+- lib/asciidoctor/rhrev/change_bars.rb
 - lib/asciidoctor/rhrev/converter.rb
 - lib/asciidoctor/rhrev/exporter.rb
 - lib/asciidoctor/rhrev/helpers.rb