Document man page sync with the new website

deps/rabbit/docs/.gitignore

@@ -0,0 +1,3 @@
+*.html
+*.md
+

deps/rabbit/docs/README.md

@@ -9,9 +9,24 @@ This directory contains [CLI tools](https://rabbitmq.com/docs/cli/) man page sou
 Please [see rabbitmq.com](https://rabbitmq.com/docs/) for documentation guides.
 
 
+## man Pages
 
+### Dependencies
 
-## man Pages
+ * `man`
+ * [`tidy5`](https://binaries.html-tidy.org/) (a.k.a. `tidy-html5`)
+
+On macOS, `tidy5` can be installed with Homebrew:
+
+``` shell
+brew install tidy-html5
+```
+
+and then be found under the `bin` directory of the Homebrew cellar:
+
+``` shell
+/opt/homebrew/bin/tidy --help
+```
 
 ### Source Files
 
@@ -25,14 +40,24 @@ man docs/rabbitmq-diagnostics.8
 man docs/rabbitmq-queues.8
 ```
 
-
 To converted all man pages to HTML using `mandoc`:
 
 ``` shell
 gmake web-manpages
 ```
 
-The result is then copied to the [website repository](https://github.com/rabbitmq/rabbitmq-website/tree/live/site/man)
+The result then must be post-processed and copied to the website repository:
+
+``` shell
+# cd deps/rabbit/docs
+#
+# clear all generated HTML and Markdown files
+rm *.html *.md
+# export tidy5 path
+export TIDY5_BIN=/opt/homebrew/bin/tidy;
+# run the post-processing script, in this case it updates the 3.13.x version of the docs
+./postprocess_man_html.sh . /path/to/rabbitmq-website.git/versioned_docs/version-3.13/man/
+```
 
 ### Contributions
 

deps/rabbit/docs/postprocess_man_html.sh

@@ -0,0 +1,92 @@
+#!/bin/sh
+
+set -e
+
+srcdir="$1"
+destdir="$2"
+
+tidy_bin=${TIDY5_BIN:-"tidy5"}
+
+for src in "$srcdir"/*.html; do
+	name=$(basename "$src" .html)
+	dest="$destdir/$name.md"
+	echo "src=$src" "dest=$dest" "name=$name"
+
+	cat <<EOF > "$dest"
+---
+title: $name
+---
+EOF
+
+$tidy_bin -i --wrap 0 \
+		--asxhtml \
+		--show-body-only yes \
+		--drop-empty-elements yes \
+		--drop-empty-paras yes \
+		--enclose-block-text yes \
+		--enclose-text yes "$src" \
+		| \
+	awk '
+	/<h[1-6]/ {
+		if ($0 ~ /<h1/) {
+			level = "#";
+		} else if ($0 ~ /<h2/) {
+			level = "##";
+		} else if ($0 ~ /<h2/) {
+			level = "##";
+		} else if ($0 ~ /<h3/) {
+			level = "###";
+		} else if ($0 ~ /<h4/) {
+			level = "####";
+		} else if ($0 ~ /<h5/) {
+			level = "#####";
+		} else if ($0 ~ /<h6/) {
+			level = "######";
+		}
+
+		id = $0;
+		sub(/.*(id|name)="/, "", id);
+		sub(/".*/, "", id);
+
+		title = $0;
+		sub(/ *<\/.*/, "", title);
+		sub(/.*> */, "", title);
+
+		print level, title, "{#" id "}";
+		next;
+	}
+	/dt id="/ {
+		id = $0;
+		sub(/.*(id|name)="/, "", id);
+		sub(/".*/, "", id);
+
+		line = $0;
+		sub(/id="[^"]*"/, "", line);
+		print line;
+
+		next;
+	}
+	/a class="permalink"/ {
+		title = $0;
+		sub(/ *<a [^>]*>/, "", title);
+		sub(/<\/a>/, "", title);
+		sub(/<br[^>]*>/, "", title);
+		gsub(/>\*</, ">\\&ast;<", title);
+
+		print level "#", title, "{#" id "}";
+		next;
+	}
+	{
+		line = $0;
+		gsub(/{/, "\\&lcub;", line);
+		gsub(/<li>/, "<li>\n", line);
+		gsub(/<\/li>/, "\n</li>", line);
+		gsub(/<\/ul>/, "</ul>\n", line);
+		gsub(/<br[^>]*>/, "<br\/>", line);
+		gsub(/<\/div>]/, "<\/div>\n]", line);
+		gsub(/style="[^"]*"/, "", line);
+		print line;
+		next;
+	}
+	' > "$dest"
+done