Hi Junio, On Mon, 22 Jul 2024, Junio C Hamano wrote: > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 78e407e4bd..371d56eb5e 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation > XMLTO_EXTRA += -x manpage.xsl > endif > > +ASCIIDOC_DEPS += docinfo.html > + > SHELL_PATH ?= $(SHELL) > # Shell quote; > SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) > @@ -337,6 +339,9 @@ clean: > $(RM) $(cmds_txt) $(mergetools_txt) *.made > $(RM) GIT-ASCIIDOCFLAGS > > +docinfo.html: docinfo-html.in > + $(QUIET_GEN)$(RM) $@ && cat $< >$@ > + > $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS) > $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $< > Hmm. This adds a "template" for no other reason than to appease the rule that all `.html` files in `Documentation/` _must_ be generated. Typically, templates are only added if anything in them needs to be interpolated to reflect the particular build, which is not the case here. Have you considered one of these alternatives? 1. https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-extend talks about two ways to extend the default style sheet that do _not_ need to add an `.html` file: a. add a `.css` file instead that `@import`s AsciiDoctor's default style sheet from a CDN. Upside: it is very clean, short, does not need any Makefile rule to generate a file that is arguable in no need of being generated. Downside: since the `@import` statement cannot refer to a file in the same directory as the `.css` file, it incurs a web request. This would prevent the build from working on an air-gapped system (such as when on a beautiful island without internet access). b. generate a `.css` file by merging AsciiDoctor's default style sheet with a small CSS snippet. Upside: it is again very clean. Downside: this would now require a Makefile rule when previously we managed without one. 2. simply adjust the `check_unignored_build_artifacts()` function to know about `docinfo.html`. Upside: it is still short and does not need any Makefile rule where previously no such thing was required. Downside: the simple rule "all .html files in Documentation/ _must_ be generated" would no longer hold true, making the architecture slightly harder to explain to newcomers. 3. stop mixing generated and source files in `Documentation/`. Instead, put the HTML files into a subdirectory that is clearly marked as containing only generated files. Upside: this would provide an overall cleaner architecture. Downside: lots of work, may require some convincing of oldtimers who see nothing wrong with mixing source and generated files. Ciao, Johannes
