[CI:DOCS] Man pages: check for corrupt tables #19278
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Every so often we hear reports of a corrupt man page table,
where columns are misaligned in nonsensical ways. The
traditional symptom looks like:
|----------------|--------------|
| option name | |
|----------------|--------------|
| | description |
|----------------|--------------|
Cause: one of the tools in the man page generation chain,
maybe 'man' itself, has an undocumented length limit on
table cells, _and_ an undocumented page width as well.
If you exceed these undocumented limits, you get corrupt
man pages. Silently.
This adds a horrible test for those. And I mean horrible:
- unreadable
- unmaintainable
- unreliable (heuristic, no guarantees)
- slows down 'make docs' (less than a second, but still)
I've tested by adding long '| sdf sdf | dsf |' rows to
a few man pages, and it triggers. That's the only good
thing I can say about it.
Other approaches I tried:
- man -l -Tascii | grep non-ascii-art
- man -l ... 2>&1 | grep "table wider than"
- perusing the generated .1/.5 pages, seeing if my eye
can detect something different about too-long cells
- same, using 'tbl'
- checking for too-long cells in the source document
...and more that I've forgotten. This was the only way
that produced reliable errors. If you have a better way,
please oh please submit it.
Signed-off-by: Ed Santiago <[email protected]>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: edsantiago The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
bot
added
the
approved
|
...and this is what the failure looks like with a deliberate fault inserted: https://cirrus-ci.com/task/6541249260290048?logs=main#L335 |
Luap99
reviewed
Jul 19, 2023
|
Lets merge this and then add the markdown validator in separate PR. |
|
/lgtm |
edsantiago
added a commit
to edsantiago/libpod
that referenced
this pull request
Jul 24, 2023
The new man-page table check (containers#19278) fails on RHEL8 because go-md2man is 2.00 and we require 2.02. After much deliberation.... just ignore the problem. Add a bold note to that part of the Makefile, and hope that when the test fails on the next RHEL branching someone will look at the Makefile, find the comment, and disable that test. Got any better ideas? Signed-off-by: Ed Santiago <[email protected]>
edsantiago
added a commit
to edsantiago/libpod
that referenced
this pull request
Jul 26, 2023
go-md2man is fragile, especially around tables (containers#18678, containers#19278). Podman man pages are finely tuned to look OK using v2.02, which is what we vendor in test/tools, so we should really use it instead of whatever is installed on the system. This fixes 'make docs' on RHEL8, broken as of containers#19278. Signed-off-by: Ed Santiago <[email protected]>
github-actions
bot
added
the
locked - please file new issue/PR
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Every so often we hear reports of a corrupt man page table,
where columns are misaligned in nonsensical ways. The
traditional symptom looks like:
|----------------|--------------|
Cause: one of the tools in the man page generation chain,
maybe 'man' itself, has an undocumented length limit on
table cells, and an undocumented page width as well.
If you exceed these undocumented limits, you get corrupt
man pages. Silently.
This adds a horrible test for those. And I mean horrible:
I've tested by adding long '| sdf sdf | dsf |' rows to
a few man pages, and it triggers. That's the only good
thing I can say about it.
Other approaches I tried:
can detect something different about too-long cells
...and more that I've forgotten. This was the only way
that produced reliable errors. If you have a better way,
please oh please submit it.
Signed-off-by: Ed Santiago [email protected]