{"thread":{"id":"62634","subject":"[PATCH 00/10] meson: wire up missing HTML documentation","startedAt":"2024-12-13T08:49:05Z","lastAt":"2025-01-03T08:35:34Z","messageCount":33,"participants":["Patrick Steinhardt","Toon Claes","Jonathan Nieder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":10},"messages":[{"id":"509051","messageId":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":null,"subject":"[PATCH 00/10] meson: wire up missing HTML documentation","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:29Z","receivedAt":"2024-12-13T08:49:05Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthis patch series wires up missing HTML-based documentation with Meson.\nThis includes a couple of missing manpages, the user manual as well as\nthe random set of articles that we have. It also starts to generate the\nindices for API docs and howtos so that the result is a complete set of\nHTML docs, same as with our Makefile. It also fixes a couple of smaller\nissues I found while working on the series.\n\nNotably missing yet is an integration with CI as well as sanity checks\nfor any kind of missing docs in Meson. I'll work on this in a separate\npatch series once the initial CI integration as well as this patch\nseries here have landed.\n\nFurther missing is the generation of both info pages and a user manual\nPDF. I couldn't find any users of these anywhere in downstream distros,\nso I decided to not care for now until somebody complains.\n\nThe series is built on top of caacdb5dfd (The fifteenth batch,\n2024-12-10) with ps/build at 904339edbd (Introduce support for the Meson\nbuild system, 2024-12-06) merged into it.\n\nThanks!\n\nPatrick\n\n---\nPatrick Steinhardt (10):\n      meson: wire up support for AsciiDoctor\n      meson: properly wire up dependencies for our docs\n      meson: fix generation of merge tools\n      meson: generate HTML pages for all man page categories\n      Documentation: inline user-manual.conf\n      meson: generate user manual\n      Documentation: refactor \"api-index.sh\" for out-of-tree builds\n      Documentation: refactor \"howto-index.sh\" for out-of-tree builds\n      meson: generate articles\n      meson: install static files for HTML documentation\n\n Documentation/Makefile                   |   8 +-\n Documentation/asciidoc.conf.in           |  10 ++\n Documentation/{ => howto}/howto-index.sh |   2 +-\n Documentation/howto/meson.build          |  62 +++++++++\n Documentation/meson.build                | 221 +++++++++++++++++++++++++------\n Documentation/technical/api-index.sh     |  19 ++-\n Documentation/technical/meson.build      |  66 +++++++++\n Documentation/user-manual.conf           |  11 --\n meson_options.txt                        |   2 +\n 9 files changed, 344 insertions(+), 57 deletions(-)\n\n\n---\nbase-commit: 0b8924716a9b7975cb21e464917bb475de842a27\nchange-id: 20241212-b4-pks-meson-docs-2634bf3e7764\n\n"},{"id":"509052","messageId":"20241213-b4-pks-meson-docs-v1-1-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 01/10] meson: wire up support for AsciiDoctor","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:30Z","receivedAt":"2024-12-13T08:49:06Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"While our Makefile supports both Asciidoc and AsciiDoctor, our Meson\nbuild instructions only support the former. Wire up support for the\nlatter, as well.\n\nOur Makefile always favors Asciidoc, but Meson will automatically figure\nout which of both to use based on whether they are installed or not. To\nkeep compatibility with our Makefile it favors Asciidoc over Asciidoctor\nin case both are available.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 107 ++++++++++++++++++++++++++++++++++------------\n meson_options.txt         |   2 +\n 2 files changed, 82 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f2426ccaa30c29bd60b850eb0a9a4ab77c66a629..d62b0846d3f8ebc412f5fa9f775f037a3656093a 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -204,28 +204,85 @@ manpages = {\n   'gitworkflows.txt' : 7,\n }\n \n-asciidoc = find_program('asciidoc')\n-git = find_program('git', required: false)\n-xmlto = find_program('xmlto')\n+docs_backend = get_option('docs_backend')\n+if docs_backend == 'auto'\n+  if find_program('asciidoc', required: false).found()\n+    docs_backend = 'asciidoc'\n+  elif find_program('asciidoctor', required: false).found()\n+    docs_backend = 'asciidoctor'\n+  else\n+    error('Neither asciidoc nor asciidoctor were found.')\n+  endif\n+endif\n \n-asciidoc_conf = custom_target(\n-  command: [\n-    shell,\n-    meson.project_source_root() / 'GIT-VERSION-GEN',\n-    meson.project_source_root(),\n-    '@INPUT@',\n-    '@OUTPUT@',\n-  ],\n-  input: meson.current_source_dir() / 'asciidoc.conf.in',\n-  output: 'asciidoc.conf',\n-  depends: [git_version_file],\n-)\n+if docs_backend == 'asciidoc'\n+  asciidoc = find_program('asciidoc', required: true)\n+  asciidoc_html = 'xhtml11'\n+  asciidoc_docbook = 'docbook'\n+  xmlto_extra = [ ]\n \n-asciidoc_common_options = [\n-  asciidoc,\n-  '--conf-file=' + asciidoc_conf.full_path(),\n-  '--attribute=build_dir=' + meson.current_build_dir(),\n-]\n+  asciidoc_conf = custom_target(\n+    command: [\n+      shell,\n+      meson.project_source_root() / 'GIT-VERSION-GEN',\n+      meson.project_source_root(),\n+      '@INPUT@',\n+      '@OUTPUT@',\n+    ],\n+    input: meson.current_source_dir() / 'asciidoc.conf.in',\n+    output: 'asciidoc.conf',\n+    depends: [git_version_file],\n+  )\n+\n+  asciidoc_common_options = [\n+    asciidoc,\n+    '--conf-file=' + asciidoc_conf.full_path(),\n+    '--attribute=build_dir=' + meson.current_build_dir(),\n+  ]\n+\n+  documentation_deps = [\n+    asciidoc_conf,\n+  ]\n+elif docs_backend == 'asciidoctor'\n+  asciidoctor = find_program('asciidoctor', required: true)\n+  asciidoc_html = 'xhtml5'\n+  asciidoc_docbook = 'docbook5'\n+  xmlto_extra = [\n+    '--skip-validation',\n+    '-x', meson.current_source_dir() / 'manpage.xsl',\n+  ]\n+\n+  asciidoctor_extensions = custom_target(\n+    command: [\n+      shell,\n+      meson.project_source_root() / 'GIT-VERSION-GEN',\n+      meson.project_source_root(),\n+      '@INPUT@',\n+      '@OUTPUT@',\n+    ],\n+    input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',\n+    output: 'asciidoctor-extensions.rb',\n+    depends: [git_version_file],\n+  )\n+\n+  asciidoc_common_options = [\n+    asciidoctor,\n+    '--attribute', 'compat-mode',\n+    '--attribute', 'tabsize=8',\n+    '--attribute', 'litdd=&#x2d;&#x2d;',\n+    '--attribute', 'docinfo=shared',\n+    '--attribute', 'build_dir=' + meson.current_build_dir(),\n+    '--load-path', meson.current_build_dir(),\n+    '--require', 'asciidoctor-extensions',\n+  ]\n+\n+  documentation_deps = [\n+    asciidoctor_extensions,\n+  ]\n+endif\n+\n+git = find_program('git', required: false)\n+xmlto = find_program('xmlto')\n \n cmd_lists = [\n   'cmds-ancillaryinterrogators.txt',\n@@ -242,10 +299,6 @@ cmd_lists = [\n   'cmds-foreignscminterface.txt',\n ]\n \n-documentation_deps = [\n-  asciidoc_conf,\n-]\n-\n documentation_deps += custom_target(\n   command: [\n     perl,\n@@ -277,7 +330,7 @@ foreach manpage, category : manpages\n   if get_option('docs').contains('man')\n     manpage_xml_target = custom_target(\n       command: asciidoc_common_options + [\n-        '--backend=docbook',\n+        '--backend=' + asciidoc_docbook,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n         meson.current_source_dir() / manpage,\n@@ -300,7 +353,7 @@ foreach manpage, category : manpages\n         manpage_xml_target,\n         '-o',\n         meson.current_build_dir(),\n-      ],\n+      ] + xmlto_extra,\n       output: manpage_path,\n       install: true,\n       install_dir: get_option('mandir') / 'man' + category.to_string(),\n@@ -310,7 +363,7 @@ foreach manpage, category : manpages\n   if get_option('docs').contains('html') and category == 1\n     custom_target(\n       command: asciidoc_common_options + [\n-        '--backend=xhtml11',\n+        '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n         meson.current_source_dir() / manpage,\ndiff --git a/meson_options.txt b/meson_options.txt\nindex 32a72139bae870745d9131cc9086a4594826be91..0d8ba28de6da7d0ed2ac4bdef7efa967509ec898 100644\n--- a/meson_options.txt\n+++ b/meson_options.txt\n@@ -73,6 +73,8 @@ option('docs', type: 'array', choices: ['man', 'html'], value: [],\n   description: 'Which documenattion formats to build and install.')\n option('default_help_format', type: 'combo', choices: ['man', 'html'], value: 'man',\n   description: 'Default format used when executing git-help(1).')\n+option('docs_backend', type: 'combo', choices: ['asciidoc', 'asciidoctor', 'auto'], value: 'auto',\n+  description: 'Which backend to use to generate documentation.')\n \n # Testing.\n option('tests', type: 'boolean', value: true,\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509054","messageId":"20241213-b4-pks-meson-docs-v1-2-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 02/10] meson: properly wire up dependencies for our docs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:31Z","receivedAt":"2024-12-13T08:49:06Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"A couple of Meson documentation targets use `meson.current_source_dir()`\nto resolve inputs. This has the downside that it does not automagically\nmake Meson track these inputs as a dependency. After all, string\narguments really can be anything, even if they happen to match an actual\nfilesystem path.\n\nAdapt these build targets to instead use inputs.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 26 ++++++++++++++++----------\n 1 file changed, 16 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex d62b0846d3f8ebc412f5fa9f775f037a3656093a..d23ed82795026e511379ff1e77355d2ec33ec499 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -229,7 +229,7 @@ if docs_backend == 'asciidoc'\n       '@INPUT@',\n       '@OUTPUT@',\n     ],\n-    input: meson.current_source_dir() / 'asciidoc.conf.in',\n+    input: 'asciidoc.conf.in',\n     output: 'asciidoc.conf',\n     depends: [git_version_file],\n   )\n@@ -260,7 +260,7 @@ elif docs_backend == 'asciidoctor'\n       '@INPUT@',\n       '@OUTPUT@',\n     ],\n-    input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',\n+    input: 'asciidoctor-extensions.rb.in',\n     output: 'asciidoctor-extensions.rb',\n     depends: [git_version_file],\n   )\n@@ -302,10 +302,11 @@ cmd_lists = [\n documentation_deps += custom_target(\n   command: [\n     perl,\n-    meson.current_source_dir() / 'cmd-list.perl',\n+    '@INPUT@',\n     meson.project_source_root(),\n     meson.current_build_dir(),\n   ] + cmd_lists,\n+  input: 'cmd-list.perl',\n   output: cmd_lists\n )\n \n@@ -313,7 +314,7 @@ foreach mode : [ 'diff', 'merge' ]\n   documentation_deps += custom_target(\n     command: [\n       shell,\n-      meson.current_source_dir() / 'generate-mergetool-list.sh',\n+      '@INPUT@',\n       '..',\n       'diff',\n       '@OUTPUT@'\n@@ -322,6 +323,7 @@ foreach mode : [ 'diff', 'merge' ]\n       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',\n       'TOOL_MODE=' + mode,\n     ],\n+    input: 'generate-mergetool-list.sh',\n     output: 'mergetools-' + mode + '.txt',\n   )\n endforeach\n@@ -333,9 +335,10 @@ foreach manpage, category : manpages\n         '--backend=' + asciidoc_docbook,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n-        meson.current_source_dir() / manpage,\n+        '@INPUT@',\n       ],\n       depends: documentation_deps,\n+      input: manpage,\n       output: fs.stem(manpage) + '.xml',\n     )\n \n@@ -343,10 +346,8 @@ foreach manpage, category : manpages\n     manpage_target = custom_target(\n       command: [\n         xmlto,\n-        '-m',\n-        meson.current_source_dir() / 'manpage-normal.xsl',\n-        '-m',\n-        meson.current_source_dir() / 'manpage-bold-literal.xsl',\n+        '-m', '@INPUT0@',\n+        '-m', '@INPUT1@',\n         '--stringparam',\n         'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'),\n         'man',\n@@ -354,6 +355,10 @@ foreach manpage, category : manpages\n         '-o',\n         meson.current_build_dir(),\n       ] + xmlto_extra,\n+      input: [\n+        'manpage-normal.xsl',\n+        'manpage-bold-literal.xsl',\n+      ],\n       output: manpage_path,\n       install: true,\n       install_dir: get_option('mandir') / 'man' + category.to_string(),\n@@ -366,9 +371,10 @@ foreach manpage, category : manpages\n         '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n-        meson.current_source_dir() / manpage,\n+        '@INPUT@',\n       ],\n       depends: documentation_deps,\n+      input: manpage,\n       output: fs.stem(manpage) + '.html',\n       install: true,\n       install_dir: get_option('datadir') / 'doc/git-doc',\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509053","messageId":"20241213-b4-pks-meson-docs-v1-3-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 03/10] meson: fix generation of merge tools","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:32Z","receivedAt":"2024-12-13T08:49:07Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our buildsystems generate a list of diff and merge tools that ultimately\nend up in our documentation. And while Meson does wire up the logic, it\ntries to use the TOOL_MODE environment variable to set up the mode. This\nis wrong though: the mode is set via an argument that we have fixed to\n'diff' mode by accident.\n\nFix this such that merge tools are properly generated.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 3 +--\n 1 file changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex d23ed82795026e511379ff1e77355d2ec33ec499..0d8b58145274c7854fe3fd91de469fe9d1e0bb6f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -316,12 +316,11 @@ foreach mode : [ 'diff', 'merge' ]\n       shell,\n       '@INPUT@',\n       '..',\n-      'diff',\n+      mode,\n       '@OUTPUT@'\n     ],\n     env: [\n       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',\n-      'TOOL_MODE=' + mode,\n     ],\n     input: 'generate-mergetool-list.sh',\n     output: 'mergetools-' + mode + '.txt',\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509057","messageId":"20241213-b4-pks-meson-docs-v1-4-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 04/10] meson: generate HTML pages for all man page categories","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:33Z","receivedAt":"2024-12-13T08:49:07Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"When generating HTML pages for our man pages we only generate them for\ncategory 1 in MEson, which are the pages corresponding to our built-in\ncommands. I cannot tell why I added this filter though: our Makefile\ninstalls all man pages, so a Meson-based build misses out on many of\nthem.\n\nFix this by removing the filter.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 0d8b58145274c7854fe3fd91de469fe9d1e0bb6f..d36b2b0d8e7795d0520976c1e54a2f90b332cacb 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -364,7 +364,7 @@ foreach manpage, category : manpages\n     )\n   endif\n \n-  if get_option('docs').contains('html') and category == 1\n+  if get_option('docs').contains('html')\n     custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509055","messageId":"20241213-b4-pks-meson-docs-v1-6-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 06/10] meson: generate user manual","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:35Z","receivedAt":"2024-12-13T08:49:08Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our documentation contains a user manual that gives people a short\nintroduction to Git. Our Makefile knows to generate the manual into\nthree different formats: an HTML page, a PDF and an info page. The Meson\nbuild instructions don't yet generate any of these.\n\nWhile wiring up all these formats I hit a couple of road blocks with how\nwe generate our info pages. Even though I eventually resolved these, it\nmade me question whether anybody actually uses info pages in the first\nplace. Checking through a couple of downstream consumers I couldn't find\na single user of either the info pages nor of our PDF manual in Arch\nLinux, Debian, Fedora, Ubuntu, FreeBSD or OpenBSDFedora. So it's rather\nsafe to assume that there aren't really any users out there, and thus\nthe added complexity does not seem worth it.\n\nWire up support for building the user manual in HTML format and\nconciously skip over the other two formats. This is basically a form of\nsilent deprecation: if people out there use the other two formats they\nwill eventually complain about them missing in Meson, which means we can\nwire them up at a later point. If they don't we can phase out these\nformats eventually.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 32 ++++++++++++++++++++++++++++++++\n 1 file changed, 32 insertions(+)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex d36b2b0d8e7795d0520976c1e54a2f90b332cacb..1fdc6a61eb04707d7c4b7aabb412b32ddc517dc7 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -380,3 +380,35 @@ foreach manpage, category : manpages\n     )\n   endif\n endforeach\n+\n+if get_option('docs').contains('html')\n+  xsltproc = find_program('xsltproc')\n+\n+  user_manual_xml = custom_target(\n+    command: asciidoc_common_options + [\n+      '--backend=' + asciidoc_docbook,\n+      '--doctype=book',\n+      '--out-file=@OUTPUT@',\n+      '@INPUT@',\n+    ],\n+    input: 'user-manual.txt',\n+    output: 'user-manual.xml',\n+    depends: documentation_deps,\n+  )\n+\n+  custom_target(\n+    command: [\n+      xsltproc,\n+      '--xinclude',\n+      '--stringparam', 'html.stylesheet', 'docbook-xsl.css',\n+      '--param', 'generate.consistent.ids', '1',\n+      '--output', '@OUTPUT@',\n+      '@INPUT@',\n+      user_manual_xml,\n+    ],\n+    input: 'docbook.xsl',\n+    output: 'user-manual.html',\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+endif\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509056","messageId":"20241213-b4-pks-meson-docs-v1-5-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 05/10] Documentation: inline user-manual.conf","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:34Z","receivedAt":"2024-12-13T08:49:08Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"When generating our user manual we set up a bit of extra configuration\ncompared to our normal configuration. This is done by having an extra\n\"user-manual.conf\" file that Asciidoc seems to pull in automatically due\nto matching filenames with \"user-manual.txt\". This dependency is quite\nhidden though and thus easy to miss. Furthermore, it seems that Asciidoc\ndoes not know to pull it in for out-of-tree builds where we use relative\npaths.\n\nThe setup in AsciiDoctor is somewhat different: instead of having two\nsets of configuration, we condition the use of manual-specific configs\nbased on whether the document type is \"book\". And as we only build our\nuser manual with that type this is sufficient.\n\nUse the same trick for our user manual by inlining the configuration\ninto \"asciidoc.conf.in\" and making it conditional on whether or not\n\"doctype-book\" is defined.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile         |  2 +-\n Documentation/asciidoc.conf.in | 10 ++++++++++\n Documentation/user-manual.conf | 11 -----------\n 3 files changed, 11 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3392e1ce7ebc540784912476847380d9c1775ac8..31c17f7d655e1dcbdde315115609b798363e7328 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -367,7 +367,7 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n %.xml : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n \n-user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS)\n+user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n \n technical/api-index.txt: technical/api-index-skel.txt \\\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex dbe36a52eabfabef59e31d3be6518549e4f90206..83ddbb76f65d7a041e4e787a81e19ff1db1d9d55 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -25,12 +25,22 @@ manmanual='Git Manual'\n mansource='Git @GIT_VERSION@'\n revdate='@GIT_DATE@'\n \n+ifdef::doctype-book[]\n+[titles]\n+\tunderlines=\"__\",\"==\",\"--\",\"~~\",\"^^\"\n+endif::doctype-book[]\n+\n ifdef::backend-docbook[]\n [linkgit-inlinemacro]\n+ifndef::doctype-book[]\n {0%{target}}\n {0#<citerefentry>}\n {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n {0#</citerefentry>}\n+endif::doctype-book[]\n+ifdef::doctype-book[]\n+<ulink url=\"{target}.html\">{target}{0?({0})}</ulink>\n+endif::doctype-book[]\n \n [literal-inlinemacro]\n {eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\\1</emphasis>', re.sub(r'([\\[\\s|()>]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1<literal>\\2</literal>', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'<literal>\\1</literal>\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\ndiff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf\ndeleted file mode 100644\nindex 0148f126dcdf6aca15a5560fb5b122b85b022461..0000000000000000000000000000000000000000\n--- a/Documentation/user-manual.conf\n+++ /dev/null\n@@ -1,11 +0,0 @@\n-[titles]\n-\tunderlines=\"__\",\"==\",\"--\",\"~~\",\"^^\"\n-\n-[attributes]\n-caret=^\n-startsb=&#91;\n-endsb=&#93;\n-tilde=&#126;\n-\n-[linkgit-inlinemacro]\n-<ulink url=\"{target}.html\">{target}{0?({0})}</ulink>\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509058","messageId":"20241213-b4-pks-meson-docs-v1-7-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 07/10] Documentation: refactor \"api-index.sh\" for out-of-tree builds","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:36Z","receivedAt":"2024-12-13T08:49:08Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The \"api-index.sh\" script generates an index of API-related\ndocumentation. The script does not handle out-of-tree builds and thus\ncannot be used easily by Meson.\n\nRefactor it to be independent of locations by both accepting a source\ndirectory where the API docs live as well as a path to an output file.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile               |  2 +-\n Documentation/technical/api-index.sh | 19 +++++++++++++++----\n 2 files changed, 16 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 31c17f7d655e1dcbdde315115609b798363e7328..44f68e7a53843dc5ea24085d5f48b592d34aec41 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -372,7 +372,7 @@ user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n-\t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt\n \n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \\\ndiff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh\nindex 9c3f4131b8586408acd81d1e60912b51688575ed..296488557434b7fff60ab25f4246a4dc270729c0 100755\n--- a/Documentation/technical/api-index.sh\n+++ b/Documentation/technical/api-index.sh\n@@ -1,6 +1,17 @@\n #!/bin/sh\n \n+if test $# -ne 2\n+then\n+\techo >&2 \"USAGE: $0 <SOURCE_DIR> <OUTPUT>\"\n+\texit 1\n+fi\n+\n+SOURCE_DIR=\"$1\"\n+OUTPUT=\"$2\"\n+\n (\n+\tcd \"$SOURCE_DIR\"\n+\n \tc=////////////////////////////////////////////////////////////////\n \tskel=api-index-skel.txt\n \tsed -e '/^\\/\\/ table of contents begin/q' \"$skel\"\n@@ -18,11 +29,11 @@\n \tdone\n \techo \"$c\"\n \tsed -n -e '/^\\/\\/ table of contents end/,$p' \"$skel\"\n-) >api-index.txt+\n+) >\"$OUTPUT\"+\n \n-if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null\n+if test -f \"$OUTPUT\" && cmp \"$OUTPUT\" \"$OUTPUT\"+ >/dev/null\n then\n-\trm -f api-index.txt+\n+\trm -f \"$OUTPUT\"+\n else\n-\tmv api-index.txt+ api-index.txt\n+\tmv \"$OUTPUT\"+ \"$OUTPUT\"\n fi\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509059","messageId":"20241213-b4-pks-meson-docs-v1-9-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 09/10] meson: generate articles","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:38Z","receivedAt":"2024-12-13T08:49:09Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"While the Meson build system already knows to generate man pages and our\nuser manual, it does not yet generate the random assortment of articles\nthat we have. Plug this gap.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/howto/meson.build     | 62 ++++++++++++++++++++++++++++++++++\n Documentation/meson.build           | 36 ++++++++++++++++++++\n Documentation/technical/meson.build | 66 +++++++++++++++++++++++++++++++++++++\n 3 files changed, 164 insertions(+)\n\ndiff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build\nnew file mode 100644\nindex 0000000000000000000000000000000000000000..c023c104161e61ca0399b5390d59e20343746621\n--- /dev/null\n+++ b/Documentation/howto/meson.build\n@@ -0,0 +1,62 @@\n+howto_sources = [\n+  'coordinate-embargoed-releases.txt',\n+  'keep-canonical-history-correct.txt',\n+  'maintain-git.txt',\n+  'new-command.txt',\n+  'rebase-from-internal-branch.txt',\n+  'rebuild-from-update-hook.txt',\n+  'recover-corrupted-blob-object.txt',\n+  'recover-corrupted-object-harder.txt',\n+  'revert-a-faulty-merge.txt',\n+  'revert-branch-rebase.txt',\n+  'separating-topic-branches.txt',\n+  'setup-git-server-over-http.txt',\n+  'update-hook-example.txt',\n+  'use-git-daemon.txt',\n+  'using-merge-subtree.txt',\n+  'using-signed-tag-in-pull-request.txt',\n+]\n+\n+howto_index = custom_target(\n+  command: [\n+    shell,\n+    meson.current_source_dir() / 'howto-index.sh',\n+    '@INPUT@',\n+  ],\n+  env: script_environment,\n+  capture: true,\n+  input: howto_sources,\n+  output: 'howto-index.txt',\n+)\n+\n+custom_target(\n+  command: asciidoc_html_options,\n+  input: howto_index,\n+  output: 'howto-index.html',\n+  depends: documentation_deps,\n+  install: true,\n+  install_dir: get_option('datadir') / 'doc/git-doc',\n+)\n+\n+foreach howto : howto_sources\n+  howto_stripped = custom_target(\n+    command: [\n+      find_program('sed'),\n+      '-e',\n+      '1,/^$/d',\n+      '@INPUT@',\n+    ],\n+    input: howto,\n+    output: fs.stem(howto) + '.stripped',\n+    capture: true,\n+  )\n+\n+  custom_target(\n+    command: asciidoc_html_options,\n+    input: howto_stripped,\n+    output: fs.stem(howto_stripped.full_path()) + '.html',\n+    depends: documentation_deps,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc/howto',\n+  )\n+endforeach\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 1fdc6a61eb04707d7c4b7aabb412b32ddc517dc7..1dd84af2d6bcf3214cfa1ec78c00359f64040fca 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -411,4 +411,40 @@ if get_option('docs').contains('html')\n     install: true,\n     install_dir: get_option('datadir') / 'doc/git-doc',\n   )\n+\n+  articles = [\n+    'DecisionMaking.txt',\n+    'MyFirstContribution.txt',\n+    'MyFirstObjectWalk.txt',\n+    'ReviewingGuidelines.txt',\n+    'SubmittingPatches',\n+    'ToolsForGit.txt',\n+    'git-bisect-lk2009.txt',\n+    'git-tools.txt',\n+  ]\n+\n+  foreach article : articles\n+    custom_target(\n+      command: asciidoc_common_options + [\n+        '--backend=' + asciidoc_html,\n+        '--out-file=@OUTPUT@',\n+        '@INPUT@',\n+      ],\n+      input: article,\n+      output: fs.stem(article) + '.html',\n+      depends: documentation_deps,\n+      install: true,\n+      install_dir: get_option('datadir') / 'doc/git-doc',\n+    )\n+  endforeach\n+\n+  asciidoc_html_options = asciidoc_common_options + [\n+    '--backend=' + asciidoc_html,\n+    '--out-file=@OUTPUT@',\n+    '--attribute', 'git-relative-html-prefix=../',\n+    '@INPUT@',\n+  ]\n+\n+  subdir('howto')\n+  subdir('technical')\n endif\ndiff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build\nnew file mode 100644\nindex 0000000000000000000000000000000000000000..21dfb8b5c9d93490f16c24bab1d49631e0395571\n--- /dev/null\n+++ b/Documentation/technical/meson.build\n@@ -0,0 +1,66 @@\n+api_docs = [\n+  'api-error-handling.txt',\n+  'api-merge.txt',\n+  'api-parse-options.txt',\n+  'api-simple-ipc.txt',\n+  'api-trace2.txt',\n+]\n+\n+articles = [\n+  'bitmap-format.txt',\n+  'build-systems.txt',\n+  'bundle-uri.txt',\n+  'commit-graph.txt',\n+  'directory-rename-detection.txt',\n+  'hash-function-transition.txt',\n+  'long-running-process-protocol.txt',\n+  'multi-pack-index.txt',\n+  'packfile-uri.txt',\n+  'pack-heuristics.txt',\n+  'parallel-checkout.txt',\n+  'partial-clone.txt',\n+  'platform-support.txt',\n+  'racy-git.txt',\n+  'reftable.txt',\n+  'remembering-renames.txt',\n+  'repository-version.txt',\n+  'rerere.txt',\n+  'scalar.txt',\n+  'send-pack-pipeline.txt',\n+  'shallow.txt',\n+  'sparse-checkout.txt',\n+  'sparse-index.txt',\n+  'trivial-merge.txt',\n+  'unit-tests.txt',\n+]\n+\n+api_index = custom_target(\n+  command: [\n+    shell,\n+    meson.current_source_dir() / 'api-index.sh',\n+    meson.current_source_dir(),\n+    '@OUTPUT@',\n+  ],\n+  env: script_environment,\n+  input: api_docs,\n+  output: 'api-index.txt',\n+)\n+\n+custom_target(\n+  command: asciidoc_html_options,\n+  input: api_index,\n+  output: 'api-index.html',\n+  depends: documentation_deps,\n+  install: true,\n+  install_dir: get_option('datadir') / 'doc/git-doc/technical',\n+)\n+\n+foreach article : api_docs + articles\n+  custom_target(\n+    command: asciidoc_html_options,\n+    input: article,\n+    output: fs.stem(article) + '.html',\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc/technical',\n+  )\n+endforeach\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509060","messageId":"20241213-b4-pks-meson-docs-v1-8-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 08/10] Documentation: refactor \"howto-index.sh\" for out-of-tree builds","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:37Z","receivedAt":"2024-12-13T08:49:09Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The \"howto-index.sh\" is used to generate an index of our how-to docs. It\nreceives as input the paths to these documents, which would typically be\nrelative to the \"Documentation/\" directory in Makefile-based builds. In\nan out-of-tree build though it will get relative that may be rooted\nsomewhere else entirely.\n\nThe file paths do end up in the generated index, and the expectation is\nthat they should always start with \"howto/\". But for out-of-tree builds\nwe would populate it with the paths relative to the build directory,\nwhich is wrong.\n\nFix the issue by using `$(basename \"$file\")` to generate the path. While\nat it, move the script into \"howto/\" to align it with the location of\nthe comparable \"api-index.sh\" script.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile                   | 4 ++--\n Documentation/{ => howto}/howto-index.sh | 2 +-\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44f68e7a53843dc5ea24085d5f48b592d34aec41..388b5ffef99f696948042ad2bed87d573fbd4e95 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -416,8 +416,8 @@ gitman.info: gitman.texi\n $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n \t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@\n \n-howto-index.txt: howto-index.sh $(HOWTO_TXT)\n-\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@\n+howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\ndiff --git a/Documentation/howto-index.sh b/Documentation/howto/howto-index.sh\nsimilarity index 92%\nrename from Documentation/howto-index.sh\nrename to Documentation/howto/howto-index.sh\nindex 167b363668b8b53d752d5971798d3ca26c8f7f1f..eecd123a93607998e8b4eb8511f4165973f9d93e 100755\n--- a/Documentation/howto-index.sh\n+++ b/Documentation/howto/howto-index.sh\n@@ -48,7 +48,7 @@ do\n \t\tfile=\"$txt\"\n \tfi\n \n-\techo \"* link:$file[$title] $from\n+\techo \"* link:howto/$(basename \"$file\")[$title] $from\n $abstract\n \n \"\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509061","messageId":"20241213-b4-pks-meson-docs-v1-10-0c7895952cd3@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH 10/10] meson: install static files for HTML documentation","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-13T08:48:39Z","receivedAt":"2024-12-13T08:49:09Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Now that we generate man pages, articles and user manual with Meson the\nonly thing that is still missing in an installation of HTML documents is\na couple of static files. Wire these up to finalize Meson's support for\ngenerating HTML documentation.\n\nDiffing an installation that uses our Makefile with an installation that\nuses Meson only surfaces a couple of discepancies now:\n\n  - Meson doesn't install \"everyday.html\" and \"git-remote-helpers.html\".\n    These files are marked as obsolete and don't contain any useful\n    information anymore: they simply point to their modern equivalents.\n\n  - Meson doesn't install \"*.txt\" files when asking for HTML docs. I'm\n    not sure why our Makefiles do this in the first place, and it does\n    seem like the resulting installation is fully functional even\n    without those files.\n\nOther than that, both layout and file contents are the exact same.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 21 +++++++++++++++++++++\n 1 file changed, 21 insertions(+)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 1dd84af2d6bcf3214cfa1ec78c00359f64040fca..751d32c4847289da5dbbe63efbce309d36719f4f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -382,6 +382,27 @@ foreach manpage, category : manpages\n endforeach\n \n if get_option('docs').contains('html')\n+  configure_file(\n+    input: 'docinfo-html.in',\n+    output: 'docinfo.html',\n+    copy: true,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+\n+  configure_file(\n+    input: 'docbook-xsl.css',\n+    output: 'docbook-xsl.css',\n+    copy: true,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+\n+  install_symlink('index.html',\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+    pointing_to: 'git.html',\n+  )\n+\n   xsltproc = find_program('xsltproc')\n \n   user_manual_xml = custom_target(\n\n-- \n2.47.1.668.gf74b3f243a.dirty\n\n"},{"id":"509518","messageId":"87wmfqfwh1.fsf@iotcl.com","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"Re: [PATCH 00/10] meson: wire up missing HTML documentation","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2024-12-23T11:51:54Z","receivedAt":"2024-12-23T11:52:13Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> Hi,\n>\n> this patch series wires up missing HTML-based documentation with Meson.\n> This includes a couple of missing manpages, the user manual as well as\n> the random set of articles that we have. It also starts to generate the\n> indices for API docs and howtos so that the result is a complete set of\n> HTML docs, same as with our Makefile. It also fixes a couple of smaller\n> issues I found while working on the series.\n>\n> Notably missing yet is an integration with CI as well as sanity checks\n> for any kind of missing docs in Meson. I'll work on this in a separate\n> patch series once the initial CI integration as well as this patch\n> series here have landed.\n>\n> Further missing is the generation of both info pages and a user manual\n> PDF. I couldn't find any users of these anywhere in downstream distros,\n> so I decided to not care for now until somebody complains.\n>\n> The series is built on top of caacdb5dfd (The fifteenth batch,\n> 2024-12-10) with ps/build at 904339edbd (Introduce support for the Meson\n> build system, 2024-12-06) merged into it.\n\nHi Patrick,\n\nI've been reading through the patches, and as far as I understand it\nmakes sense. But to be honest, I don't know how to use this. I have\nalmost no experience with Meson and I only know `meson setup` and `meson\ncompile`. But the `meson.build` from Documentation/ is marked as a\nsubdir() if option \"docs\" is given. But I don't understand how this\nshould be used. For `meson test` there are some instructions in the\nroot-level meson.build, but not for the docs. Should we add this as\nwell?\n\nAnd a bit related to this, I saw you use `env: script_environment` in a\nfew places, how does this get injected from the root-level meson.build\nfile? Due to this, I assume it's intended to only use the root-level\nmeson.build directly, and not run `meson setup` in the Documentation/\nfolder?\n\n-- \nToon\n"},{"id":"509519","messageId":"87v7vafwg6.fsf@iotcl.com","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-4-0c7895952cd3@pks.im","subject":"Re: [PATCH 04/10] meson: generate HTML pages for all man page categories","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2024-12-23T11:52:25Z","receivedAt":"2024-12-23T11:52:35Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> When generating HTML pages for our man pages we only generate them for\n> category 1 in MEson, which are the pages corresponding to our built-in\n\nThe tiniest nit: I don't think you intended to spell Meson with a\ncapital E.\n\n-- \nToon\n"},{"id":"509613","messageId":"Z26ygb_4-DP7Ufab@pks.im","threadId":"62634","inReplyTo":"87wmfqfwh1.fsf@iotcl.com","subject":"Re: [PATCH 00/10] meson: wire up missing HTML documentation","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:58:25Z","receivedAt":"2024-12-27T13:58:47Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Dec 23, 2024 at 12:51:54PM +0100, Toon Claes wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> > Hi,\n> >\n> > this patch series wires up missing HTML-based documentation with Meson.\n> > This includes a couple of missing manpages, the user manual as well as\n> > the random set of articles that we have. It also starts to generate the\n> > indices for API docs and howtos so that the result is a complete set of\n> > HTML docs, same as with our Makefile. It also fixes a couple of smaller\n> > issues I found while working on the series.\n> >\n> > Notably missing yet is an integration with CI as well as sanity checks\n> > for any kind of missing docs in Meson. I'll work on this in a separate\n> > patch series once the initial CI integration as well as this patch\n> > series here have landed.\n> >\n> > Further missing is the generation of both info pages and a user manual\n> > PDF. I couldn't find any users of these anywhere in downstream distros,\n> > so I decided to not care for now until somebody complains.\n> >\n> > The series is built on top of caacdb5dfd (The fifteenth batch,\n> > 2024-12-10) with ps/build at 904339edbd (Introduce support for the Meson\n> > build system, 2024-12-06) merged into it.\n> \n> Hi Patrick,\n> \n> I've been reading through the patches, and as far as I understand it\n> makes sense. But to be honest, I don't know how to use this. I have\n> almost no experience with Meson and I only know `meson setup` and `meson\n> compile`. But the `meson.build` from Documentation/ is marked as a\n> subdir() if option \"docs\" is given. But I don't understand how this\n> should be used. For `meson test` there are some instructions in the\n> root-level meson.build, but not for the docs. Should we add this as\n> well?\n\nI don't really think it makes sense to explicitly point out every option\nthat we have. We already document how to discover and set options, and\nfrom hereon it follows that you can wire up docs by running for example\n`meson setup -Ddocs=man ..`. It's just another option, and as such it\ncan be discovered by running `meson configure`.\n\nThe benefit of this is that it cannot grow stale like the build options\nin our Makefile. These may or may not have documentation, and may or may\nnot be stale. With Meson, every build option is listed explicitly, has\ndocumentation and is discoverable via `meson configure`.\n\n> And a bit related to this, I saw you use `env: script_environment` in a\n> few places, how does this get injected from the root-level meson.build\n> file? Due to this, I assume it's intended to only use the root-level\n> meson.build directly, and not run `meson setup` in the Documentation/\n> folder?\n\nYup, you are always expected to set up the top-level source directory,\nnot any of the subdirectories. The build instructions are then processed\nlinearly in Meson, so variables declared before a call to `subdir()`\nwould be accessible in the subdirectory, as well.\n\nPatrick\n"},{"id":"509614","messageId":"Z26yhWsL23liQz7S@pks.im","threadId":"62634","inReplyTo":"87v7vafwg6.fsf@iotcl.com","subject":"Re: [PATCH 04/10] meson: generate HTML pages for all man page categories","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:58:29Z","receivedAt":"2024-12-27T13:58:49Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Dec 23, 2024 at 12:52:25PM +0100, Toon Claes wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> > When generating HTML pages for our man pages we only generate them for\n> > category 1 in MEson, which are the pages corresponding to our built-in\n> \n> The tiniest nit: I don't think you intended to spell Meson with a\n> capital E.\n\nIndeed, fixed now.\n\nPatrick\n"},{"id":"509615","messageId":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im","subject":"[PATCH v2 00/12] meson: wire up missing HTML documentation","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:28Z","receivedAt":"2024-12-27T14:00:00Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthis patch series wires up missing HTML-based documentation with Meson.\nThis includes a couple of missing manpages, the user manual as well as\nthe random set of articles that we have. It also starts to generate the\nindices for API docs and howtos so that the result is a complete set of\nHTML docs, same as with our Makefile. It also fixes a couple of smaller\nissues I found while working on the series.\n\nNotably missing yet is an integration with CI as well as sanity checks\nfor any kind of missing docs in Meson. I'll work on this in a separate\npatch series once the initial CI integration as well as this patch\nseries here have landed.\n\nFurther missing is the generation of both info pages and a user manual\nPDF. I couldn't find any users of these anywhere in downstream distros,\nso I decided to not care for now until somebody complains.\n\nChanges in v2:\n\n  - Change the base to 76cf4f61c8 (Merge https://github.com/j6t/git-gui,\n    2024-12-26). This is done to fix conflicts with in-flight topics and\n    to pull in the CI setup.\n  - Fix a typo.\n  - Include another commit to auto-detect missing manpages in Meson both\n    via Meson itself, but also via our Makefile.\n  - Make the equivalent check in t/Makefile work with Dash.\n  - Link to v1: https://lore.kernel.org/r/20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@pks.im\n\nThanks!\n\nPatrick\n\n---\nPatrick Steinhardt (12):\n      meson: wire up support for AsciiDoctor\n      meson: properly wire up dependencies for our docs\n      meson: fix generation of merge tools\n      meson: generate HTML pages for all man page categories\n      Documentation: inline user-manual.conf\n      meson: generate user manual\n      Documentation: refactor \"api-index.sh\" for out-of-tree builds\n      Documentation: refactor \"howto-index.sh\" for out-of-tree builds\n      meson: generate articles\n      meson: install static files for HTML documentation\n      t/Makefile: make \"check-meson\" work with Dash\n      Documentation: wire up sanity checks for Meson\n\n Documentation/.gitignore                 |   1 +\n Documentation/Makefile                   |  24 ++-\n Documentation/asciidoc.conf.in           |  10 ++\n Documentation/{ => howto}/howto-index.sh |   2 +-\n Documentation/howto/meson.build          |  62 ++++++++\n Documentation/meson.build                | 255 ++++++++++++++++++++++++++-----\n Documentation/technical/api-index.sh     |  19 ++-\n Documentation/technical/meson.build      |  66 ++++++++\n Documentation/user-manual.conf           |  11 --\n meson_options.txt                        |   2 +\n t/.gitignore                             |   1 +\n t/Makefile                               |  12 +-\n 12 files changed, 402 insertions(+), 63 deletions(-)\n\nRange-diff versus v1:\n\n 1:  e564c753c9 !  1:  376ed916ce meson: wire up support for AsciiDoctor\n    @@ Documentation/meson.build: manpages = {\n     -  input: meson.current_source_dir() / 'asciidoc.conf.in',\n     -  output: 'asciidoc.conf',\n     -  depends: [git_version_file],\n    +-  env: version_gen_environment,\n     -)\n     +if docs_backend == 'asciidoc'\n     +  asciidoc = find_program('asciidoc', required: true)\n    @@ Documentation/meson.build: manpages = {\n     +    input: meson.current_source_dir() / 'asciidoc.conf.in',\n     +    output: 'asciidoc.conf',\n     +    depends: [git_version_file],\n    ++    env: version_gen_environment,\n     +  )\n     +\n     +  asciidoc_common_options = [\n    @@ Documentation/meson.build: manpages = {\n     +    input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',\n     +    output: 'asciidoctor-extensions.rb',\n     +    depends: [git_version_file],\n    ++    env: version_gen_environment,\n     +  )\n     +\n     +  asciidoc_common_options = [\n 2:  ce9bfd53f7 !  2:  6c6e593fad meson: properly wire up dependencies for our docs\n    @@ Documentation/meson.build: if docs_backend == 'asciidoc'\n     +    input: 'asciidoc.conf.in',\n          output: 'asciidoc.conf',\n          depends: [git_version_file],\n    -   )\n    +     env: version_gen_environment,\n     @@ Documentation/meson.build: elif docs_backend == 'asciidoctor'\n            '@INPUT@',\n            '@OUTPUT@',\n    @@ Documentation/meson.build: elif docs_backend == 'asciidoctor'\n     +    input: 'asciidoctor-extensions.rb.in',\n          output: 'asciidoctor-extensions.rb',\n          depends: [git_version_file],\n    -   )\n    +     env: version_gen_environment,\n     @@ Documentation/meson.build: cmd_lists = [\n      documentation_deps += custom_target(\n        command: [\n 3:  905f220caa =  3:  b962455582 meson: fix generation of merge tools\n 4:  ff35b7433a !  4:  32578c5cd2 meson: generate HTML pages for all man page categories\n    @@ Commit message\n         meson: generate HTML pages for all man page categories\n     \n         When generating HTML pages for our man pages we only generate them for\n    -    category 1 in MEson, which are the pages corresponding to our built-in\n    +    category 1 in Meson, which are the pages corresponding to our built-in\n         commands. I cannot tell why I added this filter though: our Makefile\n         installs all man pages, so a Meson-based build misses out on many of\n         them.\n 5:  bf8c278db5 !  5:  b704daf80c Documentation: inline user-manual.conf\n    @@ Documentation/Makefile: manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $\n      technical/api-index.txt: technical/api-index-skel.txt \\\n     \n      ## Documentation/asciidoc.conf.in ##\n    -@@ Documentation/asciidoc.conf.in: manmanual='Git Manual'\n    - mansource='Git @GIT_VERSION@'\n    - revdate='@GIT_DATE@'\n    +@@ Documentation/asciidoc.conf.in: manmanual=Git Manual\n    + mansource=Git @GIT_VERSION@\n    + revdate=@GIT_DATE@\n      \n     +ifdef::doctype-book[]\n     +[titles]\n 6:  aaebbf0e94 =  6:  7eaf4f4267 meson: generate user manual\n 7:  1cc7d42a55 =  7:  52b9e4c34b Documentation: refactor \"api-index.sh\" for out-of-tree builds\n 8:  29fbda50a5 =  8:  b9c8e5fe4d Documentation: refactor \"howto-index.sh\" for out-of-tree builds\n 9:  cd7f5ee207 =  9:  1f724c113a meson: generate articles\n10:  d52f3db2bc = 10:  acb6c5f370 meson: install static files for HTML documentation\n -:  ---------- > 11:  2b893f7c0e t/Makefile: make \"check-meson\" work with Dash\n -:  ---------- > 12:  adf4835053 Documentation: wire up sanity checks for Meson\n\n---\nbase-commit: 76cf4f61c87855ebf0784b88aaf737d6b09f504b\nchange-id: 20241212-b4-pks-meson-docs-2634bf3e7764\n\n"},{"id":"509616","messageId":"20241227-b4-pks-meson-docs-v2-1-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 01/12] meson: wire up support for AsciiDoctor","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:29Z","receivedAt":"2024-12-27T14:00:01Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"While our Makefile supports both Asciidoc and AsciiDoctor, our Meson\nbuild instructions only support the former. Wire up support for the\nlatter, as well.\n\nOur Makefile always favors Asciidoc, but Meson will automatically figure\nout which of both to use based on whether they are installed or not. To\nkeep compatibility with our Makefile it favors Asciidoc over Asciidoctor\nin case both are available.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 110 ++++++++++++++++++++++++++++++++++------------\n meson_options.txt         |   2 +\n 2 files changed, 84 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex fca3eab1f1360a5fdeda89c1766ab8cdb3267b89..acd6d86ec779e63230c88b7bff937aff330d2d4f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -204,29 +204,87 @@ manpages = {\n   'gitworkflows.txt' : 7,\n }\n \n-asciidoc = find_program('asciidoc')\n-git = find_program('git', required: false)\n-xmlto = find_program('xmlto')\n+docs_backend = get_option('docs_backend')\n+if docs_backend == 'auto'\n+  if find_program('asciidoc', required: false).found()\n+    docs_backend = 'asciidoc'\n+  elif find_program('asciidoctor', required: false).found()\n+    docs_backend = 'asciidoctor'\n+  else\n+    error('Neither asciidoc nor asciidoctor were found.')\n+  endif\n+endif\n \n-asciidoc_conf = custom_target(\n-  command: [\n-    shell,\n-    meson.project_source_root() / 'GIT-VERSION-GEN',\n-    meson.project_source_root(),\n-    '@INPUT@',\n-    '@OUTPUT@',\n-  ],\n-  input: meson.current_source_dir() / 'asciidoc.conf.in',\n-  output: 'asciidoc.conf',\n-  depends: [git_version_file],\n-  env: version_gen_environment,\n-)\n+if docs_backend == 'asciidoc'\n+  asciidoc = find_program('asciidoc', required: true)\n+  asciidoc_html = 'xhtml11'\n+  asciidoc_docbook = 'docbook'\n+  xmlto_extra = [ ]\n \n-asciidoc_common_options = [\n-  asciidoc,\n-  '--conf-file=' + asciidoc_conf.full_path(),\n-  '--attribute=build_dir=' + meson.current_build_dir(),\n-]\n+  asciidoc_conf = custom_target(\n+    command: [\n+      shell,\n+      meson.project_source_root() / 'GIT-VERSION-GEN',\n+      meson.project_source_root(),\n+      '@INPUT@',\n+      '@OUTPUT@',\n+    ],\n+    input: meson.current_source_dir() / 'asciidoc.conf.in',\n+    output: 'asciidoc.conf',\n+    depends: [git_version_file],\n+    env: version_gen_environment,\n+  )\n+\n+  asciidoc_common_options = [\n+    asciidoc,\n+    '--conf-file=' + asciidoc_conf.full_path(),\n+    '--attribute=build_dir=' + meson.current_build_dir(),\n+  ]\n+\n+  documentation_deps = [\n+    asciidoc_conf,\n+  ]\n+elif docs_backend == 'asciidoctor'\n+  asciidoctor = find_program('asciidoctor', required: true)\n+  asciidoc_html = 'xhtml5'\n+  asciidoc_docbook = 'docbook5'\n+  xmlto_extra = [\n+    '--skip-validation',\n+    '-x', meson.current_source_dir() / 'manpage.xsl',\n+  ]\n+\n+  asciidoctor_extensions = custom_target(\n+    command: [\n+      shell,\n+      meson.project_source_root() / 'GIT-VERSION-GEN',\n+      meson.project_source_root(),\n+      '@INPUT@',\n+      '@OUTPUT@',\n+    ],\n+    input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',\n+    output: 'asciidoctor-extensions.rb',\n+    depends: [git_version_file],\n+    env: version_gen_environment,\n+  )\n+\n+  asciidoc_common_options = [\n+    asciidoctor,\n+    '--attribute', 'compat-mode',\n+    '--attribute', 'tabsize=8',\n+    '--attribute', 'litdd=&#x2d;&#x2d;',\n+    '--attribute', 'docinfo=shared',\n+    '--attribute', 'build_dir=' + meson.current_build_dir(),\n+    '--load-path', meson.current_build_dir(),\n+    '--require', 'asciidoctor-extensions',\n+  ]\n+\n+  documentation_deps = [\n+    asciidoctor_extensions,\n+  ]\n+endif\n+\n+git = find_program('git', required: false)\n+xmlto = find_program('xmlto')\n \n cmd_lists = [\n   'cmds-ancillaryinterrogators.txt',\n@@ -243,10 +301,6 @@ cmd_lists = [\n   'cmds-foreignscminterface.txt',\n ]\n \n-documentation_deps = [\n-  asciidoc_conf,\n-]\n-\n documentation_deps += custom_target(\n   command: [\n     perl,\n@@ -278,7 +332,7 @@ foreach manpage, category : manpages\n   if get_option('docs').contains('man')\n     manpage_xml_target = custom_target(\n       command: asciidoc_common_options + [\n-        '--backend=docbook',\n+        '--backend=' + asciidoc_docbook,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n         meson.current_source_dir() / manpage,\n@@ -301,7 +355,7 @@ foreach manpage, category : manpages\n         manpage_xml_target,\n         '-o',\n         meson.current_build_dir(),\n-      ],\n+      ] + xmlto_extra,\n       output: manpage_path,\n       install: true,\n       install_dir: get_option('mandir') / 'man' + category.to_string(),\n@@ -311,7 +365,7 @@ foreach manpage, category : manpages\n   if get_option('docs').contains('html') and category == 1\n     custom_target(\n       command: asciidoc_common_options + [\n-        '--backend=xhtml11',\n+        '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n         meson.current_source_dir() / manpage,\ndiff --git a/meson_options.txt b/meson_options.txt\nindex 4be7eab39939178ae2ffde1ff9e78f83a1b482b2..f50bb40cdf6046529a0cea0a03a8cb696c3a6b18 100644\n--- a/meson_options.txt\n+++ b/meson_options.txt\n@@ -85,6 +85,8 @@ option('docs', type: 'array', choices: ['man', 'html'], value: [],\n   description: 'Which documenattion formats to build and install.')\n option('default_help_format', type: 'combo', choices: ['man', 'html'], value: 'man',\n   description: 'Default format used when executing git-help(1).')\n+option('docs_backend', type: 'combo', choices: ['asciidoc', 'asciidoctor', 'auto'], value: 'auto',\n+  description: 'Which backend to use to generate documentation.')\n \n # Testing.\n option('tests', type: 'boolean', value: true,\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509617","messageId":"20241227-b4-pks-meson-docs-v2-2-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 02/12] meson: properly wire up dependencies for our docs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:30Z","receivedAt":"2024-12-27T14:00:03Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"A couple of Meson documentation targets use `meson.current_source_dir()`\nto resolve inputs. This has the downside that it does not automagically\nmake Meson track these inputs as a dependency. After all, string\narguments really can be anything, even if they happen to match an actual\nfilesystem path.\n\nAdapt these build targets to instead use inputs.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 26 ++++++++++++++++----------\n 1 file changed, 16 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex acd6d86ec779e63230c88b7bff937aff330d2d4f..b3c8b6c56339e10099f8c37a4d8198f402192520 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -229,7 +229,7 @@ if docs_backend == 'asciidoc'\n       '@INPUT@',\n       '@OUTPUT@',\n     ],\n-    input: meson.current_source_dir() / 'asciidoc.conf.in',\n+    input: 'asciidoc.conf.in',\n     output: 'asciidoc.conf',\n     depends: [git_version_file],\n     env: version_gen_environment,\n@@ -261,7 +261,7 @@ elif docs_backend == 'asciidoctor'\n       '@INPUT@',\n       '@OUTPUT@',\n     ],\n-    input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in',\n+    input: 'asciidoctor-extensions.rb.in',\n     output: 'asciidoctor-extensions.rb',\n     depends: [git_version_file],\n     env: version_gen_environment,\n@@ -304,10 +304,11 @@ cmd_lists = [\n documentation_deps += custom_target(\n   command: [\n     perl,\n-    meson.current_source_dir() / 'cmd-list.perl',\n+    '@INPUT@',\n     meson.project_source_root(),\n     meson.current_build_dir(),\n   ] + cmd_lists,\n+  input: 'cmd-list.perl',\n   output: cmd_lists\n )\n \n@@ -315,7 +316,7 @@ foreach mode : [ 'diff', 'merge' ]\n   documentation_deps += custom_target(\n     command: [\n       shell,\n-      meson.current_source_dir() / 'generate-mergetool-list.sh',\n+      '@INPUT@',\n       '..',\n       'diff',\n       '@OUTPUT@'\n@@ -324,6 +325,7 @@ foreach mode : [ 'diff', 'merge' ]\n       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',\n       'TOOL_MODE=' + mode,\n     ],\n+    input: 'generate-mergetool-list.sh',\n     output: 'mergetools-' + mode + '.txt',\n   )\n endforeach\n@@ -335,9 +337,10 @@ foreach manpage, category : manpages\n         '--backend=' + asciidoc_docbook,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n-        meson.current_source_dir() / manpage,\n+        '@INPUT@',\n       ],\n       depends: documentation_deps,\n+      input: manpage,\n       output: fs.stem(manpage) + '.xml',\n     )\n \n@@ -345,10 +348,8 @@ foreach manpage, category : manpages\n     manpage_target = custom_target(\n       command: [\n         xmlto,\n-        '-m',\n-        meson.current_source_dir() / 'manpage-normal.xsl',\n-        '-m',\n-        meson.current_source_dir() / 'manpage-bold-literal.xsl',\n+        '-m', '@INPUT0@',\n+        '-m', '@INPUT1@',\n         '--stringparam',\n         'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'),\n         'man',\n@@ -356,6 +357,10 @@ foreach manpage, category : manpages\n         '-o',\n         meson.current_build_dir(),\n       ] + xmlto_extra,\n+      input: [\n+        'manpage-normal.xsl',\n+        'manpage-bold-literal.xsl',\n+      ],\n       output: manpage_path,\n       install: true,\n       install_dir: get_option('mandir') / 'man' + category.to_string(),\n@@ -368,9 +373,10 @@ foreach manpage, category : manpages\n         '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n         '--out-file=@OUTPUT@',\n-        meson.current_source_dir() / manpage,\n+        '@INPUT@',\n       ],\n       depends: documentation_deps,\n+      input: manpage,\n       output: fs.stem(manpage) + '.html',\n       install: true,\n       install_dir: get_option('datadir') / 'doc/git-doc',\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509618","messageId":"20241227-b4-pks-meson-docs-v2-3-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 03/12] meson: fix generation of merge tools","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:31Z","receivedAt":"2024-12-27T14:00:05Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our buildsystems generate a list of diff and merge tools that ultimately\nend up in our documentation. And while Meson does wire up the logic, it\ntries to use the TOOL_MODE environment variable to set up the mode. This\nis wrong though: the mode is set via an argument that we have fixed to\n'diff' mode by accident.\n\nFix this such that merge tools are properly generated.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 3 +--\n 1 file changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex b3c8b6c56339e10099f8c37a4d8198f402192520..c2512328ca9b76a5dd512453ddbb776faea7967f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -318,12 +318,11 @@ foreach mode : [ 'diff', 'merge' ]\n       shell,\n       '@INPUT@',\n       '..',\n-      'diff',\n+      mode,\n       '@OUTPUT@'\n     ],\n     env: [\n       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',\n-      'TOOL_MODE=' + mode,\n     ],\n     input: 'generate-mergetool-list.sh',\n     output: 'mergetools-' + mode + '.txt',\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509619","messageId":"20241227-b4-pks-meson-docs-v2-4-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 04/12] meson: generate HTML pages for all man page categories","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:32Z","receivedAt":"2024-12-27T14:00:06Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"When generating HTML pages for our man pages we only generate them for\ncategory 1 in Meson, which are the pages corresponding to our built-in\ncommands. I cannot tell why I added this filter though: our Makefile\ninstalls all man pages, so a Meson-based build misses out on many of\nthem.\n\nFix this by removing the filter.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex c2512328ca9b76a5dd512453ddbb776faea7967f..48583e9a7f4b037de218358f16f59ce08141cbe8 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -366,7 +366,7 @@ foreach manpage, category : manpages\n     )\n   endif\n \n-  if get_option('docs').contains('html') and category == 1\n+  if get_option('docs').contains('html')\n     custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509620","messageId":"20241227-b4-pks-meson-docs-v2-5-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 05/12] Documentation: inline user-manual.conf","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:33Z","receivedAt":"2024-12-27T14:00:08Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"When generating our user manual we set up a bit of extra configuration\ncompared to our normal configuration. This is done by having an extra\n\"user-manual.conf\" file that Asciidoc seems to pull in automatically due\nto matching filenames with \"user-manual.txt\". This dependency is quite\nhidden though and thus easy to miss. Furthermore, it seems that Asciidoc\ndoes not know to pull it in for out-of-tree builds where we use relative\npaths.\n\nThe setup in AsciiDoctor is somewhat different: instead of having two\nsets of configuration, we condition the use of manual-specific configs\nbased on whether the document type is \"book\". And as we only build our\nuser manual with that type this is sufficient.\n\nUse the same trick for our user manual by inlining the configuration\ninto \"asciidoc.conf.in\" and making it conditional on whether or not\n\"doctype-book\" is defined.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile         |  2 +-\n Documentation/asciidoc.conf.in | 10 ++++++++++\n Documentation/user-manual.conf | 11 -----------\n 3 files changed, 11 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex a89823e1d1ee5042367bdcca6ed426196d49ce89..4f152077dded75bedd59abd56db5f6f0693908de 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -362,7 +362,7 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n %.xml : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n \n-user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS)\n+user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n \n technical/api-index.txt: technical/api-index-skel.txt \\\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex b89bccf2309d782ba29ea716a132b888c1421669..f2aef6cb79f47cf132b97d88a7e74fb40da8ac8d 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -25,12 +25,22 @@ manmanual=Git Manual\n mansource=Git @GIT_VERSION@\n revdate=@GIT_DATE@\n \n+ifdef::doctype-book[]\n+[titles]\n+\tunderlines=\"__\",\"==\",\"--\",\"~~\",\"^^\"\n+endif::doctype-book[]\n+\n ifdef::backend-docbook[]\n [linkgit-inlinemacro]\n+ifndef::doctype-book[]\n {0%{target}}\n {0#<citerefentry>}\n {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n {0#</citerefentry>}\n+endif::doctype-book[]\n+ifdef::doctype-book[]\n+<ulink url=\"{target}.html\">{target}{0?({0})}</ulink>\n+endif::doctype-book[]\n \n [literal-inlinemacro]\n {eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\\1</emphasis>', re.sub(r'([\\[\\s|()>]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1<literal>\\2</literal>', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'<literal>\\1</literal>\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\ndiff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf\ndeleted file mode 100644\nindex 0148f126dcdf6aca15a5560fb5b122b85b022461..0000000000000000000000000000000000000000\n--- a/Documentation/user-manual.conf\n+++ /dev/null\n@@ -1,11 +0,0 @@\n-[titles]\n-\tunderlines=\"__\",\"==\",\"--\",\"~~\",\"^^\"\n-\n-[attributes]\n-caret=^\n-startsb=&#91;\n-endsb=&#93;\n-tilde=&#126;\n-\n-[linkgit-inlinemacro]\n-<ulink url=\"{target}.html\">{target}{0?({0})}</ulink>\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509621","messageId":"20241227-b4-pks-meson-docs-v2-6-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 06/12] meson: generate user manual","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:34Z","receivedAt":"2024-12-27T14:00:09Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our documentation contains a user manual that gives people a short\nintroduction to Git. Our Makefile knows to generate the manual into\nthree different formats: an HTML page, a PDF and an info page. The Meson\nbuild instructions don't yet generate any of these.\n\nWhile wiring up all these formats I hit a couple of road blocks with how\nwe generate our info pages. Even though I eventually resolved these, it\nmade me question whether anybody actually uses info pages in the first\nplace. Checking through a couple of downstream consumers I couldn't find\na single user of either the info pages nor of our PDF manual in Arch\nLinux, Debian, Fedora, Ubuntu, FreeBSD or OpenBSDFedora. So it's rather\nsafe to assume that there aren't really any users out there, and thus\nthe added complexity does not seem worth it.\n\nWire up support for building the user manual in HTML format and\nconciously skip over the other two formats. This is basically a form of\nsilent deprecation: if people out there use the other two formats they\nwill eventually complain about them missing in Meson, which means we can\nwire them up at a later point. If they don't we can phase out these\nformats eventually.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 32 ++++++++++++++++++++++++++++++++\n 1 file changed, 32 insertions(+)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 48583e9a7f4b037de218358f16f59ce08141cbe8..404cb20d10a2fbbe4e014bd8a7df74c49dad40a7 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -382,3 +382,35 @@ foreach manpage, category : manpages\n     )\n   endif\n endforeach\n+\n+if get_option('docs').contains('html')\n+  xsltproc = find_program('xsltproc')\n+\n+  user_manual_xml = custom_target(\n+    command: asciidoc_common_options + [\n+      '--backend=' + asciidoc_docbook,\n+      '--doctype=book',\n+      '--out-file=@OUTPUT@',\n+      '@INPUT@',\n+    ],\n+    input: 'user-manual.txt',\n+    output: 'user-manual.xml',\n+    depends: documentation_deps,\n+  )\n+\n+  custom_target(\n+    command: [\n+      xsltproc,\n+      '--xinclude',\n+      '--stringparam', 'html.stylesheet', 'docbook-xsl.css',\n+      '--param', 'generate.consistent.ids', '1',\n+      '--output', '@OUTPUT@',\n+      '@INPUT@',\n+      user_manual_xml,\n+    ],\n+    input: 'docbook.xsl',\n+    output: 'user-manual.html',\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+endif\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509622","messageId":"20241227-b4-pks-meson-docs-v2-7-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 07/12] Documentation: refactor \"api-index.sh\" for out-of-tree builds","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:35Z","receivedAt":"2024-12-27T14:00:10Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The \"api-index.sh\" script generates an index of API-related\ndocumentation. The script does not handle out-of-tree builds and thus\ncannot be used easily by Meson.\n\nRefactor it to be independent of locations by both accepting a source\ndirectory where the API docs live as well as a path to an output file.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile               |  2 +-\n Documentation/technical/api-index.sh | 19 +++++++++++++++----\n 2 files changed, 16 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f152077dded75bedd59abd56db5f6f0693908de..b2d146c44f4ded750b5e0766eb66b25cb5ec08e3 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -367,7 +367,7 @@ user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n-\t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt\n \n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \\\ndiff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh\nindex 9c3f4131b8586408acd81d1e60912b51688575ed..296488557434b7fff60ab25f4246a4dc270729c0 100755\n--- a/Documentation/technical/api-index.sh\n+++ b/Documentation/technical/api-index.sh\n@@ -1,6 +1,17 @@\n #!/bin/sh\n \n+if test $# -ne 2\n+then\n+\techo >&2 \"USAGE: $0 <SOURCE_DIR> <OUTPUT>\"\n+\texit 1\n+fi\n+\n+SOURCE_DIR=\"$1\"\n+OUTPUT=\"$2\"\n+\n (\n+\tcd \"$SOURCE_DIR\"\n+\n \tc=////////////////////////////////////////////////////////////////\n \tskel=api-index-skel.txt\n \tsed -e '/^\\/\\/ table of contents begin/q' \"$skel\"\n@@ -18,11 +29,11 @@\n \tdone\n \techo \"$c\"\n \tsed -n -e '/^\\/\\/ table of contents end/,$p' \"$skel\"\n-) >api-index.txt+\n+) >\"$OUTPUT\"+\n \n-if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null\n+if test -f \"$OUTPUT\" && cmp \"$OUTPUT\" \"$OUTPUT\"+ >/dev/null\n then\n-\trm -f api-index.txt+\n+\trm -f \"$OUTPUT\"+\n else\n-\tmv api-index.txt+ api-index.txt\n+\tmv \"$OUTPUT\"+ \"$OUTPUT\"\n fi\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509623","messageId":"20241227-b4-pks-meson-docs-v2-8-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 08/12] Documentation: refactor \"howto-index.sh\" for out-of-tree builds","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:36Z","receivedAt":"2024-12-27T14:00:11Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The \"howto-index.sh\" is used to generate an index of our how-to docs. It\nreceives as input the paths to these documents, which would typically be\nrelative to the \"Documentation/\" directory in Makefile-based builds. In\nan out-of-tree build though it will get relative that may be rooted\nsomewhere else entirely.\n\nThe file paths do end up in the generated index, and the expectation is\nthat they should always start with \"howto/\". But for out-of-tree builds\nwe would populate it with the paths relative to the build directory,\nwhich is wrong.\n\nFix the issue by using `$(basename \"$file\")` to generate the path. While\nat it, move the script into \"howto/\" to align it with the location of\nthe comparable \"api-index.sh\" script.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/Makefile                   | 4 ++--\n Documentation/{ => howto}/howto-index.sh | 2 +-\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b2d146c44f4ded750b5e0766eb66b25cb5ec08e3..e284ec8b98d6187ecb73011f6e490610dd3e7370 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -411,8 +411,8 @@ gitman.info: gitman.texi\n $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n \t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@\n \n-howto-index.txt: howto-index.sh $(HOWTO_TXT)\n-\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@\n+howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\ndiff --git a/Documentation/howto-index.sh b/Documentation/howto/howto-index.sh\nsimilarity index 92%\nrename from Documentation/howto-index.sh\nrename to Documentation/howto/howto-index.sh\nindex 167b363668b8b53d752d5971798d3ca26c8f7f1f..eecd123a93607998e8b4eb8511f4165973f9d93e 100755\n--- a/Documentation/howto-index.sh\n+++ b/Documentation/howto/howto-index.sh\n@@ -48,7 +48,7 @@ do\n \t\tfile=\"$txt\"\n \tfi\n \n-\techo \"* link:$file[$title] $from\n+\techo \"* link:howto/$(basename \"$file\")[$title] $from\n $abstract\n \n \"\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509626","messageId":"20241227-b4-pks-meson-docs-v2-9-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 09/12] meson: generate articles","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:37Z","receivedAt":"2024-12-27T14:00:11Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"While the Meson build system already knows to generate man pages and our\nuser manual, it does not yet generate the random assortment of articles\nthat we have. Plug this gap.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/howto/meson.build     | 62 ++++++++++++++++++++++++++++++++++\n Documentation/meson.build           | 36 ++++++++++++++++++++\n Documentation/technical/meson.build | 66 +++++++++++++++++++++++++++++++++++++\n 3 files changed, 164 insertions(+)\n\ndiff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build\nnew file mode 100644\nindex 0000000000000000000000000000000000000000..c023c104161e61ca0399b5390d59e20343746621\n--- /dev/null\n+++ b/Documentation/howto/meson.build\n@@ -0,0 +1,62 @@\n+howto_sources = [\n+  'coordinate-embargoed-releases.txt',\n+  'keep-canonical-history-correct.txt',\n+  'maintain-git.txt',\n+  'new-command.txt',\n+  'rebase-from-internal-branch.txt',\n+  'rebuild-from-update-hook.txt',\n+  'recover-corrupted-blob-object.txt',\n+  'recover-corrupted-object-harder.txt',\n+  'revert-a-faulty-merge.txt',\n+  'revert-branch-rebase.txt',\n+  'separating-topic-branches.txt',\n+  'setup-git-server-over-http.txt',\n+  'update-hook-example.txt',\n+  'use-git-daemon.txt',\n+  'using-merge-subtree.txt',\n+  'using-signed-tag-in-pull-request.txt',\n+]\n+\n+howto_index = custom_target(\n+  command: [\n+    shell,\n+    meson.current_source_dir() / 'howto-index.sh',\n+    '@INPUT@',\n+  ],\n+  env: script_environment,\n+  capture: true,\n+  input: howto_sources,\n+  output: 'howto-index.txt',\n+)\n+\n+custom_target(\n+  command: asciidoc_html_options,\n+  input: howto_index,\n+  output: 'howto-index.html',\n+  depends: documentation_deps,\n+  install: true,\n+  install_dir: get_option('datadir') / 'doc/git-doc',\n+)\n+\n+foreach howto : howto_sources\n+  howto_stripped = custom_target(\n+    command: [\n+      find_program('sed'),\n+      '-e',\n+      '1,/^$/d',\n+      '@INPUT@',\n+    ],\n+    input: howto,\n+    output: fs.stem(howto) + '.stripped',\n+    capture: true,\n+  )\n+\n+  custom_target(\n+    command: asciidoc_html_options,\n+    input: howto_stripped,\n+    output: fs.stem(howto_stripped.full_path()) + '.html',\n+    depends: documentation_deps,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc/howto',\n+  )\n+endforeach\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 404cb20d10a2fbbe4e014bd8a7df74c49dad40a7..8c6ff0bce1206d988cc0d3b7997fa0f338d01194 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -413,4 +413,40 @@ if get_option('docs').contains('html')\n     install: true,\n     install_dir: get_option('datadir') / 'doc/git-doc',\n   )\n+\n+  articles = [\n+    'DecisionMaking.txt',\n+    'MyFirstContribution.txt',\n+    'MyFirstObjectWalk.txt',\n+    'ReviewingGuidelines.txt',\n+    'SubmittingPatches',\n+    'ToolsForGit.txt',\n+    'git-bisect-lk2009.txt',\n+    'git-tools.txt',\n+  ]\n+\n+  foreach article : articles\n+    custom_target(\n+      command: asciidoc_common_options + [\n+        '--backend=' + asciidoc_html,\n+        '--out-file=@OUTPUT@',\n+        '@INPUT@',\n+      ],\n+      input: article,\n+      output: fs.stem(article) + '.html',\n+      depends: documentation_deps,\n+      install: true,\n+      install_dir: get_option('datadir') / 'doc/git-doc',\n+    )\n+  endforeach\n+\n+  asciidoc_html_options = asciidoc_common_options + [\n+    '--backend=' + asciidoc_html,\n+    '--out-file=@OUTPUT@',\n+    '--attribute', 'git-relative-html-prefix=../',\n+    '@INPUT@',\n+  ]\n+\n+  subdir('howto')\n+  subdir('technical')\n endif\ndiff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build\nnew file mode 100644\nindex 0000000000000000000000000000000000000000..21dfb8b5c9d93490f16c24bab1d49631e0395571\n--- /dev/null\n+++ b/Documentation/technical/meson.build\n@@ -0,0 +1,66 @@\n+api_docs = [\n+  'api-error-handling.txt',\n+  'api-merge.txt',\n+  'api-parse-options.txt',\n+  'api-simple-ipc.txt',\n+  'api-trace2.txt',\n+]\n+\n+articles = [\n+  'bitmap-format.txt',\n+  'build-systems.txt',\n+  'bundle-uri.txt',\n+  'commit-graph.txt',\n+  'directory-rename-detection.txt',\n+  'hash-function-transition.txt',\n+  'long-running-process-protocol.txt',\n+  'multi-pack-index.txt',\n+  'packfile-uri.txt',\n+  'pack-heuristics.txt',\n+  'parallel-checkout.txt',\n+  'partial-clone.txt',\n+  'platform-support.txt',\n+  'racy-git.txt',\n+  'reftable.txt',\n+  'remembering-renames.txt',\n+  'repository-version.txt',\n+  'rerere.txt',\n+  'scalar.txt',\n+  'send-pack-pipeline.txt',\n+  'shallow.txt',\n+  'sparse-checkout.txt',\n+  'sparse-index.txt',\n+  'trivial-merge.txt',\n+  'unit-tests.txt',\n+]\n+\n+api_index = custom_target(\n+  command: [\n+    shell,\n+    meson.current_source_dir() / 'api-index.sh',\n+    meson.current_source_dir(),\n+    '@OUTPUT@',\n+  ],\n+  env: script_environment,\n+  input: api_docs,\n+  output: 'api-index.txt',\n+)\n+\n+custom_target(\n+  command: asciidoc_html_options,\n+  input: api_index,\n+  output: 'api-index.html',\n+  depends: documentation_deps,\n+  install: true,\n+  install_dir: get_option('datadir') / 'doc/git-doc/technical',\n+)\n+\n+foreach article : api_docs + articles\n+  custom_target(\n+    command: asciidoc_html_options,\n+    input: article,\n+    output: fs.stem(article) + '.html',\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc/technical',\n+  )\n+endforeach\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509624","messageId":"20241227-b4-pks-meson-docs-v2-10-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 10/12] meson: install static files for HTML documentation","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:38Z","receivedAt":"2024-12-27T14:00:12Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Now that we generate man pages, articles and user manual with Meson the\nonly thing that is still missing in an installation of HTML documents is\na couple of static files. Wire these up to finalize Meson's support for\ngenerating HTML documentation.\n\nDiffing an installation that uses our Makefile with an installation that\nuses Meson only surfaces a couple of discepancies now:\n\n  - Meson doesn't install \"everyday.html\" and \"git-remote-helpers.html\".\n    These files are marked as obsolete and don't contain any useful\n    information anymore: they simply point to their modern equivalents.\n\n  - Meson doesn't install \"*.txt\" files when asking for HTML docs. I'm\n    not sure why our Makefiles do this in the first place, and it does\n    seem like the resulting installation is fully functional even\n    without those files.\n\nOther than that, both layout and file contents are the exact same.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/meson.build | 21 +++++++++++++++++++++\n 1 file changed, 21 insertions(+)\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 8c6ff0bce1206d988cc0d3b7997fa0f338d01194..4d9511156502653292144fe6962bd3411558d96a 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -384,6 +384,27 @@ foreach manpage, category : manpages\n endforeach\n \n if get_option('docs').contains('html')\n+  configure_file(\n+    input: 'docinfo-html.in',\n+    output: 'docinfo.html',\n+    copy: true,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+\n+  configure_file(\n+    input: 'docbook-xsl.css',\n+    output: 'docbook-xsl.css',\n+    copy: true,\n+    install: true,\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+  )\n+\n+  install_symlink('index.html',\n+    install_dir: get_option('datadir') / 'doc/git-doc',\n+    pointing_to: 'git.html',\n+  )\n+\n   xsltproc = find_program('xsltproc')\n \n   user_manual_xml = custom_target(\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509625","messageId":"20241227-b4-pks-meson-docs-v2-11-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 11/12] t/Makefile: make \"check-meson\" work with Dash","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:39Z","receivedAt":"2024-12-27T14:00:13Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The \"check-meson\" target uses process substitution to check whether\nextracted contents from \"meson.build\" match expected contents. Process\nsubstitution is unportable though and thus the target will fail when\nusing for example Dash.\n\nFix this by writing data into a temporary directory.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n t/.gitignore |  1 +\n t/Makefile   | 12 +++++++-----\n 2 files changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/t/.gitignore b/t/.gitignore\nindex 91cf5772fe5643dbe075da98ed5166e1899b9a54..3e6b0f2cc57ffed0394d1cd2efc1e374f1c2169b 100644\n--- a/t/.gitignore\n+++ b/t/.gitignore\n@@ -2,4 +2,5 @@\n /test-results\n /.prove\n /chainlinttmp\n+/mesontmp\n /out/\ndiff --git a/t/Makefile b/t/Makefile\nindex 290fb03ff011d39c31c5073c796aa6f4dc966283..daa5fcae86f3480079b8c9743dd28e3fd304c27b 100644\n--- a/t/Makefile\n+++ b/t/Makefile\n@@ -103,6 +103,7 @@ clean-except-prove-cache: clean-chainlint\n \n clean: clean-except-prove-cache\n \t$(RM) -r '$(TEST_RESULTS_DIRECTORY_SQ)'\n+\t$(RM) -r mesontmp\n \t$(RM) .prove\n \n clean-chainlint:\n@@ -116,16 +117,17 @@ check-chainlint:\n \n check-meson:\n \t@# awk acts up when trying to match single quotes, so we use \\047 instead.\n-\t@printf \"%s\\n\" \\\n+\t@mkdir -p mesontmp && \\\n+\tprintf \"%s\\n\" \\\n \t\t\"integration_tests t[0-9][0-9][0-9][0-9]-*.sh\" \\\n \t\t\"unit_test_programs unit-tests/t-*.c\" \\\n \t\t\"clar_test_suites unit-tests/u-*.c\" | \\\n \twhile read -r variable pattern; do \\\n-\t\tmeson_tests=$$(awk \"/^$$variable = \\[\\$$/ {flag=1 ; next } /^]$$/ { flag=0 } flag { gsub(/^  \\047/, \\\"\\\"); gsub(/\\047,\\$$/, \\\"\\\"); print }\" meson.build) && \\\n-\t\tactual_tests=$$(ls $$pattern) && \\\n-\t\tif test \"$$meson_tests\" != \"$$actual_tests\"; then \\\n+\t\tawk \"/^$$variable = \\[\\$$/ {flag=1 ; next } /^]$$/ { flag=0 } flag { gsub(/^  \\047/, \\\"\\\"); gsub(/\\047,\\$$/, \\\"\\\"); print }\" meson.build >mesontmp/meson.txt && \\\n+\t\tls $$pattern >mesontmp/actual.txt && \\\n+\t\tif ! cmp mesontmp/meson.txt mesontmp/actual.txt; then \\\n \t\t\techo \"Meson tests differ from actual tests:\"; \\\n-\t\t\tdiff -u <(echo \"$$meson_tests\") <(echo \"$$actual_tests\"); \\\n+\t\t\tdiff -u mesontmp/meson.txt mesontmp/actual.txt; \\\n \t\t\texit 1; \\\n \t\tfi; \\\n \tdone\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509627","messageId":"20241227-b4-pks-meson-docs-v2-12-f61e63edbfa1@pks.im","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-0-f61e63edbfa1@pks.im","subject":"[PATCH v2 12/12] Documentation: wire up sanity checks for Meson","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-27T13:59:40Z","receivedAt":"2024-12-27T14:00:13Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Wire up sanity checks for Meson to verify that no man pages are missing.\nThis check is similar to the same check we already have for our tests.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/.gitignore  |  1 +\n Documentation/Makefile    | 16 ++++++++++++++++\n Documentation/meson.build | 31 +++++++++++++++++++++++++++++++\n 3 files changed, 48 insertions(+)\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex 649df89474d357ccc91109b5c35fe2d0910f968a..9f4bb3c4bf9e9e84f740b3210c570ec25e15e4fe 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -12,6 +12,7 @@ cmds-*.txt\n mergetools-*.txt\n SubmittingPatches.txt\n tmp-doc-diff/\n+tmp-meson-diff/\n GIT-ASCIIDOCFLAGS\n /.build/\n /GIT-EXCLUDED-PROGRAMS\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e284ec8b98d6187ecb73011f6e490610dd3e7370..aedfe99d1d35889aa24ed6b9085e614dbc240096 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -339,6 +339,7 @@ clean:\n \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n \t$(RM) GIT-ASCIIDOCFLAGS\n \t$(RM) asciidoc.conf asciidoctor-extensions.rb\n+\t$(RM) -rf tmp-meson-diff\n \n docinfo.html: docinfo-html.in\n \t$(QUIET_GEN)$(RM) $@ && cat $< >$@\n@@ -494,6 +495,20 @@ lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)\n lint-docs-manpages:\n \t$(QUIET_GEN)./lint-manpages.sh\n \n+.PHONY: lint-docs-meson\n+lint-docs-meson:\n+\t@# awk acts up when trying to match single quotes, so we use \\047 instead.\n+\t@mkdir -p tmp-meson-diff && \\\n+\tawk \"/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^  \\047/, \\\"\\\"); gsub(/\\047 : [157],\\$$/, \\\"\\\"); print }\" meson.build | \\\n+\t\tgrep -v -e '#' -e '^$$' | \\\n+\t\tsort >tmp-meson-diff/meson.txt && \\\n+\tls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \\\n+\tif ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \\\n+\t\techo \"Meson man pages differ from actual man pages:\"; \\\n+\t\tdiff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \\\n+\t\texit 1; \\\n+\tfi\n+\n ## Lint: list of targets above\n .PHONY: lint-docs\n lint-docs: lint-docs-fsck-msgids\n@@ -501,6 +516,7 @@ lint-docs: lint-docs-gitlink\n lint-docs: lint-docs-man-end-blurb\n lint-docs: lint-docs-man-section-order\n lint-docs: lint-docs-manpages\n+lint-docs: lint-docs-meson\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 4d9511156502653292144fe6962bd3411558d96a..2a26fa8a5fedc0f46a82fcc31bf1d6457f6d082c 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -471,3 +471,34 @@ if get_option('docs').contains('html')\n   subdir('howto')\n   subdir('technical')\n endif\n+\n+# Sanity check that we are not missing any tests present in 't/'. This check\n+# only runs once at configure time and is thus best-effort, only. Furthermore,\n+# it only verifies man pages for the sake of simplicity.\n+configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.txt', 'git-tools.txt' ]\n+actual_manpages = run_command(shell, '-c', 'ls git*.txt scalar.txt',\n+  check: true,\n+  env: script_environment,\n+).stdout().strip().split('\\n')\n+\n+if configured_manpages != actual_manpages\n+  missing_manpage = [ ]\n+  foreach actual_manpage : actual_manpages\n+    if actual_manpage not in configured_manpages\n+      missing_manpage += actual_manpage\n+    endif\n+  endforeach\n+  if missing_manpage.length() > 0\n+    error('Man page found, but not configured:\\n\\n - ' + '\\n - '.join(missing_manpage))\n+  endif\n+\n+  superfluous_manpage = [ ]\n+  foreach configured_manpage : configured_manpages\n+    if configured_manpage not in actual_manpages\n+      superfluous_manpage += configured_manpage\n+    endif\n+  endforeach\n+  if superfluous_manpage.length() > 0\n+    error('Man page configured, but not found:\\n\\n - ' + '\\n - '.join(superfluous_manpage))\n+  endif\n+endif\n\n-- \n2.48.0.rc0.311.gb6c66824c1.dirty\n\n"},{"id":"509803","messageId":"Z3ayzUEfW1xd4Up0@google.com","threadId":"62634","inReplyTo":"20241227-b4-pks-meson-docs-v2-11-f61e63edbfa1@pks.im","subject":"Re: [PATCH v2 11/12] t/Makefile: make \"check-meson\" work with Dash","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2025-01-02T15:37:49Z","receivedAt":"2025-01-02T15:37:52Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nPatrick Steinhardt wrote:\n\n> The \"check-meson\" target uses process substitution to check whether\n> extracted contents from \"meson.build\" match expected contents. Process\n> substitution is unportable though and thus the target will fail when\n> using for example Dash.\n>\n> Fix this by writing data into a temporary directory.\n>\n> Signed-off-by: Patrick Steinhardt <ps@pks.im>\n> ---\n>  t/.gitignore |  1 +\n>  t/Makefile   | 12 +++++++-----\n>  2 files changed, 8 insertions(+), 5 deletions(-)\n\nWithout this, I get the error described in\nhttps://lore.kernel.org/git/CAHWeT-boK3x6mup11boEinNDQiAxxf0vwvZkxsGRc_GRvXYA8g@mail.gmail.com/\n('/bin/sh: 10: Syntax error: \"(\" unexpected'), and with this, the\nbuild in the Debian buildd environment succeeds.\n\nTested-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks for fixing it.\n\nSincerely,\nJonathan\n"},{"id":"509806","messageId":"xmqqikqxussh.fsf@gitster.g","threadId":"62634","inReplyTo":"Z3ayzUEfW1xd4Up0@google.com","subject":"Re: [PATCH v2 11/12] t/Makefile: make \"check-meson\" work with Dash","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-02T15:41:50Z","receivedAt":"2025-01-02T15:41:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Without this, I get the error described in\n> https://lore.kernel.org/git/CAHWeT-boK3x6mup11boEinNDQiAxxf0vwvZkxsGRc_GRvXYA8g@mail.gmail.com/\n> ('/bin/sh: 10: Syntax error: \"(\" unexpected'), and with this, the\n> build in the Debian buildd environment succeeds.\n>\n> Tested-by: Jonathan Nieder <jrnieder@gmail.com>\n>\n> Thanks for fixing it.\n\nThanks.\n"},{"id":"509815","messageId":"xmqq1pxku5hd.fsf@gitster.g","threadId":"62634","inReplyTo":"xmqqikqxussh.fsf@gitster.g","subject":"Re: [PATCH v2 11/12] t/Makefile: make \"check-meson\" work with Dash","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-03T00:05:18Z","receivedAt":"2025-01-03T00:05:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Jonathan Nieder <jrnieder@gmail.com> writes:\n>\n>> Without this, I get the error described in\n>> https://lore.kernel.org/git/CAHWeT-boK3x6mup11boEinNDQiAxxf0vwvZkxsGRc_GRvXYA8g@mail.gmail.com/\n>> ('/bin/sh: 10: Syntax error: \"(\" unexpected'), and with this, the\n>> build in the Debian buildd environment succeeds.\n>>\n>> Tested-by: Jonathan Nieder <jrnieder@gmail.com>\n>>\n>> Thanks for fixing it.\n>\n> Thanks.\n\nNow the fix is in 'master'.\n\nThanks, all.\n"},{"id":"509828","messageId":"874j2gl46v.fsf@iotcl.com","threadId":"62634","inReplyTo":"Z26ygb_4-DP7Ufab@pks.im","subject":"Re: How to use Meson (was: [PATCH 00/10] meson: wire up missing HTML documentation])","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2025-01-03T07:58:00Z","receivedAt":"2025-01-03T07:58:22Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> I don't really think it makes sense to explicitly point out every\n> option that we have. We already document how to discover and set\n> options, and from hereon it follows that you can wire up docs by\n> running for example `meson setup -Ddocs=man ..`. It's just another\n> option, and as such it can be discovered by running `meson configure`.\n\nThis is something I wasn't aware of. Because I'm used to the Makefile\nworkflow and I'm not familiar with Meson, I didn't expect it to work\nlike that.\n\n> The benefit of this is that it cannot grow stale like the build options\n> in our Makefile. These may or may not have documentation, and may or may\n> not be stale. With Meson, every build option is listed explicitly, has\n> documentation and is discoverable via `meson configure`.\n\nThat's awesome, and I totally I agree we use the benefit of this\nself-documenting feature of Meson. Again, I didn't know about that. It's\nmore of a me-problem than with your code.\n\n> Yup, you are always expected to set up the top-level source directory,\n> not any of the subdirectories. The build instructions are then processed\n> linearly in Meson, so variables declared before a call to `subdir()`\n> would be accessible in the subdirectory, as well.\n\nWith Makefiles I can build individual targets (like `make docs`), or run\n`make` in the docs/ subdir, is something like that also possible with\nMeson? Or are you always configuring what to build in `meson configure`\nand building all that with `meson compile`?\n\n-- \nToon\n"},{"id":"509833","messageId":"Z3ehR4uaG_j3iWy7@pks.im","threadId":"62634","inReplyTo":"874j2gl46v.fsf@iotcl.com","subject":"Re: How to use Meson (was: [PATCH 00/10] meson: wire up missing HTML documentation])","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-01-03T08:35:29Z","receivedAt":"2025-01-03T08:35:34Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Jan 03, 2025 at 08:58:00AM +0100, Toon Claes wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> > Yup, you are always expected to set up the top-level source directory,\n> > not any of the subdirectories. The build instructions are then processed\n> > linearly in Meson, so variables declared before a call to `subdir()`\n> > would be accessible in the subdirectory, as well.\n> \n> With Makefiles I can build individual targets (like `make docs`), or run\n> `make` in the docs/ subdir, is something like that also possible with\n> Meson? Or are you always configuring what to build in `meson configure`\n> and building all that with `meson compile`?\n\nYou can in theory. It's already possible to build individual parts of\nGit, e.g.:\n\n    # We need to discern these two `git` targets because the same name\n    # is defined once as a static library and once as an executable.\n    $ meson compile git:static_library\n    $ meson compile git:executable\n    $ meson compile Documentation/git-add.1\n\nWe can also have a target equivalent to `make docs` by adding\n`alias_target()`s to Meson. I ain't got these wired up yet, but it could\nlook like the patch at the end of this mail. And then you can simply say\n`meson compile docs`. It does require you to have docs configured\nthough, otherwise the 'Documentation/' subdirectory does not get pulled\nincluded in the first place.\n\nPatrick\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 2a26fa8a5f..4f8e2e7ebb 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -204,6 +204,8 @@ manpages = {\n   'gitworkflows.txt' : 7,\n }\n \n+docs_target = []\n+\n docs_backend = get_option('docs_backend')\n if docs_backend == 'auto'\n   if find_program('asciidoc', required: false).found()\n@@ -364,10 +366,12 @@ foreach manpage, category : manpages\n       install: true,\n       install_dir: get_option('mandir') / 'man' + category.to_string(),\n     )\n+\n+    docs_target += manpage_target\n   endif\n \n   if get_option('docs').contains('html')\n-    custom_target(\n+    docs_target += custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n@@ -419,7 +423,7 @@ if get_option('docs').contains('html')\n     depends: documentation_deps,\n   )\n \n-  custom_target(\n+  docs_target += custom_target(\n     command: [\n       xsltproc,\n       '--xinclude',\n@@ -447,7 +451,7 @@ if get_option('docs').contains('html')\n   ]\n \n   foreach article : articles\n-    custom_target(\n+    docs_target += custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n         '--out-file=@OUTPUT@',\n@@ -502,3 +506,5 @@ if configured_manpages != actual_manpages\n     error('Man page configured, but not found:\\n\\n - ' + '\\n - '.join(superfluous_manpage))\n   endif\n endif\n+\n+alias_target('docs', docs_target)\n"}]}