Re: [PATCH 1/2] doc: add an option to have Asciidoctor build man pages directly
- From
Jeff King <peff@peff.net>
- Date
- May 12, 2021, 06:22 UTC
- Message-ID
- <YJt0Dv7HP2VnLLwv@coredump.intra.peff.net>
- In-Reply-To
- <20210512021138.63598-1-sandals@crustytoothpaste.net>
On Wed, May 12, 2021 at 02:11:37AM +0000, brian m. carlson wrote:
Show 10 quoted lines
> @@ -367,9 +370,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS > manpage-base-url.xsl: manpage-base-url.xsl.in > $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ > > +ifdef TXT_TO_MAN > +%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS > + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ > + $(TXT_TO_MAN) -o $@+ $< && \ > + mv $@+ $@ > +else
This depends on GIT-ASCIIDOCFLAGS, which is good. But I think we'd also want to tell that file whether we are using the direct backend or not. Otherwise, doing:
make USE_ASCIIDOCTOR=1 git.1 make USE_ASCIIDOCTOR=1 USE_ASCIIDOCTOR_MANPAGE=1 git.1
gets confused. Because git.1 is more recent than git.txt, it things there is nothing to build in the second case. I think you want:
diff --git a/Documentation/Makefile b/Documentation/Makefile index 536d9a5f3d..4b66a61f51 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -337,7 +337,7 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ date >$@ -TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE)) GIT-ASCIIDOCFLAGS: FORCE @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ With that change, plus a patch I'll send in a minute, it's easy to run doc-diff on the result. > diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb > index d906a00803..40fa87b121 100644 > --- a/Documentation/asciidoctor-extensions.rb > +++ b/Documentation/asciidoctor-extensions.rb > @@ -15,6 +15,8 @@ module Git > "#{target}(#{attrs[1]})</ulink>" > elsif parent.document.basebackend? 'html' > %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) > + elsif parent.document.basebackend? 'manpage' > + %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP) Unfortunately, this doesn't seem to work. Diffing the rendered docs between regular asciidoctor-then-xmlto and direct-to-manpage shows a lot of hunks like: For more details about the <pathspec> syntax, see the pathspec - entry in gitglossary(7). + entry in \fBgitglossary\fP\fR(7)\fP. -Peff