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 pages: fix broken tables

Browse Source 
Work around a go-md2man bug, and add a check script to make sure
this doesn't hit us again.

Background: go-md2man can't deal with a left-hand column > 31 chars.
It produces man pages that look like:

    | Something With >31 Character |                |
    |                              | ..description  |

(should be all on one row). It also has trouble when the vertical
bars are misaligned: it completely removes the right-hand side.

There's almost certainly a better solution: fix go-md2man, or
use a different conversion tool, or maybe even pre/postprocess.
But this is a quick interim solution.

Sorry for the perl. This could be done in bash/sed/awk/grep,
but not with any sort of sane error messages.

Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago
2023-05-24 11:21:48 -06:00
parent e7ef259cb6
commit dfba6ddd4c
4 changed files with 241 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@ -505,6 +505,7 @@ podman-remote-%-docs: podman-remote
man-page-check: bin/podman man-page-check: bin/podman
hack/man-page-checker hack/man-page-checker
hack/xref-helpmsgs-manpages hack/xref-helpmsgs-manpages
hack/man-page-table-check
.PHONY: swagger-check .PHONY: swagger-check
swagger-check: swagger-check:

28
docs/source/markdown/podman-images.1.md.in
View File

@ -31,20 +31,20 @@ The *filters* argument format is of `key=value` or `key!=value`. If there is mor
Supported filters: Supported filters:
| Filter | Description | | Filter | Description |
| :----------------: | --------------------------------------------------------------------------------------------- | |:---------------:|-----------------------------------------------------------------------------------------------|
| *id* | Filter by image ID. | | *id* | Filter by image ID. |
| *before* | Filter by images created before the given IMAGE (name or tag). | | *before* | Filter by images created before the given IMAGE (name or tag). |
| *containers* | Filter by images with a running container. | | *containers* | Filter by images with a running container. |
| *dangling* | Filter by dangling (unused) images. | | *dangling* | Filter by dangling (unused) images. |
| *digest* | Filter by digest. | | *digest* | Filter by digest. |
| *intermediate* | Filter by images that are dangling and have no children | | *intermediate* | Filter by images that are dangling and have no children |
| *label* | Filter by images with (or without, in the case of label!=[...] is used) the specified labels. | | *label* | Filter by images with (or without, in the case of label!=[...] is used) the specified labels. |
| *manifest* | Filter by images that are manifest lists. | | *manifest* | Filter by images that are manifest lists. |
| *readonly* | Filter by read-only or read/write images. | | *readonly* | Filter by read-only or read/write images. |
| *reference* | Filter by image name. | | *reference* | Filter by image name. |
| *after*/*since* | Filter by images created after the given IMAGE (name or tag). | | *after*/*since* | Filter by images created after the given IMAGE (name or tag). |
| *until* | Filter by images created until the given duration or time. | | *until* | Filter by images created until the given duration or time. |
The `id` *filter* accepts the image ID string. The `id` *filter* accepts the image ID string.

100
docs/source/markdown/podman-systemd.unit.5.md
View File

@ -84,56 +84,56 @@ There is only one required key, `Image`, which defines the container image the s
Valid options for `[Container]` are listed below: Valid options for `[Container]` are listed below:
| **[Container] options** | **podman run equivalent** | | **[Container] options** | **podman run equivalent** |
| ----------------- | ------------------ | |--------------------------------|------------------------------------------------------|
| AddCapability=CAP | --cap-add CAP | | AddCapability=CAP | --cap-add CAP |
| AddDevice=/dev/foo | --device /dev/foo | | AddDevice=/dev/foo | --device /dev/foo |
| Annotation="YXZ" | --annotation "XYZ" | | Annotation="YXZ" | --annotation "XYZ" |
| ContainerName=name | --name name | | ContainerName=name | --name name |
| DropCapability=CAP | --cap-drop=CAP | | DropCapability=CAP | --cap-drop=CAP |
| Environment=foo=bar | --env foo=bar | | Environment=foo=bar | --env foo=bar |
| EnvironmentFile=/tmp/env | --env-file /tmp/env | | EnvironmentFile=/tmp/env | --env-file /tmp/env |
| EnvironmentHost=true | --env-host | | EnvironmentHost=true | --env-host |
| Exec=/usr/bin/command | Command after image specification - /usr/bin/command | | Exec=/usr/bin/command | Command after image specification - /usr/bin/command |
| ExposeHostPort=50-59 | --expose 50-59 | | ExposeHostPort=50-59 | --expose 50-59 |
| Group=1234 | --user UID:1234 | | Group=1234 | --user UID:1234 |
| HealthCmd="/usr/bin/command" | --health-cmd="/usr/bin/command" | | HealthCmd="/usr/bin/command" | --health-cmd="/usr/bin/command" |
| HealthInterval=2m | --health-interval=2m | | HealthInterval=2m | --health-interval=2m |
| HealthOnFailure=kill | --health-on-failure=kill | | HealthOnFailure=kill | --health-on-failure=kill |
| HealthRetries=5 | --health-retries=5 | | HealthRetries=5 | --health-retries=5 |
| HealthStartPeriod=1m | --health-start-period=period=1m | | HealthStartPeriod=1m | --health-start-period=period=1m |
| HealthStartupCmd="/usr/bin/command" | --health-startup-cmd="/usr/bin/command" | | HealthStartupCmd="command" | --health-startup-cmd="command" |
| HealthStartupInterval=1m | --health-startup-interval=2m | | HealthStartupInterval=1m | --health-startup-interval=2m |
| HealthStartupRetries=8 | --health-startup-retries=8 | | HealthStartupRetries=8 | --health-startup-retries=8 |
| HealthStartupSuccess=2 | --health-startup-success=2 | | HealthStartupSuccess=2 | --health-startup-success=2 |
| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s | | HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s |
| HealthTimeout=20s | --health-timeout=20s | | HealthTimeout=20s | --health-timeout=20s |
| HostName=new-host-name | --hostname="new-host-name" | | HostName=new-host-name | --hostname="new-host-name" |
| Image=ubi8 | Image specification - ubi8 | | Image=ubi8 | Image specification - ubi8 |
| IP=192.5.0.1 | --ip 192.5.0.0 | | IP=192.5.0.1 | --ip 192.5.0.0 |
| IP6=fd46:db93:aa76:ac37::10 | --ip6 2001:db8::1 | | IP6=fd46:db93:aa76:ac37::10 | --ip6 2001:db8::1 |
| Label="YXZ" | --label "XYZ" | | Label="YXZ" | --label "XYZ" |
| LogDriver=journald | --log-driver journald | | LogDriver=journald | --log-driver journald |
| Mount=type=bind,source=/path/on/host,destination=/path/in/container | --mount type=bind,source=/path/on/host,destination=/path/in/container | | Mount=type=... | --mount type=... |
| Network=host | --net host | | Network=host | --net host |
| NoNewPrivileges=true | --security-opt no-new-privileges | | NoNewPrivileges=true | --security-opt no-new-privileges |
| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs | | Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs |
| Notify=true | --sdnotify container | | Notify=true | --sdnotify container |
| PodmanArgs=--add-host foobar | --add-host foobar | | PodmanArgs=--add-host foobar | --add-host foobar |
| PublishPort=true | --publish | | PublishPort=true | --publish |
| ReadOnly=true | --read-only | | ReadOnly=true | --read-only |
| RunInit=true | --init | | RunInit=true | --init |
| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json | | SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json |
| SecurityLabelDisable=true | --security-opt label=disable | | SecurityLabelDisable=true | --security-opt label=disable |
| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t | | SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t |
| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 | | SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 |
| SecurityLabelType=spc_t | --security-opt label=type:spc_t | | SecurityLabelType=spc_t | --security-opt label=type:spc_t |
| Timezone=local | --tz local | | Timezone=local | --tz local |
| Tmpfs=/work | --tmpfs /work | | Tmpfs=/work | --tmpfs /work |
| User=bin | --user bin | | User=bin | --user bin |
| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | | UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 |
| VolatileTmp=true | --tmpfs /tmp | | VolatileTmp=true | --tmpfs /tmp |
| Volume=/source:/dest | --volume /source:/dest | | Volume=/source:/dest | --volume /source:/dest |
Description of `[Container]` section are: Description of `[Container]` section are:

176
hack/man-page-table-check Executable file
View File

@ -0,0 +1,176 @@
#!/usr/bin/perl
#
# man-page-table-check - workaround for go-md2man bug that screws up tables
#
package Podman::ManPage::TableCheck;
use v5.14;
use utf8;
use strict;
use warnings;
(our $ME = $0) =~ s|.*/||;
###############################################################################
# BEGIN boilerplate args checking, usage messages
sub usage {
print <<"END_USAGE";
Usage: $ME [OPTIONS]
$ME checks man pages (the *roff files produced
by go-md2man) for empty table cells. Reason: go-md2man cannot handle
markdown characters (e.g. asterisk) in tables. It produces horribly
broken *roff which in turn makes unreadable man pages.
If $ME finds broken tables, it will highlight them
and display hints on how to resolve the problem.
OPTIONS:
--help display this message
END_USAGE
exit;
}
# Command-line options. Note that this operates directly on @ARGV !
our $debug = 0;
our $force = 0;
our $verbose = 0;
our $NOT = ''; # print "blahing the blah$NOT\n" if $debug
sub handle_opts {
use Getopt::Long;
GetOptions(
'debug!' => \$debug,
help => \&usage,
) or die "Try `$ME --help' for help\n";
}
# END boilerplate args checking, usage messages
###############################################################################
############################## CODE BEGINS HERE ###############################
# The term is "modulino".
__PACKAGE__->main() unless caller();
# Main code.
sub main {
# Note that we operate directly on @ARGV, not on function parameters.
# This is deliberate: it's because Getopt::Long only operates on @ARGV
# and there's no clean way to make it use @_.
handle_opts(); # will set package globals
die "$ME: Too many arguments; try $ME --help\n" if @ARGV;
my $manpage_dir = 'docs/build/man'; # FIXME-hardcoding
opendir my $dir_fh, $manpage_dir
or die "$ME: Cannot opendir $manpage_dir: $!\n";
my @manpages;
for my $ent (sort readdir $dir_fh) {
next unless $ent =~ /^[a-z].*\.[1-8][a-z]?$/; # groff files only
next if -l "$manpage_dir/$ent"; # skip links
push @manpages, $ent;
}
closedir $dir_fh;
@manpages
or die "$ME: did not find any .[1-8] files under $manpage_dir\n";
my $errs = 0;
for my $file (@manpages) {
$errs += check_tables("$manpage_dir/$file");
}
exit 0 if !$errs;
die "\n$ME: found empty cells in the above man page(s)
This is a bug in go-md2man: it gets really confused when it sees
misaligned vertical-bar signs ('|') in tables, or a left-hand
column with more than 31 characters.
WORKAROUND: find the above line(s) in the docs/source/markdown file,
then fix the issue (left as exercise for the reader). Keep regenerating
docs until it passes:
\$ make -C docs clean;make docs;$0
"
}
sub check_tables {
my $path = shift;
my $status = 0;
my @cmd = ('man', '-l', '--no-hyphenation', '-Tlatin1', '-');
pipe my $fh_read, my $fh_write;
my $kidpid = fork;
if ($kidpid) { # we are the parent
close $fh_write;
}
elsif (defined $kidpid) { # we are the child
close $fh_read;
open my $fh_in, '<:utf8', $path
or die "$ME: Could not read $path: $!\n";
# groff spits out nasty useless warnings
close STDERR;
open STDOUT, '>&', $fh_write;
open my $fh_man, '|-', @cmd
or die "$ME: Could not fork: $! (message will never be seen)\n";
while (my $line = <$fh_in>) {
$line =~ s/✅/OK/g;
print { $fh_man } $line;
}
close $fh_in or die;
close $fh_man or die;
exit 0;
}
else { # fork failed
die "$ME: could not fork: $!";
}
my $linecount = 0;
my $want = 0;
while (my $line = <$fh_read>) {
++$linecount;
chomp $line;
# Table borders (+----------+------------+)
if ($line =~ /^\s*\+-+\+-+/) {
$want = 1;
next;
}
# Row immediately after table borders
elsif ($want) {
# print $line, "\n";
# *Two* blank cells is OK, go-md2man always does this
# on the last row of each table.
if ($line !~ /^\s*\|\s+\|\s+\|/) {
if ($line =~ /\|\s+\|/) {
warn "\n$ME: $path:\n" if $status == 0;
warn " $line\n";
$status = 1;
}
}
}
$want = 0;
}
close $fh_read;
die "$ME: $path: command failed: @cmd\n" if $?;
waitpid $kidpid, 0;
if ($linecount < 10) {
die "$ME: $path: nothing seen!\n";
}
return $status;
}
1;