test: fix man page formatting by adding blank lines in after-help text by Agent-Hellboy · Pull Request #9005 · uutils/coreutils

Agent-Hellboy · 2025-10-25T03:37:02Z

github-actions · 2025-10-25T05:35:17Z

GNU testsuite comparison:

Skipping an intermittent issue tests/misc/tee (passes in this run but fails in the 'main' branch)

matttbe

@Agent-Hellboy thanks for fixing that! I just did (almost) the same on my side, then I saw your PR :)

I think you need more new lines: on my side, I had to double each new line in the test-after-help section, see: https://manpages.ubuntu.com/manpages/questing/en/man1/test.1.html

matttbe · 2025-10-25T06:34:26Z


  File operations:
  - FILE1 -ef FILE2 FILE1 and FILE2 have the same device and inode numbers
  - FILE1 -nt FILE2 FILE1 is newer (modification date) than FILE2


Sorry, I didn't mean doubling the lines you already did below, but all the ones here and above.

Let me find all instances and fix it

github-actions · 2025-10-25T08:45:13Z

GNU testsuite comparison:

Skip an intermittent issue tests/timeout/timeout (fails in this run but passes in the 'main' branch)

matttbe

Almost there I think

matttbe · 2025-10-25T11:57:10Z

+
  - EXPRESSION1 -o EXPRESSION2 either EXPRESSION1 or EXPRESSION2 is true

  String operations:


You also need a newline here below

matttbe · 2025-10-25T11:57:38Z

+
  - STRING1 != STRING2 the strings are not equal

  Integer comparisons:


Same here below

matttbe · 2025-10-25T11:57:49Z

+
  - INTEGER1 -ne INTEGER2 INTEGER1 is not equal to INTEGER2

  File operations:


Same here below

matttbe · 2025-10-25T11:59:13Z

+
  - EXPRESSION1 -o EXPRESSION2 EXPRESSION1 ou EXPRESSION2 est vraie

  Opérations sur les chaînes :


Same here below

matttbe · 2025-10-25T11:59:22Z

+
  - STRING1 != STRING2 les chaînes ne sont pas égales

  Comparaisons d'entiers :


Same here below

matttbe · 2025-10-25T11:59:30Z

+
  - INTEGER1 -ne INTEGER2 INTEGER1 n'est pas égal à INTEGER2

  Opérations sur les fichiers :


Same here below

Agent-Hellboy · 2025-10-26T11:01:37Z

I hope it's okay now

matttbe

It looks like you added new lines above my comments, not below.

On the screenshot, the first entry is on the same line as the list introduction line.

sylvestre · 2025-10-26T11:48:23Z

could you please add a test that would verify that the manpage output is correct ? thanks

github-actions · 2025-10-26T11:49:05Z

GNU testsuite comparison:

Skipping an intermittent issue tests/misc/tee (passes in this run but fails in the 'main' branch)
Skipping an intermittent issue tests/tail/overlay-headers (passes in this run but fails in the 'main' branch)

Agent-Hellboy · 2025-10-26T11:53:26Z

It looks like you added new lines above my comments, not below.

On the screenshot, the first entry is on the same line as the list introduction line.

Ohh, sorry , I can also see it😬

Agent-Hellboy · 2025-10-26T11:53:43Z

could you please add a test that would verify that the manpage output is correct ? thanks

Sure thing.

github-actions · 2025-10-26T15:44:08Z

GNU testsuite comparison:

Skip an intermittent issue tests/tail/overlay-headers (fails in this run but passes in the 'main' branch)

Agent-Hellboy · 2025-10-26T15:52:48Z

@matttbe I guess CI failures are not related.

cakebaker · 2025-10-26T15:58:34Z

@Agent-Hellboy I think the Code Quality checks and the CICD / Build check are related to this PR :|

Agent-Hellboy · 2025-10-26T16:01:53Z

@Agent-Hellboy I think the Code Quality checks and the CICD / Build check are related to this PR :|

Yeah, I expanded and saw

matttbe

Thanks for the last update. The modifications in the man pages look good to me. It is similar to what I did, except that in your version, you added an extra new line (2 in total then) before each list introduction sentence, but I guess that's fine.

Regarding the tests, I'm not sure how they work, but could you eventually have a generic version that is not specific to the test man pages? e.g. each line starting with a - should have an empty new line before?

If you do that, please add a link to the bug report or PR you opened in the other project to render this part correctly. So when this part is fixed, the test can be adapted.

Agent-Hellboy · 2025-10-26T17:06:07Z

@matttbe, first of all, I apologize for not verifying my change closely enough several times.

I'm not sure how they work, but could you eventually have a generic version that is not specific to the test man pages?

sure, but we need to validate for test.

e.g. each line starting with a - should have an empty new line before?

Yeah I did that please check

If you do that, please add a link to the bug report or PR you opened in the other project to render this part correctly. So when this part is fixed, the test can be adapted.

sure

matttbe · 2025-10-26T17:34:03Z

sure, but we need to validate for test.

OK, I don't exactly know the policy for this project, but the tests you added might be enough. I hope someone else will be able to comment about that.

e.g. each line starting with a - should have an empty new line before?

Yeah I did that please check

I'm not sure that's what you did. What I meant is that the formatting issue is not specific to the test man page, but for all man pages. So ideally, it would be nice to ensure all lists (a line starting with a dash) defined in the test-after-help section are preceded by an empty line. Au last until this bug is solved: clap-rs/clap#6087

I don't know if you can use regex with multiple lines but you should not have any hits for something like this in the test-after-help section: [^\n]\n\s*- (not tested, I'm on my phone).
Would it not work? (Can eventually be part of another PR, not sure what's the policy here)

codspeed-hq · 2025-10-26T17:55:43Z

Merging this PR will not alter performance

✅ 103 untouched benchmarks
🗄️ 1 archived benchmark run¹

_{Comparing Agent-Hellboy:fix-8362 (9113c0a) with main (3b2cb6a)}

1 benchmark was run, but is now archived. If it was deleted in another branch, consider rebasing to remove it from the report. Instead if it was added back, click here to restore it. ↩

github-actions · 2025-10-26T17:59:44Z

GNU testsuite comparison:

Skip an intermittent issue tests/tail/overlay-headers (fails in this run but passes in the 'main' branch)

Agent-Hellboy · 2025-10-27T02:55:42Z

I'm not sure that's what you did. What I meant is that the formatting issue is not specific to the test man page, but for all man pages. So ideally, it would be nice to ensure all lists (a line starting with a dash) defined in the test-after-help section are preceded by an empty line. Au last until this bug is solved: clap-rs/clap#6087

I guess we need to add a comment in ftl files. As these tests are integration test and just check the man file formatting, it doesn't care about how it gets generated and all

I don't know if you can use regex with multiple lines but you should not have any hits for something like this in the test-after-help section: [^\n]\n\s*- (not tested, I'm on my phone).
Would it not work? (Can eventually be part of another PR, not sure what's the policy here)

I guess it's okay, but if you want, I can add regex for this kind of validation in some other PR.

github-actions · 2025-10-27T06:24:56Z

GNU testsuite comparison:

Skip an intermittent issue tests/tail/overlay-headers (fails in this run but passes in the 'main' branch)

matttbe

Thanks for the last update!

The code looks good to me, but I'm not part of the project, and I don't know the policy around the tests. I have one suggestion, but this PR is maybe not the right place to do that, I don't know.

Hopefully someone from the project can continue the review :)

matttbe · 2025-10-27T11:10:39Z

+    // the formatting issue is consistent across all utilities
+
+    // Test a representative sample of utilities
+    let utilities_to_test = vec!["cat", "test", "wc", "uniq", "echo", "head", "tail", "cut"];


Why only a selection? Is it not possible to check all man pages? All of them should be properly formatted.

(Or maybe it is not the right place for that kind of tests?)

matttbe · 2025-10-27T11:14:37Z

I don't know if you can use regex with multiple lines but you should not have any hits for something like this in the test-after-help section: [^\n]\n\s*- (not tested, I'm on my phone).
Would it not work? (Can eventually be part of another PR, not sure what's the policy here)

I guess it's okay, but if you want, I can add regex for this kind of validation in some other PR.

What you did looks good to me:

if a line ends with :, it should be followed by an empty line
if a line starts with -, there should be an empty line before

Would be even better if this check is done for all man-pages, but not sure what's possible there.

One last thing: the CI spot some issues. It looks like they are related to your new tests.

matttbe

the modifications in the .ftl look good to me. The CI is complaining about the rest. Can someone review the rest please?

matttbe

(sorry, just to avoid confusions, better mark this PR as "Request changes")

Agent-Hellboy · 2025-10-27T11:30:04Z

Thanks @matttbe for the review and being patient, I will look at everything carefully after the festival ends at my place, I don't want to rush on anything now.

matttbe · 2025-12-15T11:44:46Z

@Agent-Hellboy if having tests checking if a newline is added after each line ending with : in all man pages using after_help, maybe the fix and the tests should be split?

Having a fix for the unreadable test man page might be better to have than checking for future regressions due to an external lib not handling formatting in the after_help part?

test: fix man page formatting by adding blank lines in after-help text

00f8d5f

matttbe suggested changes Oct 25, 2025

View reviewed changes

add extra newlines

894e890

matttbe suggested changes Oct 25, 2025

View reviewed changes

add extra newlines inside other blocks

10d4731

matttbe suggested changes Oct 25, 2025

View reviewed changes

resolve review comments

9afdb43

matttbe suggested changes Oct 26, 2025

View reviewed changes

resolve comment and add test

d9a844d

matttbe reviewed Oct 26, 2025

View reviewed changes

update manpage generation and fix test

1cd3195

Agent-Hellboy added 2 commits October 27, 2025 07:19

fix: update tests

e7bd03b

geric test to test manpage formatting for few utilities

9113c0a

matttbe reviewed Oct 27, 2025

View reviewed changes

matttbe approved these changes Oct 27, 2025

View reviewed changes

matttbe reviewed Oct 27, 2025

View reviewed changes

matttbe suggested changes Oct 27, 2025

View reviewed changes

matttbe mentioned this pull request Feb 5, 2026

test: make the man-page readable + sync #10737

Merged


		- EXPRESSION1 -o EXPRESSION2 either EXPRESSION1 or EXPRESSION2 is true

		String operations:


		- STRING1 != STRING2 the strings are not equal

		Integer comparisons:


		- INTEGER1 -ne INTEGER2 INTEGER1 is not equal to INTEGER2

		File operations:


		- EXPRESSION1 -o EXPRESSION2 EXPRESSION1 ou EXPRESSION2 est vraie

		Opérations sur les chaînes :


		- STRING1 != STRING2 les chaînes ne sont pas égales

		Comparaisons d'entiers :


		- INTEGER1 -ne INTEGER2 INTEGER1 n'est pas égal à INTEGER2

		Opérations sur les fichiers :

Uh oh!

Conversation

Agent-Hellboy commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 25, 2025

Uh oh!

matttbe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Agent-Hellboy Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 25, 2025

Uh oh!

matttbe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

matttbe left a comment

Choose a reason for hiding this comment

Uh oh!

sylvestre commented Oct 26, 2025

Uh oh!

github-actions Bot commented Oct 26, 2025

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

github-actions Bot commented Oct 26, 2025

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

cakebaker commented Oct 26, 2025

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

matttbe left a comment

Choose a reason for hiding this comment

Uh oh!

Agent-Hellboy commented Oct 26, 2025

Uh oh!

matttbe commented Oct 26, 2025

Uh oh!

codspeed-hq Bot commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions Bot commented Oct 26, 2025

Uh oh!

Agent-Hellboy commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 27, 2025

Uh oh!

matttbe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Agent-Hellboy commented Oct 25, 2025 •

edited

Loading

Agent-Hellboy Oct 25, 2025 •

edited

Loading

codspeed-hq Bot commented Oct 26, 2025 •

edited

Loading

Agent-Hellboy commented Oct 27, 2025 •

edited

Loading

matttbe commented Dec 15, 2025 •

edited

Loading