opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-17 15:18:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

Man page checker: require canonical name in SEE ALSO

Browse Source 
The man-page cross-reference script checks the SEE ALSO section
to confirm that all references are to existing man pages (#12258).
However, it's a little too forgiving: it allows aliases, the
short '.so' files under the 'links/' subdirectory. That means
we could link to non-default command names, and were doing so.

As of this PR, we no longer allow that. Any podman command
referenced in SEE ALSO must be the canonical command name
(and man page). Fix existing non-canonical names, and
remove the exception so we don't allow this again.

See #16848 for discussion of context.

Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago
2023-01-02 10:28:54 -07:00
parent 2dcf6b1b18
commit d92bfd244f
5 changed files with 12 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
hack/xref-helpmsgs-manpages
View File

@ -554,7 +554,7 @@ sub _check_seealso_links {
my ($name, $link) = ($1, $2);
if ($name =~ /^(.*)\((\d)\)$/) {
my ($base, $section) = ($1, $2);
if (-e "$Markdown_Path/$base.$section.md" || -e "$Markdown_Path/links/$base.$section") {
if (-e "$Markdown_Path/$base.$section.md") {
if ($link ne "$base.$section.md") {
warn "$ME: $path: inconsistent link $name -> $link, expected $base.$section.md\n";
++$Errs;
@ -578,11 +578,17 @@ sub _check_seealso_links {
my ($base, $section) = ($1, $2);
# Unadorned 'podman-foo(1)' must be a link.
if (-e "$Markdown_Path/$base.$section.md" || -e "$Markdown_Path/links/$base.$section") {
if (-e "$Markdown_Path/$base.$section.md") {
warn "$ME: $path: '$token' should be '[$token]($base.$section.md)'\n";
++$Errs;
}
# Aliases (non-canonical command names): never link to these
if (-e "$Markdown_Path/links/$base.$section") {
warn "$ME: $path: '$token' refers to a command alias; please use the canonical command name instead\n";
++$Errs;
}
# Link to man page foo(5) but without a link. This is not an error
# but Ed may sometimes want to see those on a manual test run.
warn "$ME: $path: plain '$token' would be so much nicer as a link\n"