dilim/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2026-08-08 17:11:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

meson: expose knob for xmlto relative links in manuals

Browse Source 
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:<relative> 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 <ben.knoble@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
D. Ben Knoble
2026-08-07 07:56:24 -04:00
committed by Junio C Hamano
parent 2c78326f81
commit 70b392613f
2 changed files with 8 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
Documentation/meson.build
View File

@@ -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',

2
meson_options.txt
View File

@@ -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',