diff --git a/Makefile b/Makefile index dcdc1d578c..65b5615bc8 100644 --- a/Makefile +++ b/Makefile @@ -95,7 +95,7 @@ OCI_RUNTIME ?= "" MANPAGES_SOURCE_DIR = docs/source/markdown MANPAGES_MD_IN ?= $(wildcard $(MANPAGES_SOURCE_DIR)/*.md.in) MANPAGES_MD_GENERATED ?= $(MANPAGES_MD_IN:%.md.in=%.md) -MANPAGES_MD ?= $(sort $(wildcard $(MANPAGES_SOURCE_DIR)/*.md) $(MANPAGES_MD_GENERATED)) +MANPAGES_MD ?= $(sort $(wildcard $(MANPAGES_SOURCE_DIR)/*.md) $(MANPAGES_MD_GENERATED) $(MANPAGES_SOURCE_DIR)/podman-troubleshooting.7.md) MANPAGES ?= $(MANPAGES_MD:%.md=%) MANPAGES_DEST ?= $(subst markdown,man, $(subst source,build,$(MANPAGES))) @@ -523,15 +523,19 @@ pkg/api/swagger.yaml: .install.swagger $(MANPAGES_MD_GENERATED): %.md: %.md.in $(MANPAGES_SOURCE_DIR)/options/*.md hack/markdown-preprocess +$(MANPAGES_SOURCE_DIR)/podman-troubleshooting.7.md: troubleshooting.md + ( echo "% podman-troubleshooting 7"; echo; sed -e '/logo.*\.png/d' <$< ) >$@.tmp.$$ && \ + mv $@.tmp.$$ $@ + $(MANPAGES): OUTFILE=$(subst source/markdown,build/man,$@) $(MANPAGES): %: %.md .install.md2man docdir # This does a bunch of filtering needed for man pages: -# 1. Strip markdown link targets like '[podman(1)](podman.1.md)' +# 1. Convert all markdown site links to plain text: +# [foo](https://www.....) -> foo +# 2. Strip man-page targets like '[podman(1)](podman.1.md)' # to just '[podman(1)]', because man pages have no link mechanism; -# 2. Then remove the brackets: '[podman(1)]' -> 'podman(1)'; -# 3. Then do the same for all other markdown links, -# like '[cgroups(7)](https://.....)' -> just 'cgroups(7)'; +# 3. Then remove the brackets: '[podman(1)]' -> 'podman(1)'; # 4. Remove HTML-ish stuff like '..' and '..' # 5. Replace "\" (backslash) at EOL with two spaces (no idea why) # Then two sanity checks: @@ -545,11 +549,11 @@ $(MANPAGES): %: %.md .install.md2man docdir # ASCII art. I (esm) believe the cost of releasing corrupt man pages # is higher than the cost of carrying this kludge. # - @$(SED) -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g' \ - -e 's/\[\(podman[^]]*\)\]/\1/g' \ - -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \ - -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \ - -e 's/\\$$/ /g' $< |\ + @$(SED) -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \ + -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g' \ + -e 's/\[\(podman[^]]*\)\]/\1/g' \ + -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \ + -e 's/\\$$/ /g' $< |\ $(GOMD2MAN) -out $(OUTFILE) @if grep 'included file options/' $(OUTFILE); then \ echo "FATAL: man pages must not contain ^^^^ in $(OUTFILE)"; exit 1; \ @@ -910,10 +914,12 @@ install.modules-load: # This should only be used by distros which might use ipta install.man: install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man1 install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man5 + install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man7 install ${SELINUXOPT} -m 644 $(filter %.1,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man1 install ${SELINUXOPT} -m 644 docs/source/markdown/links/*1 $(DESTDIR)$(MANDIR)/man1 install ${SELINUXOPT} -m 644 $(filter %.5,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man5 install ${SELINUXOPT} -m 644 docs/source/markdown/links/*5 $(DESTDIR)$(MANDIR)/man5 + install ${SELINUXOPT} -m 644 $(filter %.7,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man7 .PHONY: install.completions install.completions: diff --git a/docs/Makefile b/docs/Makefile index 4e982e27fb..698a3ca1d8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,7 +15,7 @@ help: clean: $(RM) -fr build - cd source/markdown && $(RM) -f $$(<.gitignore) + cd source/markdown && $(RM) -f $$(<.gitignore) podman-troubleshooting.7.md .PHONY: help Makefile diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 29bbf0b411..99b3161bc8 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -58,6 +58,7 @@ podman-start.1.md podman-stats.1.md podman-stop.1.md podman-top.1.md +podman-troubleshooting.7.md podman-unmount.1.md podman-unpause.1.md podman-update.1.md diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 5f647a9cf0..7fb5b27368 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -709,6 +709,11 @@ 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/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/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/common/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/common/blob/main/docs/containerignore.5.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY Aug 2020, Additional options and .containerignore added by Dan Walsh `` diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md index 8fa1c9bb63..7964197553 100644 --- a/docs/source/markdown/podman-commit.1.md +++ b/docs/source/markdown/podman-commit.1.md @@ -125,5 +125,10 @@ $ podman commit -q --change LABEL=io.containers.capabilities=setuid,setgid epic_ ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY December 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-images.1.md.in b/docs/source/markdown/podman-images.1.md.in index 61f916c1b8..9be1766911 100644 --- a/docs/source/markdown/podman-images.1.md.in +++ b/docs/source/markdown/podman-images.1.md.in @@ -243,5 +243,10 @@ docker.io/library/alpine latest 3fd9065eaf02 5 months ago 4.41 MB ## SEE ALSO **[podman(1)](podman.1.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY March 2017, Originally compiled by Dan Walsh `` diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md index ee069c9968..df65f60a41 100644 --- a/docs/source/markdown/podman-machine.1.md +++ b/docs/source/markdown/podman-machine.1.md @@ -39,5 +39,10 @@ environment variable while the machines are running can lead to unexpected behav ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-machine-info(1)](podman-machine-info.1.md)**, **[podman-machine-init(1)](podman-machine-init.1.md)**, **[podman-machine-list(1)](podman-machine-list.1.md)**, **[podman-machine-os(1)](podman-machine-os.1.md)**, **[podman-machine-rm(1)](podman-machine-rm.1.md)**, **[podman-machine-ssh(1)](podman-machine-ssh.1.md)**, **[podman-machine-start(1)](podman-machine-start.1.md)**, **[podman-machine-stop(1)](podman-machine-stop.1.md)**, **[podman-machine-inspect(1)](podman-machine-inspect.1.md)**, **[podman-machine-reset(1)](podman-machine-reset.1.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY March 2021, Originally compiled by Ashley Cui diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 528e570a6f..1441f1ed06 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -226,6 +226,10 @@ $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **containers.conf(1)**, **[cgroups(7)](https://man7.org/linux/man-pages/man7/cgroups.7.html)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. ## HISTORY July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index f42981b36d..02d4e22ca3 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -218,5 +218,10 @@ $ podman --remote pull -q --retry 6 --retry-delay 10s ubi9 ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-push(1)](podman-push.1.md)**, **[podman-login(1)](podman-login.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)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY July 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index 990783bccb..add7c39fb6 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -160,3 +160,8 @@ Storing signatures ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-pull(1)](podman-pull.1.md)**, **[podman-login(1)](podman-login.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)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)** + +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. diff --git a/docs/source/markdown/podman-remote.1.md b/docs/source/markdown/podman-remote.1.md index 2dd94a037e..35cf9fc729 100644 --- a/docs/source/markdown/podman-remote.1.md +++ b/docs/source/markdown/podman-remote.1.md @@ -194,3 +194,8 @@ Podman uses builtin defaults if no containers.conf file is found. ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-system-service(1)](podman-system-service.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** + +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 879dcde569..f2e75701ee 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -904,6 +904,11 @@ NOTE: Use the environment variable `TMPDIR` to change the temporary storage loca ## 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/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)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[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)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY September 2018, updated by Kunal Kushwaha `` diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 80e8b50d93..ecd1763bf7 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -466,10 +466,13 @@ The Overlay file system (OverlayFS) is not supported with kernels prior to 5.12. The Network File System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not supported when running in rootless mode as these file systems do not understand user namespace. However, rootless Podman can make use of an NFS Homedir by modifying the `$HOME/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage. -For more information, see the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/main/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/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/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)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)** +### Troubleshooting + +See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md) +for solutions to common issues. + ## HISTORY Dec 2016, Originally compiled by Dan Walsh diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index e62f068c8c..c38b9b87b5 100755 --- a/hack/xref-helpmsgs-manpages +++ b/hack/xref-helpmsgs-manpages @@ -599,6 +599,10 @@ sub podman_man { elsif ($line =~ /^\#\#\s+SEE\s+ALSO/) { $section = 'see-also'; } + # New section or subsection within SEE ALSO: disable the '**' rules. + elsif ($line =~ /^\#\#+/ && $section eq 'see-also') { + $section = ''; + } elsif ($line =~ /^\#\#[^#]/) { $section = ''; } diff --git a/rpm/podman.spec b/rpm/podman.spec index b93ef3c2cd..6b3cee152d 100644 --- a/rpm/podman.spec +++ b/rpm/podman.spec @@ -274,7 +274,7 @@ PODMAN_VERSION=%{version} %{__make} DESTDIR=%{buildroot} PREFIX=%{_prefix} ETCDI sed -i 's;%{buildroot};;g' %{buildroot}%{_bindir}/docker # do not include docker and podman-remote man pages in main package -for file in `find %{buildroot}%{_mandir}/man[15] -type f | sed "s,%{buildroot},," | grep -v -e %{name}sh.1 -e remote -e docker`; do +for file in `find %{buildroot}%{_mandir}/man[157] -type f | sed "s,%{buildroot},," | grep -v -e %{name}sh.1 -e remote -e docker`; do echo "$file*" >> %{name}.file-list done