From 9219325be74c35c493a61ab3107d215cad91cf38 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 6 Dec 2024 14:24:53 +0100 Subject: Documentation: allow sourcing generated includes from separate dir Our documentation uses "include::" directives to include parts that are either reused across multiple documents or parts that we generate at build time. Unfortunately, top-level includes are only ever resolved relative to the base directory, which is typically the directory of the including document. Most importantly, it is not possible to have either asciidoc or asciidoctor search multiple directories. It follows that both kinds of includes must live in the same directory. This is of course a bummer for out-of-tree builds, because here the dynamically-built includes live in the build directory whereas the static includes live in the source directory. Introduce a `build_dir` attribute and prepend it to all of our includes for dynamically-built files. This attribute gets set to the build directory and thus converts the include path to an absolute path, which asciidoc and asciidoctor know how to resolve. Note that this change also requires us to update "build-docdep.perl", which tries to figure out included files such our Makefile can set up proper build-time dependencies. This script simply scans through the source files for any lines that match "^include::" and treats the remainder of the line as included file path. But given that those may now contain the "{build_dir}" variable we have to teach the script to replace that attribute with the actual build directory. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/config/diff.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/config/diff.txt') diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 45f3fe855c..fdae13a212 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -218,7 +218,7 @@ endif::git-diff[] Set this option to `true` to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. -include::../mergetools-diff.txt[] +include::{build_dir}/mergetools-diff.txt[] `diff.indentHeuristic`:: Set this option to `false` to disable the default heuristics -- cgit v1.3 From 21e1b4486586d3a15d2d7bf0479e77636359b816 Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Wed, 8 Jan 2025 23:35:23 +0000 Subject: difftool docs: restore correct position of tool list 2a9dfdf260 (difftool docs: de-duplicate configuration sections, 2022-09-07) moved the difftool documentation, but missed moving this "include" line that includes the generated list of diff tools, as referenced in the moved text. Restore the correct position of the included list. Signed-off-by: Adam Johnson Signed-off-by: Junio C Hamano --- Documentation/config/diff.txt | 2 -- Documentation/config/difftool.txt | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/config/diff.txt') diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index fdae13a212..1135a62a0a 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -218,8 +218,6 @@ endif::git-diff[] Set this option to `true` to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. -include::{build_dir}/mergetools-diff.txt[] - `diff.indentHeuristic`:: Set this option to `false` to disable the default heuristics that shift diff hunk boundaries to make patches easier to read. diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt index 447c40d85a..6cd47331a9 100644 --- a/Documentation/config/difftool.txt +++ b/Documentation/config/difftool.txt @@ -13,6 +13,8 @@ diff.guitool:: and requires that a corresponding difftool..cmd variable is defined. +include::{build_dir}/mergetools-diff.txt[] + difftool..cmd:: Specify the command to invoke the specified diff tool. The specified command is evaluated in shell with the following -- cgit v1.3