diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df9906467bbdc9a7a62abfb9a9889dd1a0847320..80ead5dcfdfefbd98fd01856d985ece2e2b56b60 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -13,6 +13,7 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * introduce `embedReferenceStyle` property on exporter's converter object to control how image targets are rewritten (when embedded or bundled) (#100) * introduce `link_reference_style` subkey on the `assembly` category key in the Assembler configuration to control how linkable targets are rewritten (#116) * assign intrinsic attributes assembler-filetype and assembler-filetype- (#122) +* introduce `drop_explicit_xref_text` subkey on the `assembly` category key to control when Assembler drops the text of an xref (#25) === Changed diff --git a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc index 91e27478d436fc3c892804b0a7b344c2f059113c..c26ef34d7b91b8826966315c8b789ece5e6f2e46 100644 --- a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc +++ b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc @@ -50,6 +50,11 @@ Acceptable keys and their default values are listed in the table below. |absolute, root-relative, relative |Controls how Assembler rewrites references to linkable resources. +|<> +|never +|always, if-redundant, never +|Controls when Assembler drops the text of an xref. + |<> | |String @@ -433,6 +438,28 @@ One exception is when the export is HTML and the value of the key is `relative`. When exporting to HTML, this key is also used to control how image references are rewritten. When exporting to any other format, the converter controls this behavior. +[#drop-explicit-xref-text-key] +== drop_explicit_xref_text + +The `drop_explicit_xref_text` key controls whether Assembler drops the explicit text defined on xrefs (almost always page references). + +The `drop_explicit_xref_text` key is an optional key that can be set in [.path]_antora-assembler.yml_. +It accepts the values `always`, `if-redundant`, and `never`. +The default value is `never`. + +.antora-assembler.yml +[,yaml] +---- +assembly: + drop_explicit_xref_text: if-redundant +---- + +The benefit of dropping the explicit text is that once in the assembly, the xref's text can be controlled by the global `xrefstyle` attribute. +For example, when linking to a section with numbering enabled, the rendered text will look like `Section 2.3, “Installation”` if the `xreftext` is set to full. +If the original xref text were to be preserved, that text would be used as entered. + +The `if-redundant` setting only drops the text in the case that the explicit text matches the title of the target page. + [#profile-key] == profile diff --git a/packages/assembler/lib/load-config.js b/packages/assembler/lib/load-config.js index c3a2d1f244e39d047f5fbb924640ba14a6760c73..5198dd1dbb63630485181e917a8f0009812f60f6 100644 --- a/packages/assembler/lib/load-config.js +++ b/packages/assembler/lib/load-config.js @@ -5,6 +5,14 @@ const fsp = require('node:fs/promises') const os = require('node:os') const yaml = require('js-yaml') +const ASSEMBLY_KEYS = [ + 'rootLevel', + 'insertStartPage', + 'sectionMergeStrategy', + 'linkReferenceStyle', + 'dropExplicitXrefText', +] + function loadConfig (playbook, configSource = './antora-assembler.yml') { return ( configSource.constructor === Object @@ -46,7 +54,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') { const remapAssemblyKeys = !('assembly' in config) const assembly = (config.assembly ??= {}) if (remapAssemblyKeys) { - for (const key of ['rootLevel', 'insertStartPage', 'sectionMergeStrategy', 'linkReferenceStyle']) { + for (const key of ASSEMBLY_KEYS) { if (!(key in config)) continue assembly[key] = config[key] delete config[key] @@ -62,6 +70,9 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') { if (['relative', 'root-relative', 'absolute'].indexOf(assembly.linkReferenceStyle) < 0) { assembly.linkReferenceStyle = 'absolute' } + if (['always', 'if-redundant', 'never'].indexOf(assembly.dropExplicitXrefText) < 0) { + assembly.dropExplicitXrefText = 'never' + } const build = (config.build ??= {}) if (build.dir === '$' + '{playbook.output.dir}') { throw new Error('Not implemented') diff --git a/packages/assembler/lib/produce-assembly-file.js b/packages/assembler/lib/produce-assembly-file.js index 6c4e6019385f69de3e21887119f199b9c74c5578..5380e7485a1eb993d1f70b7b7628ee40d75542f2 100644 --- a/packages/assembler/lib/produce-assembly-file.js +++ b/packages/assembler/lib/produce-assembly-file.js @@ -447,7 +447,14 @@ function mergeAsciiDoc ( const refid = fragment ? `${relativePart}${idScopeSeparator}${fragment}` : relativePart + (ReservedIdNames.includes(relativePart) ? idScopeSeparator : '') - return `<<${refid}${text && text !== resource.title ? ',' + text.replace(/\\]/g, ']') : ''}>>` + if ( + text && + (assemblyModel.dropExplicitXrefText === 'always' || + (assemblyModel.dropExplicitXrefText === 'if-redundant' && text === resource.title)) + ) { + text = '' + } + return `<<${refid}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>` }) } if (~line.indexOf('link:{attachmentsdir}/')) { diff --git a/packages/assembler/lib/produce-assembly-files.js b/packages/assembler/lib/produce-assembly-files.js index 2d1a2495301515aef45d30068a81b825466a21d1..68e88c62abe643d0d2fd60481256b7802ef46fef 100644 --- a/packages/assembler/lib/produce-assembly-files.js +++ b/packages/assembler/lib/produce-assembly-files.js @@ -20,6 +20,7 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re xmlIds: assemblyConfig.xmlIds, embedReferenceStyle: assemblyConfig.embedReferenceStyle, linkReferenceStyle: assemblyConfig.linkReferenceStyle, + dropExplicitXrefText: assemblyConfig.dropExplicitXrefText, }) const assemblerAsciiDocAttributes = Object.assign({}, assemblerAsciiDocConfig.attributes) const { revdate, 'source-highlighter': sourceHighlighter } = assemblerAsciiDocAttributes diff --git a/packages/assembler/test/produce-assembly-files-test.js b/packages/assembler/test/produce-assembly-files-test.js index 7d019a86ecf4abf65dd87d24b9bf42968dfbdd49..2f17c702883efaafc1b5b87c225b44655781aebf 100644 --- a/packages/assembler/test/produce-assembly-files-test.js +++ b/packages/assembler/test/produce-assembly-files-test.js @@ -183,6 +183,24 @@ describe('produceAssemblyFiles()', () => { await runScenario('rewrite-relative-page-links', __dirname) }) + it('should drop redundant page link text when drop_explicit_xref_text is if-redundant', async () => { + const { loadAsciiDoc, contentCatalog, assemblerConfig } = await loadScenario('rewrite-page-links', __dirname) + assemblerConfig.assembly.dropExplicitXrefText = 'if-redundant' + const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) + assert.equal(assemblyFiles.length, 1) + const actual = assemblyFiles[0].contents.toString() + assert.match(actual, /<>/) + }) + + it('should drop redundant page link text when drop_explicit_xref_text is always', async () => { + const { loadAsciiDoc, contentCatalog, assemblerConfig } = await loadScenario('rewrite-page-links', __dirname) + assemblerConfig.assembly.dropExplicitXrefText = 'always' + const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) + assert.equal(assemblyFiles.length, 1) + const actual = assemblyFiles[0].contents.toString() + assert.match(actual, /<>/) + }) + it('should allow generated IDs to be XML compliant', async () => { await runScenario('xml-ids', __dirname) }) diff --git a/packages/assembler/test/scenarios/rewrite-page-links/data.yml b/packages/assembler/test/scenarios/rewrite-page-links/data.yml index 89afd9980b583a9f0d8afd5d73d2819e280d3ab0..25aae86c469713fdfded7af472d0878818ad14db 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/data.yml +++ b/packages/assembler/test/scenarios/rewrite-page-links/data.yml @@ -18,7 +18,7 @@ files: You are on xref:the-page.adoc[this page]. - This page follows the xref:header.adoc[]. + This page follows the xref:header.adoc[Header]. Also see xref:other-module:the-page.adoc[]. diff --git a/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc b/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc index f434cd2441ecd1607e0bd7770785571959594160..452612f19733464cd82b324a8b0f28a47b00f1c7 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc +++ b/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc @@ -34,7 +34,7 @@ Stuff at the top. You are on <>. -This page follows the <>. +This page follows the <>. Also see <>.