[PATCH RFC] perf docs: build only the declared manual section

[PATCH RFC] perf docs: build only the declared manual section

[ORTOLA Raphaël]

Hello,

While building Ubuntu linux 7.3.0-9.9, GNU make 4.4.1 reports that the
perf manual rules do not update their .5 and .7 peer targets. The
implicit multi-target rules promise all three sections for each input,
whereas XMLto and Asciidoctor emit the section declared by that input.

The proposed change uses the existing DOC_MAN1/DOC_MAN5/DOC_MAN7 lists
with static pattern prerequisites and one recipe per backend. The
shared asciidoc.conf prerequisite is moved after those rules so that
$< remains the manual input rather than the configuration file.
USE_ASCIIDOCTOR selects the two alternative backends.

Checks on this downstream source:
- Before: the native XMLto build reports missing .5/.7 peer targets.
- After: all 41 native XMLto manuals build without warnings.
- Additional section 5 and 7 fixture manuals build with XMLto.
- Asciidoctor 2.0.26 with Ruby 3.3.8 generates section 1, 5 and 7
fixture manuals without warnings, using explicit ASCIIDOC_EXTRA
backend flags.

This is an RFC for the documentation rules; it is not a claim of a
completed kernel build or testing on current upstream master. Please
review the proposed fix below.

--- a/tools/perf/Documentation/Makefile
+++ b/tools/perf/Documentation/Makefile
@@ -174,7 +174,6 @@

 html: $(DOC_HTML)

-$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf

 man: man1 man5 man7
 man1: $(DOC_MAN1)
@@ -259,17 +258,26 @@
                     --date=short --no-show-signature $<)))

 ifdef USE_ASCIIDOCTOR
-$(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : %.txt
+$(DOC_MAN1): $(OUTPUT)%.1: %.txt
+$(DOC_MAN5): $(OUTPUT)%.5: %.txt
+$(DOC_MAN7): $(OUTPUT)%.7: %.txt
+$(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7):
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b manpage -d manpage \
 		$(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) \
 		-adocdate=$(PERF_DATE) -o $@+ $< && \
 	mv $@+ $@
-endif
-
-$(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : $(OUTPUT)%.xml
+else
+
+$(DOC_MAN1): $(OUTPUT)%.1: $(OUTPUT)%.xml
+$(DOC_MAN5): $(OUTPUT)%.5: $(OUTPUT)%.xml
+$(DOC_MAN7): $(OUTPUT)%.7: $(OUTPUT)%.xml
+$(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7):
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
+
+$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf

 $(OUTPUT)%.xml : %.txt
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

Re: [PATCH RFC] perf docs: build only the declared manual section

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 2 potential
issues to consider:
- [High] perf docs: missing Signed-off-by trailer in commit message
- [Low] perf docs: missing Fixes trailers for multi-target manpage build
  rules
--

commit bfd2c7c72bce033b21098d6070bc47bebfe6a33c
Author: ORTOLA Raphaël <raphael.ortola@gmail.com>

> perf docs: build only the declared manual section
>
> Hello,
>
> While building Ubuntu linux 7.3.0-9.9, GNU make 4.4.1 reports that the
> perf manual rules do not update their .5 and .7 peer targets. The
> implicit multi-target rules promise all three sections for each input,
> whereas XMLto and Asciidoctor emit the section declared by that input.
>
> The proposed change uses the existing DOC_MAN1/DOC_MAN5/DOC_MAN7 lists
> with static pattern prerequisites and one recipe per backend. The
> shared asciidoc.conf prerequisite is moved after those rules so that
> $< remains the manual input rather than the configuration file.
> USE_ASCIIDOCTOR selects the two alternative backends.
>
> Checks on this downstream source:
> - Before: the native XMLto build reports missing .5/.7 peer targets.
> - After: all 41 native XMLto manuals build without warnings.
> - Additional section 5 and 7 fixture manuals build with XMLto.
> - Asciidoctor 2.0.26 with Ruby 3.3.8 generates section 1, 5 and 7
> fixture manuals without warnings, using explicit ASCIIDOC_EXTRA
> backend flags.
>
> This is an RFC for the documentation rules; it is not a claim of a
> completed kernel build or testing on current upstream master. Please
> review the proposed fix below.

[Severity: High]
The commit message is missing a Signed-off-by: trailer, which is required
under Documentation/process/submitting-patches.rst before a patch can be
applied.  Also, the greeting and RFC note should go below the ---
separator so they do not end up in the permanent git changelog.

[Severity: Low]
Since this fixes the multi-target implicit rules for XMLto and
Asciidoctor, should it include Fixes: trailers for the commits that
introduced them?

  Fixes: c1c2365acf8c ("perf_counter tools: Generate per command manpages (and pdf/html, etc.)")
  Fixes: ffef80ecf89f ("perf Documentation: Support for asciidoctor")

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/CACzNvX6qkkd-QgJzcQquHS6XiKacMqb85JeLC8LmfLTeWqu4EQ@mail.gmail.com?part=1