Skip to content

Commit 146b486

Browse files
michaelklishinmichaelklishin
authored
Merge pull request #12007 from rabbitmq/mergify/bp/v3.13.x/pr-12006
Initial man page updates for 4.0 (backport #12005) (backport #12006)
2 parents 90beee7 + 8a454e1 commit 146b486

13 files changed

+156
-28
lines changed

‎deps/rabbit/docs/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.html
2+
*.md
3+

‎deps/rabbit/docs/README.md

Lines changed: 45 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,63 @@
11
# Manual Pages and Documentation Extras
22

3-
This directory contains [CLI tool](https://rabbitmq.com/cli.html) man page sources as well as a few documentation extras:
3+
This directory contains [CLI tools](https://rabbitmq.com/docs/cli/) man page sources as well as a few documentation extras:
44

5-
* An [annotated rabbitmq.conf example](./rabbitmq.conf.example) (see [new style configuration format](https://www.rabbitmq.com/configure.html#config-file-formats))
6-
* An [annotated advanced.config example](./advanced.config.example) (see [The advanced.config file](https://www.rabbitmq.com/configure.html#advanced-config-file))
5+
* An [annotated rabbitmq.conf example](./rabbitmq.conf.example) (see [new style configuration format](https://www.rabbitmq.com/docs/configure#config-file-formats))
6+
* An [annotated advanced.config example](./advanced.config.example) (see [The advanced.config file](https://www.rabbitmq.com/docs/configure#advanced-config-file))
77
* A [systemd unit file example](./rabbitmq-server.service.example)
88

9-
Please [see rabbitmq.com](https://rabbitmq.com/documentation.html) for documentation guides.
9+
Please [see rabbitmq.com](https://rabbitmq.com/docs/) for documentation guides.
1010

1111

12-
## Classic Config File Format Example
12+
## man Pages
1313

14-
Feeling nostalgic and looking for the [classic configuration file example](https://github.com/rabbitmq/rabbitmq-server/blob/v3.7.x/docs/rabbitmq.config.example)?
15-
Now that's old school! Keep in mind that classic configuration file **should be considered deprecated**.
16-
Prefer `rabbitmq.conf` (see [new style configuration format](https://www.rabbitmq.com/configure.html#config-file-formats))
17-
with an `advanced.config` to complement it as needed.
14+
### Dependencies
1815

16+
* `man`
17+
* [`tidy5`](https://binaries.html-tidy.org/) (a.k.a. `tidy-html5`)
1918

20-
## man Pages
19+
On macOS, `tidy5` can be installed with Homebrew:
20+
21+
``` shell
22+
brew install tidy-html5
23+
```
24+
25+
and then be found under the `bin` directory of the Homebrew cellar:
26+
27+
``` shell
28+
/opt/homebrew/bin/tidy --help
29+
```
2130

2231
### Source Files
2332

24-
This directory contains man pages that are converted to HTML using `mandoc`:
33+
This directory contains man pages in ntroff, the man page format.
34+
35+
To inspect a local version, use `man`:
36+
37+
``` shell
38+
man docs/rabbitmq-diagnostics.8
39+
40+
man docs/rabbitmq-queues.8
41+
```
42+
43+
To converted all man pages to HTML using `mandoc`:
44+
45+
``` shell
46+
gmake web-manpages
47+
```
2548

26-
gmake web-manpages
49+
The result then must be post-processed and copied to the website repository:
2750

28-
The result is then copied to the [website repository](https://github.com/rabbitmq/rabbitmq-website/tree/live/site/man)
51+
``` shell
52+
# cd deps/rabbit/docs
53+
#
54+
# clear all generated HTML and Markdown files
55+
rm *.html *.md
56+
# export tidy5 path
57+
export TIDY5_BIN=/opt/homebrew/bin/tidy;
58+
# run the post-processing script, in this case it updates the 3.13.x version of the docs
59+
./postprocess_man_html.sh . /path/to/rabbitmq-website.git/versioned_docs/version-3.13/man/
60+
```
2961

3062
### Contributions
3163

‎deps/rabbit/docs/postprocess_man_html.sh

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/bin/sh
2+
3+
set -e
4+
5+
srcdir="$1"
6+
destdir="$2"
7+
8+
tidy_bin=${TIDY5_BIN:-"tidy5"}
9+
10+
for src in "$srcdir"/*.html; do
11+
name=$(basename "$src" .html)
12+
dest="$destdir/$name.md"
13+
echo "src=$src" "dest=$dest" "name=$name"
14+
15+
cat <<EOF > "$dest"
16+
---
17+
title: $name
18+
---
19+
EOF
20+
21+
$tidy_bin -i --wrap 0 \
22+
--asxhtml \
23+
--show-body-only yes \
24+
--drop-empty-elements yes \
25+
--drop-empty-paras yes \
26+
--enclose-block-text yes \
27+
--enclose-text yes "$src" \
28+
| \
29+
awk '
30+
/<h[1-6]/ {
31+
if ($0 ~ /<h1/) {
32+
level = "#";
33+
} else if ($0 ~ /<h2/) {
34+
level = "##";
35+
} else if ($0 ~ /<h2/) {
36+
level = "##";
37+
} else if ($0 ~ /<h3/) {
38+
level = "###";
39+
} else if ($0 ~ /<h4/) {
40+
level = "####";
41+
} else if ($0 ~ /<h5/) {
42+
level = "#####";
43+
} else if ($0 ~ /<h6/) {
44+
level = "######";
45+
}
46+
47+
id = $0;
48+
sub(/.*(id|name)="/, "", id);
49+
sub(/".*/, "", id);
50+
51+
title = $0;
52+
sub(/ *<\/.*/, "", title);
53+
sub(/.*> */, "", title);
54+
55+
print level, title, "{#" id "}";
56+
next;
57+
}
58+
/dt id="/ {
59+
id = $0;
60+
sub(/.*(id|name)="/, "", id);
61+
sub(/".*/, "", id);
62+
63+
line = $0;
64+
sub(/id="[^"]*"/, "", line);
65+
print line;
66+
67+
next;
68+
}
69+
/a class="permalink"/ {
70+
title = $0;
71+
sub(/ *<a [^>]*>/, "", title);
72+
sub(/<\/a>/, "", title);
73+
sub(/<br[^>]*>/, "", title);
74+
gsub(/>\*</, ">\\&ast;<", title);
75+
76+
print level "#", title, "{#" id "}";
77+
next;
78+
}
79+
{
80+
line = $0;
81+
gsub(/{/, "\\&lcub;", line);
82+
gsub(/<li>/, "<li>\n", line);
83+
gsub(/<\/li>/, "\n</li>", line);
84+
gsub(/<\/ul>/, "</ul>\n", line);
85+
gsub(/<br[^>]*>/, "<br\/>", line);
86+
gsub(/<\/div>]/, "<\/div>\n]", line);
87+
gsub(/style="[^"]*"/, "", line);
88+
print line;
89+
next;
90+
}
91+
' > "$dest"
92+
done

‎deps/rabbit/docs/rabbitmq-diagnostics.8

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -697,10 +697,10 @@ See
697697
.Cm quorum_status
698698
in
699699
.Xr rabbitmq-queues 8
700-
.It Cm check_if_node_is_mirror_sync_critical
700+
.It Cm check_if_cluster_has_classic_queue_mirroring_policy
701701
.Pp
702702
See
703-
.Cm check_if_node_is_mirror_sync_critical
703+
.Cm check_if_cluster_has_classic_queue_mirroring_policy
704704
in
705705
.Xr rabbitmq-queues 8
706706
.It Cm check_if_node_is_quorum_critical
@@ -723,4 +723,4 @@ in
723723
.\" ------------------------------------------------------------------
724724
.Sh AUTHOR
725725
.\" ------------------------------------------------------------------
726-
.An The RabbitMQ Team Aq Mt [email protected].com
726+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-echopid.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,4 +67,4 @@ The short-name form of the RabbitMQ node name.
6767
.\" ------------------------------------------------------------------
6868
.Sh AUTHOR
6969
.\" ------------------------------------------------------------------
70-
.An The RabbitMQ Team Aq Mt [email protected].com
70+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-env.conf.5

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,4 +84,4 @@ file RabbitMQ configuration file location is changed to "/data/services/rabbitmq
8484
.\" ------------------------------------------------------------------
8585
.Sh AUTHOR
8686
.\" ------------------------------------------------------------------
87-
.An The RabbitMQ Team Aq Mt [email protected].com
87+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-plugins.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,4 +252,4 @@ plugin and its dependencies and disables everything else:
252252
.\" ------------------------------------------------------------------
253253
.Sh AUTHOR
254254
.\" ------------------------------------------------------------------
255-
.An The RabbitMQ Team Aq Mt [email protected].com
255+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-queues.8

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -182,13 +182,14 @@ This command is currently only supported by quorum queues.
182182
Example:
183183
.Sp
184184
.Dl rabbitmq-queues peek --vhost Qo a-vhost Qc Qo a-queue Qc Qo 1 Qc
185-
.It Cm check_if_node_is_mirror_sync_critical
185+
.It Cm check_if_cluster_has_classic_queue_mirroring_policy
186186
.Pp
187-
Health check that exits with a non-zero code if there are classic mirrored queues without online synchronised mirrors (queues that would potentially lose data if the target node is shut down).
187+
Health check that exits with a non-zero code if there are policies in the cluster that enable classic queue mirroring.
188+
Classic queue mirroring has been deprecated since 2021 and was completely removed in the RabbitMQ 4.0 development cycle.
188189
.Pp
189190
Example:
190191
.Sp
191-
.Dl rabbitmq-queues check_if_node_is_mirror_sync_critical
192+
.Dl rabbitmq-queues check_if_cluster_has_classic_queue_mirroring_policy
192193
.It Cm check_if_node_is_quorum_critical
193194
.Pp
194195
Health check that exits with a non-zero code if there are queues with minimum online quorum (queues that would lose their quorum if the target node is shut down).
@@ -210,4 +211,4 @@ Example:
210211
.\" ------------------------------------------------------------------
211212
.Sh AUTHOR
212213
.\" ------------------------------------------------------------------
213-
.An The RabbitMQ Team Aq Mt [email protected].com
214+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-server.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,4 +96,4 @@ For example, runs RabbitMQ AMQP server in the background:
9696
.\" ------------------------------------------------------------------
9797
.Sh AUTHOR
9898
.\" ------------------------------------------------------------------
99-
.An The RabbitMQ Team Aq Mt [email protected].com
99+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-service.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,4 +150,4 @@ is to discard the server output.
150150
.\" ------------------------------------------------------------------
151151
.Sh AUTHOR
152152
.\" ------------------------------------------------------------------
153-
.An The RabbitMQ Team Aq Mt [email protected].com
153+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-streams.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -447,4 +447,4 @@ for each consumer attached to the stream-1 stream and belonging to the stream-1
447447
.\" ------------------------------------------------------------------
448448
.Sh AUTHOR
449449
.\" ------------------------------------------------------------------
450-
.An The RabbitMQ Team Aq Mt [email protected].com
450+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmq-upgrade.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,4 +127,4 @@ To learn more, see the
127127
.\" ------------------------------------------------------------------
128128
.Sh AUTHOR
129129
.\" ------------------------------------------------------------------
130-
.An The RabbitMQ Team Aq Mt [email protected].com
130+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

‎deps/rabbit/docs/rabbitmqctl.8

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2489,4 +2489,4 @@ Reset the stats database for all nodes in the cluster.
24892489
.\" ------------------------------------------------------------------------------------------------
24902490
.Sh AUTHOR
24912491
.\" ------------------------------------------------------------------------------------------------
2492-
.An The RabbitMQ Team Aq Mt [email protected].com
2492+
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

0 commit comments

Comments
 (0)