From: D. Ben Knoble Date: Thu, 20 Aug 2026 13:18:07 GMT Subject: [PATCH v4 1/3] meson: expose knob for xmlto relative links in manuals Message-ID: In-Reply-To: Makefile-based builds have had this knob for most of the project's life, since a479a564dc (Documentation/Makefile: allow man.base.url.for.relative.link to be set from Make, 2009-12-03). Meson, however, hard-codes the equivalent of $prefix/$mandir, which is not really where all the HTML docs are stored in most distro builds. Plus, this value is missing a trailing slash, so links come out broken, like this in git.1: 1. Git User’s Manual /usr/share/manuser-manual.html Of course we can do better: 1. Change the default to match Make: use file://$(htmldir)/ (with trailing slash!) to form a local URL pointing at the HTML docs. This is safe because all current uses of link: point at HTML docs: git grep 'link:[[:alnum:]]' Documentation | grep -ve html -e http produces only a single result (Documentation/howto/howto-index.sh) which can be ignored. Since nothing else [*] in the normal build sets MAN_BASE_URL, this seems like the right default. 2. Provide a configurable knob, just like the Makefile, so distributions that build with Meson (like Gentoo) can decide where to make the links if they need to. Those that set htmldir probably won't need to tweak this any further, though. [*]: Well, Git's todo branch has a script dodoc.sh to build and archive docs for kernel.org; these docs are pulled by Homebrew installations, for example. It sets MAN_BASE_URL to "git_htmldocs", so the equivalent note on macOS + Homebrew is 1. Git User’s Manual git-htmldocs/user-manual.html which is not functional either, but that's a problem for downstream. In any case, users can recover the right path with "git --html-path". Signed-off-by: D. Ben Knoble --- Notes (benknoble/commits): This patch is mostly because I noticed the link I added in a later patch didn't come out right. I did an internet search for "MAN_BASE_URL" and got no real hits, so I'm not sure if any distros today actually use it, but that's not a proper audit in that I didn't look at any distro _code_ besides Gentoo (which, as noted, uses Meson). Documentation/meson.build | 7 ++++++- meson_options.txt | 2 ++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index f4854f802d..cfa9c67609 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -379,13 +379,18 @@ foreach manpage, category : manpages output: fs.stem(manpage) + '.xml', ) + man_base_url = 'file://' + htmldir + '/' + if get_option('man_base_url') != '' + man_base_url = get_option('man_base_url') + endif + doc_targets += custom_target( command: [ xmlto, '-m', '@INPUT0@', '-m', '@INPUT1@', '--stringparam', - 'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'), + 'man.base.url.for.relative.links=' + man_base_url, 'man', manpage_xml_target, '-o', diff --git a/meson_options.txt b/meson_options.txt index dc88f130d7..d590c21648 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -111,6 +111,8 @@ option('default_help_format', type: 'combo', choices: ['man', 'html', 'platform' description: 'Default format used when executing git-help(1).') option('docs_backend', type: 'combo', choices: ['asciidoc', 'asciidoctor', 'auto'], value: 'auto', description: 'Which backend to use to generate documentation.') +option('man_base_url', type: 'string', value: '', + description: 'The base URL to use for relative links in manuals') # Testing. option('benchmarks', type: 'feature', value: 'auto', -- 2.55.0.860.g4b6b3295ed.dirty