6 files changed, 32 insertions, 36 deletions
diff --git a/docs/README.md b/docs/README.md
index 0f2af16d6..abe7d7758 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,7 +13,6 @@ link on that page.
 | ------------------------------------ | --------------------------- |
 | Markdown source for man pages        | docs/source/markdown/       |
 | man pages aliases as .so files       | docs/source/markdown/links/ |
-| restructured text for readthedocs.io | docs/rst/                   |
 | target for output                    | docs/build                  |
 | man pages                            | docs/build/man              |
 | remote linux man pages               | docs/build/remote/linux     |
@@ -60,16 +59,24 @@ incorrect, or the file isn't accessible for some other reason.
 
 ## Local Testing
 
-Assuming that you have the [dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies)
+To build standard man pages, run `make docs`. Results will be in `docs/build/man`.
+
+To build HTMLized man pages: Assuming that you have the
+[dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies)
 installed, then also install (showing Fedora in the example):
 
 ```
-# dnf install python3-sphinx python3-recommonmark
-# pip install sphinx-markdown-tables
+$ sudo dnf install python3-sphinx python3-recommonmark
+$ pip install sphinx-markdown-tables myst_parser
 ```
+(The above dependencies are current as of 2022-09-15. If you experience problems,
+please see [requirements.txt](requirements.txt) in this directory, it will almost
+certainly be more up-to-date than this README.)
+
 After that completes, cd to the `docs` directory in your Podman sandbox and then do `make html`.
 
 You can then preview the html files in `docs/build/html` with:
 ```
 python -m http.server 8000 --directory build/html
 ```
+...and point your web browser at `http://localhost:8000/`
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b58bb3f46..345e289e1 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -86,12 +86,12 @@ def convert_markdown_title(app, docname, source):
     if docpath.endswith(".md"):
         # Convert pandoc title line into eval_rst block for myst_parser
         #
-        # Remove the ending "(1)" to avoid it from being displayed
+        # Remove the ending " 1" (section) to avoid it from being displayed
         # in the web tab. Often such a text indicates that
         # a web page got an update. For instance GitHub issues
         # shows the number of new comments that have been written
         # after the user's last visit.
-        source[0] = re.sub(r"^% (.*)(\(\d\))", r"```{title} \g<1>\n```", source[0])
+        source[0] = re.sub(r"^% (.*)\s(\d)", r"```{title} \g<1>\n```", source[0])
 
 def setup(app):
     app.connect("source-read", convert_markdown_title)
diff --git a/docs/source/markdown/options/dns.md b/docs/source/markdown/options/dns.md
new file mode 100644
index 000000000..39380ace2
--- /dev/null
+++ b/docs/source/markdown/options/dns.md
@@ -0,0 +1,11 @@
+#### **--dns**=*ipaddr*
+
+Set custom DNS servers.
+
+This option can be used to override the DNS
+configuration passed to the container. Typically this is necessary when the
+host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this
+is the case the **--dns** flag is necessary for every run.
+
+The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman.
+The _/etc/resolv.conf_ file in the image will be used without changes.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 94644a051..e201806e5 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -223,18 +223,12 @@ specifying **--disable-compression=false**.
 
 @@option disable-content-trust
 
-#### **--dns**=*dns*
+@@option dns
 
-Set custom DNS servers to be used during the build.
+This option cannot be combined with **--network** that is set to **none**.
 
-This option can be used to override the DNS configuration passed to the
-container. Typically this is necessary when the host DNS configuration is
-invalid for the container (e.g., 127.0.0.1). When this is the case the `--dns`
-option is necessary for every run.
-
-The special value **none** can be specified to disable creation of
-/etc/resolv.conf in the container by Podman. The /etc/resolv.conf file in the
-image will be used without changes.
+Note: this option takes effect only during *RUN* instructions in the build.
+It does not affect _/etc/resolv.conf_ in the final image.
 
 #### **--dns-option**=*option*
 
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 835976eba..72f167a7e 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -141,17 +141,9 @@ flag to pass the user's supplementary group access into the container.
 
 @@option disable-content-trust
 
-#### **--dns**=*dns*
+@@option dns
 
-Set custom DNS servers. Invalid if using **--dns** and **--network** that is set to 'none' or `container:<name|id>`.
-
-This option can be used to override the DNS
-configuration passed to the container. Typically this is necessary when the
-host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this
-is the case the **--dns** flag is necessary for every run.
-
-The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman.
-The **/etc/resolv.conf** file in the image will be used without changes.
+This option cannot be combined with **--network** that is set to **none** or **container:**_id_.
 
 @@option dns-opt.container
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index b4bb107d6..37d052646 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -177,17 +177,9 @@ flag to pass the user's supplementary group access into the container.
 
 @@option disable-content-trust
 
-#### **--dns**=*ipaddr*
+@@option dns
 
-Set custom DNS servers. Invalid if using **--dns** with **--network** that is set to **none** or **container:**_id_.
-
-This option can be used to override the DNS
-configuration passed to the container. Typically this is necessary when the
-host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this
-is the case the **--dns** flag is necessary for every run.
-
-The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman.
-The _/etc/resolv.conf_ file in the image will be used without changes.
+This option cannot be combined with **--network** that is set to **none** or **container:**_id_.
 
 @@option dns-opt.container