| Message ID | pull.1749.v2.git.git.1721679949618.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 8bfc3e47a73b108fd8e7f9c3b9e7714b9f418fa8 |
| Headers | show |
| Series | [v2] asciidoctor: fix `synopsis` rendering | expand |
"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Johannes Schindelin <johannes.schindelin@gmx.de> > > Since 76880f0510c (doc: git-clone: apply new documentation formatting > guidelines, 2024-03-29), the synopsis of `git clone`'s manual page is > rendered differently than before; Its parent commit did the same for > `git init`. > ... > Documentation/.gitignore | 1 + > Documentation/Makefile | 1 + > Documentation/docinfo.html | 5 +++++ > 3 files changed, 7 insertions(+) > create mode 100644 Documentation/docinfo.html I think our mails crossed. You need something like this squashed in, or "make distclean" would make the tree dirty as Ramsay reported. Documentation/Makefile | 5 +++++ Documentation/{docinfo.html => docinfo-html.in} | 0 2 files changed, 5 insertions(+) rename Documentation/{docinfo.html => docinfo-html.in} (100%) 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 $@ $< diff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in similarity index 100% rename from Documentation/docinfo.html rename to Documentation/docinfo-html.in
Junio C Hamano <gitster@pobox.com> writes: > I think our mails crossed. You need something like this squashed > in, or "make distclean" would make the tree dirty as Ramsay > reported. > ... And I needed to undo the .gitignore change between v1 and v2 to match (otherwise ci/lib.sh notices that docinfo.html is an "unignored build artifact" and complains). An updated SQUASH??? fixup looks like this. Thanks. Documentation/.gitignore | 1 - Documentation/Makefile | 5 +++++ Documentation/{docinfo.html => docinfo-html.in} | 0 3 files changed, 5 insertions(+), 1 deletion(-) rename Documentation/{docinfo.html => docinfo-html.in} (100%) diff --git a/Documentation/.gitignore b/Documentation/.gitignore index d11567fbbe..a48448de32 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,6 +1,5 @@ *.xml *.html -!/docinfo.html *.[1-8] *.made *.texi 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 $@ $< diff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in similarity index 100% rename from Documentation/docinfo.html rename to Documentation/docinfo-html.in
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
Johannes Schindelin <Johannes.Schindelin@gmx.de> writes: > 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. Consider that we leave the door open for future enhancements (like, lose the conditional compilation and instead make it an empty file when AsciiDoc and not asciidoctor is in use). > Have you considered one of these alternatives? No, because I am not interested in anything more elaborate a few days before tagging -rc2. If this is not meant for the upcoming release, then I am all ears (and eyes), but otherwise, let's just do the simplest and the most obvious thing to unbreak users for the upcoming release and leave a more elaborate engineering to next cycle. Jean-Noël is planning to undo the overly elaborate mark-up and that may eliminate the need to work around "<code> in <pre> is made into a block element" behaviour of default asciidoctor style in the first place, so the longer term plan should take that into account as well. Thanks.
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index a48448de32f..d11567fbbe7 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,5 +1,6 @@ *.xml *.html +!/docinfo.html *.[1-8] *.made *.texi diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c7..78e407e4bd1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +ASCIIDOC_EXTRA += -adocinfo=shared ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html new file mode 100644 index 00000000000..fb3560eb92b --- /dev/null +++ b/Documentation/docinfo.html @@ -0,0 +1,5 @@ +<style> +pre>code { + display: inline; +} +</style>