meson: wire up support for AsciiDoctor
While our Makefile supports both Asciidoc and AsciiDoctor, our Meson build instructions only support the former. Wire up support for the latter, as well. Our Makefile always favors Asciidoc, but Meson will automatically figure out which of both to use based on whether they are installed or not. To keep compatibility with our Makefile it favors Asciidoc over Asciidoctor in case both are available. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patrick Steinhardt committed
Dec 27, 2024 at 14:59 UTC
d838d821c9687a789673b2ac9dff707fdc599e1e
2 files changed
+84
-28
Documentation/meson.build
+82
-28
index fca3eab1f1..acd6d86ec7 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -204,29 +204,87 @@ manpages = {
'gitworkflows.txt' : 7,
}
-asciidoc = find_program('asciidoc')
-git = find_program('git', required: false)
-xmlto = find_program('xmlto')
+docs_backend = get_option('docs_backend')
+if docs_backend == 'auto'
+ if find_program('asciidoc', required: false).found()
+ docs_backend = 'asciidoc'
+ elif find_program('asciidoctor', required: false).found()
+ docs_backend = 'asciidoctor'
+ else
+ error('Neither asciidoc nor asciidoctor were found.')
+ endif
+endif
-asciidoc_conf = custom_target(
- command: [
- shell,
- meson.project_source_root() / 'GIT-VERSION-GEN',
- meson.project_source_root(),
- '@INPUT@',
- '@OUTPUT@',
- ],
- input: meson.current_source_dir() / 'asciidoc.conf.in',
- output: 'asciidoc.conf',
- depends: [git_version_file],
- env: version_gen_environment,
-)
+if docs_backend == 'asciidoc'
+ asciidoc = find_program('asciidoc', required: true)
+ asciidoc_html = 'xhtml11'
+ asciidoc_docbook = 'docbook'
+ xmlto_extra = [ ]
-asciidoc_common_options = [
- asciidoc,
- '--conf-file=' + asciidoc_conf.full_path(),
- '--attribute=build_dir=' + meson.current_build_dir(),
-]
+ asciidoc_conf = custom_target(
+ command: [
+ shell,
+ meson.project_source_root() / 'GIT-VERSION-GEN',
+ meson.project_source_root(),
+ '@INPUT@',
+ '@OUTPUT@',
+ ],
+ input: meson.current_source_dir() / 'asciidoc.conf.in',
+ output: 'asciidoc.conf',
+ depends: [git_version_file],
+ env: version_gen_environment,
+ )
+
+ asciidoc_common_options = [
+ asciidoc,
+ '--conf-file=' + asciidoc_conf.full_path(),
+ '--attribute=build_dir=' + meson.current_build_dir(),
+ ]
+
+ documentation_deps = [
+ asciidoc_conf,
+ ]
+elif docs_backend == 'asciidoctor'
+ asciidoctor = find_program('asciidoctor', required: true)
+ asciidoc_html = 'xhtml5'
+ asciidoc_docbook = 'docbook5'
+ xmlto_extra = [
+ '--skip-validation',
+ '-x', meson.current_source_dir() / 'manpage.xsl',
+ ]
+
+ asciidoctor_extensions = custom_target(
+ command: [
+ shell,
+ meson.project_source_root() / 'GIT-VERSION-GEN',
+ meson.project_source_root(),
+ '@INPUT@',
+ '@OUTPUT@',
+ ],
+ input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',
+ output: 'asciidoctor-extensions.rb',
+ depends: [git_version_file],
+ env: version_gen_environment,
+ )
+
+ asciidoc_common_options = [
+ asciidoctor,
+ '--attribute', 'compat-mode',
+ '--attribute', 'tabsize=8',
+ '--attribute', 'litdd=--',
+ '--attribute', 'docinfo=shared',
+ '--attribute', 'build_dir=' + meson.current_build_dir(),
+ '--load-path', meson.current_build_dir(),
+ '--require', 'asciidoctor-extensions',
+ ]
+
+ documentation_deps = [
+ asciidoctor_extensions,
+ ]
+endif
+
+git = find_program('git', required: false)
+xmlto = find_program('xmlto')
cmd_lists = [
'cmds-ancillaryinterrogators.txt',
@@ -243,10 +301,6 @@ cmd_lists = [
'cmds-foreignscminterface.txt',
]
-documentation_deps = [
- asciidoc_conf,
-]
-
documentation_deps += custom_target(
command: [
perl,
@@ -278,7 +332,7 @@ foreach manpage, category : manpages
if get_option('docs').contains('man')
manpage_xml_target = custom_target(
command: asciidoc_common_options + [
- '--backend=docbook',
+ '--backend=' + asciidoc_docbook,
'--doctype=manpage',
'--out-file=@OUTPUT@',
meson.current_source_dir() / manpage,
@@ -301,7 +355,7 @@ foreach manpage, category : manpages
manpage_xml_target,
'-o',
meson.current_build_dir(),
- ],
+ ] + xmlto_extra,
output: manpage_path,
install: true,
install_dir: get_option('mandir') / 'man' + category.to_string(),
@@ -311,7 +365,7 @@ foreach manpage, category : manpages
if get_option('docs').contains('html') and category == 1
custom_target(
command: asciidoc_common_options + [
- '--backend=xhtml11',
+ '--backend=' + asciidoc_html,
'--doctype=manpage',
'--out-file=@OUTPUT@',
meson.current_source_dir() / manpage,
meson_options.txt
+2
index 4be7eab399..f50bb40cdf 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -85,6 +85,8 @@ option('docs', type: 'array', choices: ['man', 'html'], value: [],
description: 'Which documenattion formats to build and install.')
option('default_help_format', type: 'combo', choices: ['man', 'html'], value: 'man',
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.')
# Testing.
option('tests', type: 'boolean', value: true,