asciidoctor-rhrev 1.0.1 → 1.2.0

package/README.adoc

@@ -4,7 +4,7 @@ rhrev is a comprehensive revision history tracking system for the AsciiDoc and A
 
 https://baiyibai-antora.gitlab.io
 
-It supports several converters/backends:
+== Supported Backends
 
 * asciidoctor-pdf
 +
@@ -21,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]
 
-* *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=features]
+
+include::doc/modules/ROOT/pages/introduction.adoc[tag=quick-start]
 
 == Inspiration
 
@@ -44,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
 
@@ -116,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
 ----
 
@@ -130,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[^]

package/antora-extension/antora-rhrev-asciidoc.js

@@ -39,23 +39,26 @@ class RevisionCatalog {
   }
 
   sortedRevisions() {
-    // Collect all unique revisions from entries and allEntries
     const revisions = new Set([
       ...Object.keys(this.entries),
       ...Object.keys(this.allEntries)
     ])
-    
-    return Array.from(revisions).sort((a, b) => {
-      const [aMajor, aMinor] = a.split('-').map(Number)
-      const [bMajor, bMinor] = b.split('-').map(Number)
-      
-      if (aMajor !== bMajor) return bMajor - aMajor
-      return bMinor - aMinor
-    })
+    return Array.from(revisions).sort(compareRevisions)
   }
 }
 
-// Helper functions
+function compareRevisions(a, b) {
+  const aParts = a.split('-').map(Number)
+  const bParts = b.split('-').map(Number)
+  const len = Math.max(aParts.length, bParts.length)
+  for (let i = 0; i < len; i++) {
+    const aVal = i < aParts.length ? aParts[i] : 0
+    const bVal = i < bParts.length ? bParts[i] : 0
+    if (aVal !== bVal) return bVal - aVal
+  }
+  return 0
+}
+
 function isInitialRelease(revnumber) {
   return revnumber === '1.0' || revnumber === '1'
 }
@@ -328,7 +331,7 @@ function generateHtmlTable(doc, catalog, currentPage = '') {
     const prevrevAttr = `${revision}-prevrev`
     const prevrevdateAttr = `${revision}-prevrevdate`
     const revisionLabel = String(doc.getAttribute('version-label') || 'Revision')
-    const prevTitle = String(doc.getAttribute(prevrevAttr) || revision.replace('-', '.'))
+    const prevTitle = String(doc.getAttribute(prevrevAttr) || revision.replaceAll('-', '.'))
     const prevDate = String(doc.getAttribute(prevrevdateAttr) || '')
     const prevRevText = formatPrevRev(prevTitle, prevDate, doc)
     
@@ -366,15 +369,43 @@ function generateHtmlTable(doc, catalog, currentPage = '') {
       ).join(' ')
       
       html.push('<tr>')
-      
-      // Build link - if entry is from a different page, include page path
+
+      // Build link: local anchor if the section lives on the current page (directly or via include)
       let linkHref = `#${anchor}`
       if (entry.page && entry.page !== currentPage) {
-        // Cross-page link: convert "modules/ROOT/pages/chapter-1.adoc" to "chapter-1.html#anchor"
-        const pagePath = entry.page.replace('modules/ROOT/pages/', '').replace('.adoc', '.html')
-        linkHref = `${pagePath}#${anchor}`
+        const entryComponent = entry.component
+        const entryVersion = entry.version
+        const entryModule = entry.module || 'ROOT'
+        const entryPageStem = entry.stem ||
+          entry.page.replace(/^modules\/[^/]+\/pages\//, '').replace(/\.[^.]+$/, '')
+
+        const currentComponent = doc.getAttribute('page-component-name')
+        const currentVersion = doc.getAttribute('page-version')
+        const currentModule = doc.getAttribute('page-module') || 'ROOT'
+        const currentDocname = doc.getAttribute('docname') || ''
+
+        // Check if the source page is included into the current page.
+        // Key format matches includedBy builder: "component/module/filename"
+        const includedBy = global.antoraRhrevCatalog?.includedBy
+        const entryPageKey = `${entryComponent}/${entryModule}/${entry.page}`
+        const currentPageFile = currentDocname ? `${currentDocname}.adoc` : null
+        const isIncludedLocally = currentPageFile && (includedBy?.[entryPageKey] || []).some(inc => {
+          if (inc.component !== currentComponent || inc.module !== currentModule) return false
+          if (inc.page !== currentPageFile) return false
+          if (inc.tag === null) return true
+          return entry.containingTags?.includes(inc.tag)
+        })
+
+        if (isIncludedLocally) {
+          linkHref = `#${anchor}`
+        } else if (entryComponent === currentComponent && entryVersion === currentVersion && entryModule === 'ROOT') {
+          linkHref = `${entryPageStem}.html#${anchor}`
+        } else {
+          const modulePart = entryModule !== 'ROOT' ? `${entryModule}/` : ''
+          linkHref = `../../${entryComponent}/${entryVersion}/${modulePart}${entryPageStem}.html#${anchor}`
+        }
       }
-      
+
       html.push(`<td><a href="${linkHref}">${title}</a></td>`)
       html.push(`<td>${formatChangeAsHtmlList(entry.change)}</td>`)
       html.push('</tr>')
@@ -416,23 +447,34 @@ module.exports.register = function (registry, context = {}) {
         }
       }
       
-      // Try to use global catalog from Antora pipeline extension
-      // Otherwise fall back to collecting from current document only
-      let catalog = global.antoraRhrevCatalog
-      
+      // Try to use catalog from Antora pipeline extension (component-scoped by default).
+      // global.antoraRhrevCatalog is the site-wide catalog; .byComponent holds per-component catalogs.
+      let catalog
+      const rhrevCatalog = global.antoraRhrevCatalog
+      if (rhrevCatalog && rhrevCatalog.byComponent) {
+        const rhrevScope = doc.getAttribute('rhrev-scope') || 'component'
+        if (rhrevScope === 'site') {
+          catalog = rhrevCatalog
+        } else {
+          const componentName = doc.getAttribute('page-component-name') || '__unknown__'
+          catalog = rhrevCatalog.byComponent[componentName] || rhrevCatalog
+        }
+      } else if (rhrevCatalog && rhrevCatalog.entries) {
+        catalog = rhrevCatalog
+      }
+
       if (!catalog || !catalog.entries) {
-        // Fallback: collect from current document only (standalone mode)
         catalog = collectAllEntries(doc)
       }
-      
+
       if (catalog.sortedRevisions().length === 0) {
         return self.createBlock(parent, 'paragraph', '')
       }
-      
+
       // Get current page path for cross-page link resolution
-      const currentPage = doc.getAttribute('page-component-src-relative') || 
+      const currentPage = doc.getAttribute('page-component-src-relative') ||
                          doc.getAttribute('docfile') || ''
-      
+
       const html = generateHtmlOutput(doc, catalog, currentPage)
       return self.createBlock(parent, 'pass', html)
     })

package/antora-extension/antora-rhrev-html.js

@@ -21,40 +21,105 @@ module.exports.register = function ({ config: extensionConfig = {} }) {
   // Hook into contentClassified - we can still modify raw content
   this.on('contentClassified', ({ contentCatalog, siteAsciiDocConfig }) => {
     if (!contentCatalog) return
-    
+
     if (!quiet) {
       logger.debug('rhrev-extension: contentClassified event fired')
     }
-    
-    // Find all pages in the catalog
+
     const pageFiles = contentCatalog.findBy({ family: 'page' }) || []
-    
+
     if (!quiet) {
       logger.debug(`rhrev-extension: Found ${pageFiles.length} page files`)
     }
-    
-    // Build global catalog by scanning all pages
-    const globalCatalog = buildGlobalCatalog(pageFiles, logger, quiet)
-    
-    if (!quiet) {
-      logger.debug(`rhrev-extension: Global catalog has ${Object.keys(globalCatalog.entries).length} revisions`)
-      logger.debug(`rhrev-extension: Total block entries: ${Object.values(globalCatalog.entries).reduce((sum, arr) => sum + arr.length, 0)}`)
+
+    // Group pages by Antora component name
+    const pagesByComponent = {}
+    for (const file of pageFiles) {
+      const componentName = file.src?.component || '__unknown__'
+      if (!pagesByComponent[componentName]) pagesByComponent[componentName] = []
+      pagesByComponent[componentName].push(file)
     }
-    
-    // Store the catalog globally so the Asciidoctor extension can access it
-    // This allows proper backend-specific rendering (HTML vs PDF)
-    global.antoraRhrevCatalog = globalCatalog
-    
+
+    // Build a catalog for each component
+    const byComponent = {}
+    for (const [componentName, files] of Object.entries(pagesByComponent)) {
+      byComponent[componentName] = buildComponentCatalog(files, logger, quiet)
+      if (!quiet) {
+        logger.debug(`rhrev-extension: Component '${componentName}' catalog has ${Object.keys(byComponent[componentName].entries).length} revisions`)
+      }
+    }
+
+    // Build a merged site-wide catalog (= backward-compatible top-level catalog)
+    const site = mergeCatalogs(Object.values(byComponent))
+
+    // Build includedBy map: scan each page for cross-component include directives.
+    // Maps "srcComponent/modules/mod/pages/file.adoc" → [{component, version, page, tag}]
+    // Used by the Asciidoctor blockMacro to emit local anchors for included sections.
+    const includedBy = {}
+    const crossIncludeRx = /^include::([^:]+):([^:]+):page\$([^\[]+\.adoc)\[([^\]]*)\]/gm
+    for (const targetFiles of Object.values(pagesByComponent)) {
+      for (const targetFile of targetFiles) {
+        if (!targetFile.contents) continue
+        const content = targetFile.contents.toString()
+        let m
+        crossIncludeRx.lastIndex = 0
+        while ((m = crossIncludeRx.exec(content)) !== null) {
+          const srcComp = m[1], srcMod = m[2], srcPageFile = m[3], attrs = m[4]
+          const tagM = attrs.match(/\btag=([^,\]]+)/)
+          const tag = tagM ? tagM[1].trim() : null
+          // Key format: "component/module/filename" — matches entry.component + '/' + entry.module + '/' + entry.page
+          // (file.src.relative in Antora is just the filename, e.g. "introduction.adoc", not the full path)
+          const key = `${srcComp}/${srcMod}/${srcPageFile}`
+          if (!includedBy[key]) includedBy[key] = []
+          includedBy[key].push({
+            component: targetFile.src?.component,
+            module: targetFile.src?.module || 'ROOT',
+            page: targetFile.src?.relative,  // e.g. "rhrev.adoc"
+            tag
+          })
+        }
+      }
+    }
+
+    // Store: top-level is site-wide (backward compat with installed 1.0.1 npm package),
+    // byComponent is added for component-scoped lookup in 1.0.2+ asciidoc extension.
+    global.antoraRhrevCatalog = site
+    global.antoraRhrevCatalog.byComponent = byComponent
+    global.antoraRhrevCatalog.includedBy = includedBy
+    global.antoraRhrevCatalog.componentFileMeta = Object.fromEntries(
+      Object.entries(byComponent).map(([name, cat]) => [name, cat.fileMeta || {}])
+    )
+
     if (!quiet) {
-      logger.debug('rhrev-extension: Global catalog stored for Asciidoctor extension')
+      logger.debug(`rhrev-extension: Catalogs stored — ${Object.keys(byComponent).length} component(s) + site-wide`)
     }
   })
 }
 
-function buildGlobalCatalog(pageFiles, logger, quiet) {
+function mergeCatalogs(catalogs) {
+  const merged = {
+    entries: {},
+    allEntries: {},
+    sortedRevisions() {
+      const all = [...Object.keys(this.entries), ...Object.keys(this.allEntries)]
+      return [...new Set(all)].sort(compareRevisions)
+    }
+  }
+  for (const catalog of catalogs) {
+    for (const [revision, entries] of Object.entries(catalog.entries)) {
+      if (!merged.entries[revision]) merged.entries[revision] = []
+      merged.entries[revision].push(...entries)
+    }
+    Object.assign(merged.allEntries, catalog.allEntries)
+  }
+  return merged
+}
+
+function buildComponentCatalog(pageFiles, logger, quiet) {
   const catalog = {
     entries: {},      // { '1-1': [...], '1-2': [...] }
     allEntries: {},   // { '1-1': 'text', '1-2': 'text' }
+    fileMeta: {},     // { 'modules/ROOT/pages/file.adoc': { tagName: {startLine, endLine} } }
     sequence: 0,
     
     // Add sortedRevisions method for compatibility with Asciidoctor extension
@@ -64,46 +129,33 @@ function buildGlobalCatalog(pageFiles, logger, quiet) {
         ...Object.keys(this.allEntries)
       ]
       const uniqueRevisions = [...new Set(allRevisions)]
-      
-      return uniqueRevisions.sort((a, b) => {
-        const [aMajor, aMinor] = a.split('-').map(Number)
-        const [bMajor, bMinor] = b.split('-').map(Number)
-        
-        if (aMajor !== bMajor) return bMajor - aMajor
-        return bMinor - aMinor
-      })
+      return uniqueRevisions.sort(compareRevisions)
     }
   }
-  
+
   // Get component attributes from first file's src.origin (antora.yml)
   const firstFile = pageFiles[0]
   if (!firstFile) return catalog
-  
+
   // Component attributes are in src.origin.descriptor.asciidoc.attributes
   const componentAttrs = firstFile.src?.origin?.descriptor?.asciidoc?.attributes || {}
   const prefix = componentAttrs.revhistoryprefix || 'rhrev'
-  
+
   if (!quiet) {
     logger.debug(`rhrev-extension: Using prefix '${prefix}'`)
   }
-  
-  // Collect document-level entries (-all)
-  for (let major = 0; major <= 9; major++) {
-    for (let minor = 0; minor <= 9; minor++) {
-      const revision = `${major}-${minor}`
-      const prevrevAttr = `${revision}-prevrev`
-      
-      if (componentAttrs[prevrevAttr]) {
-        const allAttrName = `${prefix}${revision}-all`
-        const allValue = componentAttrs[allAttrName]
-        
-        if (allValue) {
-          catalog.allEntries[revision] = allValue
-          
-          if (!quiet) {
-            logger.debug(`rhrev-extension: Found -all entry for ${revision}`)
-          }
-        }
+
+  // Collect document-level entries by scanning for *-prevrev attributes (supports N-part versions)
+  const prevrevRx = /^([0-9]+(?:-[0-9]+)+)-prevrev$/
+  for (const attrName of Object.keys(componentAttrs)) {
+    const m = attrName.match(prevrevRx)
+    if (!m) continue
+    const revision = m[1]
+    const allValue = componentAttrs[`${prefix}${revision}-all`]
+    if (allValue) {
+      catalog.allEntries[revision] = allValue
+      if (!quiet) {
+        logger.debug(`rhrev-extension: Found -all entry for ${revision}`)
       }
     }
   }
@@ -118,17 +170,35 @@ function buildGlobalCatalog(pageFiles, logger, quiet) {
       logger.debug(`rhrev-extension: Scanning ${file.src?.relative} for block attributes`)
     }
     
-    // Match block attribute lines: [rhrev1-1="text"]
-    const blockAttrRx = new RegExp(`\\[${prefix}([0-9]+-[0-9]+)="([^"]+)"\\]`, 'g')
+    // Strip delimited block content (source, literal, listing) to avoid matching examples
+    const strippedContent = stripVerbatimBlocks(content)
+
+    // Compute tag regions in the stripped content (for cross-component include detection)
+    const fileTagBoundaries = {}
+    strippedContent.split('\n').forEach((line, lineNum) => {
+      const startM = line.match(/^\/\/ tag::([^\[\]]+)\[\]$/)
+      if (startM) fileTagBoundaries[startM[1]] = { startLine: lineNum }
+      const endM = line.match(/^\/\/ end::([^\[\]]+)\[\]$/)
+      if (endM && fileTagBoundaries[endM[1]]) fileTagBoundaries[endM[1]].endLine = lineNum
+    })
+    catalog.fileMeta[file.src?.relative || file.path] = fileTagBoundaries
+
+    // Match block attribute lines: [rhrev1-1="text"] or [rhrev1-0-1="text"] (N-part versions)
+    const blockAttrRx = new RegExp(`\\[${prefix}([0-9]+(?:-[0-9]+)+)="([^"]+)"\\]`, 'g')
     let match
-    
-    while ((match = blockAttrRx.exec(content)) !== null) {
+
+    while ((match = blockAttrRx.exec(strippedContent)) !== null) {
       const revision = match[1]
       const changeText = match[2]
+      const matchLine = strippedContent.substring(0, match.index).split('\n').length - 1
+      const containingTags = Object.entries(fileTagBoundaries)
+        .filter(([, b]) => b.startLine !== undefined && b.endLine !== undefined &&
+          matchLine > b.startLine && matchLine < b.endLine)
+        .map(([name]) => name)
       
       // Look for anchor/title IMMEDIATELY after the attribute (within next 200 chars)
       const matchEnd = match.index + match[0].length
-      const nextChunk = content.substring(matchEnd, matchEnd + 200)
+      const nextChunk = strippedContent.substring(matchEnd, matchEnd + 200)
       
       // Look for [#anchor], .Title, or === Section in that order
       const anchorMatch = nextChunk.match(/^\s*\[#([^\]]+)\]/)
@@ -162,13 +232,19 @@ function buildGlobalCatalog(pageFiles, logger, quiet) {
             if (!catalog.entries[revision]) {
               catalog.entries[revision] = []
             }
-            
+
             catalog.entries[revision].push({
               anchor,
               change: changeText,
               title,
               sequence: catalog.sequence++,
-              page: file.src?.relative || file.path
+              page: file.src?.relative || file.path,
+              component: file.src?.component,
+              version: file.src?.version,
+              module: file.src?.module || 'ROOT',
+              stem: file.src?.stem || (file.src?.basename || '').replace(/\.[^.]+$/, ''),
+              matchLine,
+              containingTags
             })
             
         if (!quiet) {
@@ -257,18 +333,12 @@ function generateRevisionHistoryHtml(file, catalog, logger, quiet) {
   ]
   const uniqueRevisions = [...new Set(allRevisions)]
   
-  const sortedRevisions = uniqueRevisions.sort((a, b) => {
-    const [aMajor, aMinor] = a.split('-').map(Number)
-    const [bMajor, bMinor] = b.split('-').map(Number)
-    
-    if (aMajor !== bMajor) return bMajor - aMajor
-    return bMinor - aMinor
-  })
-  
+  const sortedRevisions = uniqueRevisions.sort(compareRevisions)
+
   // Generate revision rows
   sortedRevisions.forEach(revision => {
     const prevrevAttr = `${revision}-prevrev`
-    const prevTitle = String(attrs[prevrevAttr] || revision.replace('-', '.'))
+    const prevTitle = String(attrs[prevrevAttr] || revision.replaceAll('-', '.'))
     const prevrevdateAttr = `${revision}-prevrevdate`
     const prevDate = attrs[prevrevdateAttr] || ''
     
@@ -329,6 +399,33 @@ function generateRevisionHistoryHtml(file, catalog, logger, quiet) {
   return html.join('\n')
 }
 
+function stripVerbatimBlocks(content) {
+  const lines = content.split('\n')
+  const out = []
+  let depth = 0
+  for (const line of lines) {
+    if (/^-{4,}$|^\.{4,}$|^\+{4,}$/.test(line)) {
+      depth = depth > 0 ? depth - 1 : depth + 1
+      out.push(line)
+    } else if (depth === 0) {
+      out.push(line)
+    }
+  }
+  return out.join('\n')
+}
+
+function compareRevisions(a, b) {
+  const aParts = a.split('-').map(Number)
+  const bParts = b.split('-').map(Number)
+  const len = Math.max(aParts.length, bParts.length)
+  for (let i = 0; i < len; i++) {
+    const aVal = i < aParts.length ? aParts[i] : 0
+    const bVal = i < bParts.length ? bParts[i] : 0
+    if (aVal !== bVal) return bVal - aVal
+  }
+  return 0
+}
+
 function formatChangeAsHtmlList(text) {
   if (!text) return ''
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciidoctor-rhrev",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Revision history block macro extension for Asciidoctor.js and Antora (HTML5 backend)",
   "main": "antora-extension/antora-rhrev-asciidoc.js",
   "scripts": {