[CI:DOCS] Add CI check for SEE ALSO in man pages

Add new CI check to confirm that links and references
in SEE ALSO sections are properly formatted and that
links are valid (at least in theory: we do no actual
URL fetching to test for 404).

The check is piggybacked into existing xref-helpmsgs-manpages
script. It could conceivably be more elegant to write a
separate tool for this purpose, but I don't wish to duplicate
the logic for finding and reading markdown files.

Script identified various problems, which I fix in this PR:

  . missing '**' (asterisks) around some references, or '**'
    in the wrong place.

  . links pointing to github.com/.../tree/ instead of /blob/
    (github redirects those automatically, but I like
    consistency)

  . a few copy-paste errors, e.g. subgid linking to subuid.

Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago 2021-11-10 08:44:44 -07:00
parent 2e6231bcbc
commit 6236be4ff9
12 changed files with 136 additions and 11 deletions

View File

@ -141,4 +141,4 @@ $ podman auto-update
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, sd_notify(3), systemd.unit(5)
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**

View File

@ -1021,7 +1021,7 @@ If you are using `useradd` within your build script, you should pass the
useradd to stop creating the lastlog file.
## SEE ALSO
**[podman(1)](podman.1.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[useradd(8)](https://www.unix.com/man-page/redhat/8/useradd)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[Containerfile(5)](https://github.com/containers/buildah/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/buildah/blob/main/docs/containerignore.5.md)**
**[podman(1)](podman.1.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[useradd(8)](https://www.unix.com/man-page/redhat/8/useradd)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[Containerfile(5)](https://github.com/containers/buildah/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/buildah/blob/main/docs/containerignore.5.md)**
## HISTORY
Aug 2020, Additional options and .containerignore added by Dan Walsh `<dwalsh@redhat.com>`

View File

@ -61,4 +61,4 @@ completion output to a file and source that to the user's powershell profile.
More information about profiles is available with **Get-Help about_Profiles**.
## SEE ALSO
**[podman(1)](podman.1.md)**, zsh(1), fish(1), powershell(1)
**[podman(1)](podman.1.md)**, **zsh(1)**, **fish(1)**, **powershell(1)**

View File

@ -51,7 +51,7 @@ $ podman container cleanup mywebserver myflaskserver 860a4b23
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, conmon(8)
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
## HISTORY
Jun 2018, Originally compiled by Dan Walsh <dwalsh@redhat.com>

View File

@ -84,7 +84,7 @@ $ podman container runlabel --display run foobar
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**
**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**
## HISTORY
August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot com)

View File

@ -1537,7 +1537,7 @@ page.
NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**.
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**
## HISTORY
October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman `<dwalsh@redhat.com>`

View File

@ -235,7 +235,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS
bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.5.md)**
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
## HISTORY
April 2020, Updated details and added use case to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)

View File

@ -53,7 +53,6 @@ $ podman rmi -a -f
**125** The command fails for any other reason
## SEE ALSO
podman(1), skopeo-delete(1)
**[podman(1)](podman.1.md)**, **[skopeo-delete(1)](https://github.com/containers/skopeo/blob/main/docs/skopeo-delete.1.md)**
## HISTORY

View File

@ -1891,7 +1891,7 @@ page.
NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**.
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**
## HISTORY
September 2018, updated by Kunal Kushwaha `<kushwaha_kunal_v7@lab.ntt.co.jp>`

View File

@ -144,7 +144,6 @@ Note: This works only with registries that implement the v2 API. If tried with a
registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
## SEE ALSO
podman(1), containers-registries.conf(5)
**[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)**
## HISTORY

View File

@ -400,7 +400,7 @@ The Network File System (NFS) and other distributed file systems (for example: L
For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/master/troubleshooting.md).
## SEE ALSO
**[containers-mounts.conf(5)](https://github.com/containers/common/blob/main/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **oci-hooks**(5), **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
**[containers-mounts.conf(5)](https://github.com/containers/common/blob/main/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **oci-hooks(5)**, **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
## HISTORY
Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com>

View File

@ -54,6 +54,11 @@ option is listed in the appropriate man page and vice-versa.
$ME invokes '\$PODMAN' (default: $Default_Podman).
In the spirit of shoehorning functionality where it wasn't intended,
$ME also checks the SEE ALSO section of each man page
to ensure that references and links are properly formatted
and valid.
Exit status is zero if no inconsistencies found, one otherwise
OPTIONS:
@ -286,6 +291,9 @@ sub podman_man {
elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) {
$section = 'commands';
}
elsif ($line =~ /^\#\#\s+SEE\s+ALSO/) {
$section = 'see-also';
}
elsif ($line =~ /^\#\#[^#]/) {
$section = '';
}
@ -340,6 +348,11 @@ sub podman_man {
}
}
}
# It's easy to make mistakes in the SEE ALSO elements.
elsif ($section eq 'see-also') {
_check_seealso_links( "$subpath:$.", $line );
}
}
close $fh;
@ -427,5 +440,119 @@ sub podman_rst {
# END data gathering
###############################################################################
# BEGIN sanity checking of SEE ALSO links
##########################
# _check_seealso_links # Check formatting and link validity.
##########################
sub _check_seealso_links {
my $path = shift;
my $line = shift;
return if ! $line;
# Line must be a comma-separated list of man page references, e.g.
# **foo(1)**, **[podman-bar(1)](podman-bar.1.md)**, **[xxx(8)](http...)**
TOKEN:
for my $token (split /,\s+/, $line) {
# Elements must be separated by comma and space. (We don't do further
# checks here, so it's possible for the dev to add the space and then
# have us fail on the next iteration. I choose not to address that.)
if ($token =~ /,/) {
warn "$ME: $path: please add space after comma: '$token'\n";
++$Errs;
next TOKEN;
}
# Each token must be of the form '**something**'
if ($token !~ s/^\*\*(.*)\*\*$/$1/) {
if ($token =~ /\*\*/) {
warn "$ME: $path: '$token' has asterisks in the wrong place\n";
}
else {
warn "$ME: $path: '$token' should be bracketed by '**'\n";
}
++$Errs;
next TOKEN;
}
# Is it a markdown link?
if ($token =~ /^\[(\S+)\]\((\S+)\)$/) {
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 ($link ne "$base.$section.md") {
warn "$ME: $path: inconsistent link $name -> $link, expected $base.$section.md\n";
++$Errs;
}
}
else {
if (! _is_valid_external_link($base, $section, $link)) {
warn "$ME: $path: invalid link $name -> $link\n";
++$Errs;
}
}
}
else {
warn "$ME: $path: could not parse '$name' as 'manpage(N)'\n";
++$Errs;
}
}
# Not a markdown link; it must be a plain man reference, e.g. 'foo(5)'
elsif ($token =~ m!^(\S+)\((\d+)\)$!) {
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") {
warn "$ME: $path: '$token' should be '[$token]($base.$section.md)'\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"
if $verbose;
}
else {
warn "$ME: $path: invalid token '$token'\n";
++$Errs;
}
}
}
#############################
# _is_valid_external_link # Tries to validate links to external man pages
#############################
#
# This performs no actual fetches, so we can't actually check for 404.
# All we do is ensure that links conform to standard patterns. This is
# good for catching things like 'conmon(8)' pointing to a .5 URL, or
# linking to .md instead of .html.
#
# FIXME: we could actually rewrite this so as to offer hints on what to fix.
# That's a lot of work, and a lot of convoluted code, for questionable ROI.
#
sub _is_valid_external_link {
my ($base, $section, $link) = @_;
return 1 if $link =~ m!^https://github\.com/\S+/blob/(main|master)(/.*)?/\Q$base\E\.$section\.md!;
return 1 if $link =~ m!^https://.*unix\.com/man-page/(linux|redhat)/$section/$base$!;
return 1 if $link eq "https://man7\.org/linux/man-pages/man$section/$base\.$section\.html";
if ($base =~ /systemd/) {
return 1 if $link eq "https://www.freedesktop.org/software/systemd/man/$base.html";
}
return;
}
# END sanity checking of SEE ALSO links
###############################################################################
1;