asciidoctor-rhrev 1.0.0

data/USAGE.adoc

@@ -0,0 +1,653 @@
+= rhrev Asciidoctor Revision History Extension
+:toc: macro
+
+A comprehensive revision history tracking system for AsciiDoctor and Antora that automatically creates a grouped, formatted table of document changes with clickable page numbers.
+
+toc::[]
+
+== Key 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`
+
+== 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.