From patchwork Thu Oct 24 12:40:21 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13848899 Received: from fout-b5-smtp.messagingengine.com (fout-b5-smtp.messagingengine.com [202.12.124.148]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DBCE41D5AD7 for ; Thu, 24 Oct 2024 12:40:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=202.12.124.148 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729773631; cv=none; b=sUjX2m/y5pXRtDdOvg6jFIX/YnEIY3TqGoZyYKENqtrL/T8C2to07Thuguo9R86oaHdpRn0o8f7OQjQc6i7jTWgb5FTlVGUXti2s1kO2mOApAnr5aYPMhOZFVz50yMtZ5iD+X9ehpCf0d0ie93oHK/ybCVpHl4ORGutp140/AS4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729773631; c=relaxed/simple; bh=pt7/pTT9PXEsukJfwIRcMGe4Ex9FDUwORgjV5BnOdO4=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=BeIt4fspf6Myowwp2Od5jbq5olZTHn7Ndd0vgiZeiIutiAiH6eVkbEd4bAEULjImrDWAIC6ev2YLfl9vVIGKzQ8BEUFdHSEdRWJNeT4pe0jdQxO8fZgVCCTFCopLwG+PLGyyKp1JG2iF0EIYA790Wzyc99JvwOwwaulAR2gqDNQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=SBog2ePV; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=Ehi1XbOB; arc=none smtp.client-ip=202.12.124.148 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="SBog2ePV"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="Ehi1XbOB" Received: from phl-compute-03.internal (phl-compute-03.phl.internal [10.202.2.43]) by mailfout.stl.internal (Postfix) with ESMTP id 625F9114012A; Thu, 24 Oct 2024 08:40:27 -0400 (EDT) Received: from phl-mailfrontend-01 ([10.202.2.162]) by phl-compute-03.internal (MEProxy); Thu, 24 Oct 2024 08:40:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1729773627; x=1729860027; bh=7oUtyybFmx s61IyYfgd4+qxFxXg2gaGiAP6Uy2giNfo=; b=SBog2ePVsIPs62i7we8OFTDKof C/SGkmik/SNBrDenzJZyLqkJxZhTQkis6ck3hpITa//7SGQ+lmbI5pkEmLImbKjn i0WTg+yO60LtRSzPGnw4G3WHOVIM7ahuZ01AqSC5eDxiCWEn9n4SRb95vUQml26C fJSrn4uur6zamRwgB+s/lR8u0olpMNaHvnGm6C5rkg35Phe/awRkeWm3iYwEpjb0 xDWGeXsi3VY28+Y8rm8lDVMXFjyGCIdW7kzFdkRfZbhK+D4829QmVFZMTA/gCknb emS+j39pyJIrn7Ny40TdF5TkCsIDbRFNuu3WvAK10gLb/20L9p1oaKDfkq+w== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1729773627; x=1729860027; bh=7oUtyybFmxs61IyYfgd4+qxFxXg2 gaGiAP6Uy2giNfo=; b=Ehi1XbOBc5IcuGUC6uW1X+/z24BYKfdsysN0aNYhmPM6 3ovgX64NEeiR6KJVNXbrmJsPE/0ZA5DkKunXGI0shHh2NOaUbs5G8s71EasBoKvV HWfJUAwTZqChP0qMhE6lVrT8Xn+4tG/kDrt1mnM8v0x1TFcSzU9ij5svtyNbQ1UK o0KbHL6Mjvknivf8DNe0RAj7j4Eqm7t62zkAXJz66QeZyJ79DsW7yweQg7iAvrQX 37rTMAbE/2BX8AHmWxzmFh05d9CfguU/G0Db2z8x2YpoNf0ODnYY7Vg1jU8gmXLu 8+Th6urXCY9jyTlzRyNFdkdRW/ELP+qqX/wrfPplfA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrvdejtddgvdelucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdggtfgfnhhsuhgsshgtrhhisggvpdfu rfetoffkrfgpnffqhgenuceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnh htshculddquddttddmnecujfgurhepfffhvfevuffkfhggtggujgesthdtredttddtvden ucfhrhhomheprfgrthhrihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimh eqnecuggftrfgrthhtvghrnhepveekkeffhfeitdeludeigfejtdetvdelvdduhefgueeg udfghfeukefhjedvkedtnecuvehluhhsthgvrhfuihiivgepfeenucfrrghrrghmpehmrg hilhhfrhhomhepphhssehpkhhsrdhimhdpnhgspghrtghpthhtohepjedpmhhouggvpehs mhhtphhouhhtpdhrtghpthhtohepmhgvsehtthgrhihlohhrrhdrtghomhdprhgtphhtth hopegvshgthhifrghrthiisehgvghnthhoohdrohhrghdprhgtphhtthhopehsuhhnshhh ihhnvgesshhunhhshhhinhgvtghordgtohhmpdhrtghpthhtoheprhgrmhhsrgihsehrrg hmshgrhihjohhnvghsrdhplhhushdrtghomhdprhgtphhtthhopehphhhilhhlihhprdif ohhougduvdefsehgmhgrihhlrdgtohhmpdhrtghpthhtohepghhithhsthgvrhesphhosg hogidrtghomhdprhgtphhtthhopehgihhtsehvghgvrhdrkhgvrhhnvghlrdhorhhg X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu, 24 Oct 2024 08:40:25 -0400 (EDT) Received: by vm-mail (OpenSMTPD) with ESMTPSA id afd6b122 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Thu, 24 Oct 2024 12:40:28 +0000 (UTC) Date: Thu, 24 Oct 2024 14:40:21 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Eli Schwartz , Eric Sunshine , Phillip Wood , Junio C Hamano , Ramsay Jones , Taylor Blau Subject: [RFC PATCH v4 12/19] Documentation: allow sourcing generated includes from separate dir Message-ID: References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: 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 --- Documentation/Makefile | 3 ++- Documentation/build-docdep.perl | 2 ++ Documentation/config/diff.txt | 2 +- Documentation/config/merge.txt | 2 +- Documentation/git.txt | 24 ++++++++++++------------ 5 files changed, 18 insertions(+), 15 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 0f55baa252f..75755ceec18 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -218,6 +218,7 @@ SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ASCIIDOC_EXTRA += -abuild_dir='$(shell pwd)' ifdef DEFAULT_PAGER DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' @@ -283,7 +284,7 @@ docdep_prereqs = \ cmd-list.made $(cmds_txt) doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl - $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR) + $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl "$(shell pwd)" >$@ $(QUIET_STDERR) ifneq ($(MAKECMDGOALS),clean) -include doc.dep diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl index 1b3ac8fdd95..315efaa2fa2 100755 --- a/Documentation/build-docdep.perl +++ b/Documentation/build-docdep.perl @@ -1,5 +1,6 @@ #!/usr/bin/perl +my ($build_dir) = @ARGV; my %include = (); my %included = (); @@ -10,6 +11,7 @@ chomp; s/^include::\s*//; s/\[\]//; + s/{build_dir}/${build_dir}/; $include{$text}{$_} = 1; $included{$_} = 1; } diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 190bda17e51..9575af91fa5 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -206,7 +206,7 @@ diff..cachetextconv:: 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 diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 8851b6cedef..82554d65a0a 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -101,7 +101,7 @@ merge.guitool:: Any other value is treated as a custom merge tool and requires that a corresponding mergetool..cmd variable is defined. -include::../mergetools-merge.txt[] +include::{build_dir}/mergetools-merge.txt[] merge.verbosity:: Controls the amount of output shown by the recursive merge diff --git a/Documentation/git.txt b/Documentation/git.txt index d15a8697625..44f0797ccff 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -245,17 +245,17 @@ ancillary user utilities. Main porcelain commands ~~~~~~~~~~~~~~~~~~~~~~~ -include::cmds-mainporcelain.txt[] +include::{build_dir}/cmds-mainporcelain.txt[] Ancillary Commands ~~~~~~~~~~~~~~~~~~ Manipulators: -include::cmds-ancillarymanipulators.txt[] +include::{build_dir}/cmds-ancillarymanipulators.txt[] Interrogators: -include::cmds-ancillaryinterrogators.txt[] +include::{build_dir}/cmds-ancillaryinterrogators.txt[] Interacting with Others @@ -264,7 +264,7 @@ Interacting with Others These commands are to interact with foreign SCM and with other people via patch over e-mail. -include::cmds-foreignscminterface.txt[] +include::{build_dir}/cmds-foreignscminterface.txt[] Reset, restore and revert ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -313,13 +313,13 @@ repositories. Manipulation commands ~~~~~~~~~~~~~~~~~~~~~ -include::cmds-plumbingmanipulators.txt[] +include::{build_dir}/cmds-plumbingmanipulators.txt[] Interrogation commands ~~~~~~~~~~~~~~~~~~~~~~ -include::cmds-plumbinginterrogators.txt[] +include::{build_dir}/cmds-plumbinginterrogators.txt[] In general, the interrogate commands do not touch the files in the working tree. @@ -328,12 +328,12 @@ the working tree. Syncing repositories ~~~~~~~~~~~~~~~~~~~~ -include::cmds-synchingrepositories.txt[] +include::{build_dir}/cmds-synchingrepositories.txt[] The following are helper commands used by the above; end users typically do not use them directly. -include::cmds-synchelpers.txt[] +include::{build_dir}/cmds-synchelpers.txt[] Internal helper commands @@ -342,14 +342,14 @@ Internal helper commands These are internal helper commands used by other commands; end users typically do not use them directly. -include::cmds-purehelpers.txt[] +include::{build_dir}/cmds-purehelpers.txt[] Guides ------ The following documentation pages are guides about Git concepts. -include::cmds-guide.txt[] +include::{build_dir}/cmds-guide.txt[] Repository, command and file interfaces --------------------------------------- @@ -358,7 +358,7 @@ This documentation discusses repository and command interfaces which users are expected to interact with directly. See `--user-formats` in linkgit:git-help[1] for more details on the criteria. -include::cmds-userinterfaces.txt[] +include::{build_dir}/cmds-userinterfaces.txt[] File formats, protocols and other developer interfaces ------------------------------------------------------ @@ -367,7 +367,7 @@ This documentation discusses file formats, over-the-wire protocols and other git developer interfaces. See `--developer-interfaces` in linkgit:git-help[1]. -include::cmds-developerinterfaces.txt[] +include::{build_dir}/cmds-developerinterfaces.txt[] Configuration Mechanism -----------------------