Re: [PATCH v2] asciidoctor: fix `synopsis` rendering

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jul 23, 2024, 14:19 UTC
Message-ID: <a1d70653-182e-e063-5438-2b3179d011f7@gmx.de>
In-Reply-To: <xmqqplr59mvm.fsf@gitster.g>

Hi Junio,

On Mon, 22 Jul 2024, Junio C Hamano wrote:

Show 23 quoted lines

> 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