On Mon, Aug 07, 2023 at 04:45:30PM +0200, Thomas Goirand wrote: > Ok, so if there's only 5 patches, not 6, then I should be able to manage > (even though it's not the best convenient way). Thanks for your patches.
I think I possibly understand what you meant now. Is this more convenient? -- Colin Watson (he/him) [cjwat...@debian.org]
>From 45a2a2245f6c73dc6898f63c8d30ffd138920066 Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 18:22:31 +0100 Subject: [PATCH v2 0/5] docs: Fix manpage-check warnings with groff 1.23.0 https://bugs.debian.org/1042358 reported a manpage-check failure with groff 1.23.0 in Debian testing/unstable. Fixing the immediate mistake here exposed a few other issues in how the tables in ovs-fields(7) are rendered. Colin Watson (5): docs: Wrap more table entries in text blocks docs: Shorten overly-wide table heading docs: Tweak width of name column in field property tables docs: Fix rendering of VLAN Comparison Chart docs: Run tbl preprocessor in manpage-check rule Makefile.am | 2 +- build-aux/extract-ofp-fields | 20 ++++++++++++++------ lib/meta-flow.xml | 25 +++++++++++++------------ 3 files changed, 28 insertions(+), 19 deletions(-) -- 2.39.2
>From 97fb673b2b09747beabe8625ac86dbfc5aa0c023 Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 11:19:06 +0100 Subject: [PATCH v2 1/5] docs: Wrap more table entries in text blocks This fixes a number of "table wider than line length minus indentation" warnings from tbl. The table cells are too narrow for centered text to look good, so left-align the contents of the text blocks. Reported-by: Lucas Nussbaum <lu...@debian.org> Reported-at: https://bugs.debian.org/1042358 Signed-off-by: Colin Watson <cjwat...@ubuntu.com> --- build-aux/extract-ofp-fields | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/build-aux/extract-ofp-fields b/build-aux/extract-ofp-fields index efec59c25..2f566d2b9 100755 --- a/build-aux/extract-ofp-fields +++ b/build-aux/extract-ofp-fields @@ -189,12 +189,14 @@ def field_to_xml(field_node, f, body, summary): ovs_version = [int(x) for x in ovs_version_s.split(".")] if min_ovs_version is None or ovs_version < min_ovs_version: min_ovs_version = ovs_version - summary += ["\\fB%s\\fR" % f["name"]] + summary += ["T{\n.ad l\n\\fB%s\\fR" % f["name"]] if f["extra_name"]: summary += [" aka \\fB%s\\fR" % f["extra_name"]] - summary += [";%d" % f["n_bytes"]] + summary += ["\nT}"] + summary += [";T{\n.ad l\n%d" % f["n_bytes"]] if f["n_bits"] != 8 * f["n_bytes"]: summary += [" (low %d bits)" % f["n_bits"]] + summary += ["\nT}"] summary += [";%s;" % {"MFM_NONE": "no", "MFM_FULLY": "yes"}[f["mask"]]] summary += ["%s;" % {True: "yes", False: "no"}[f["writable"]]] summary += ["%s;" % f["prereqs"]] @@ -203,7 +205,7 @@ def field_to_xml(field_node, f, body, summary): support += ["OF %s+" % VERSION_REVERSE[min_of_version]] if min_ovs_version is not None: support += ["OVS %s+" % ".".join([str(x) for x in min_ovs_version])] - summary += " and ".join(support) + summary += ["T{\n.ad l\n", " and ".join(support), "\nT}"] summary += ["\n"] # Full description. @@ -230,8 +232,10 @@ l lx. body += ["Width:;"] if f["n_bits"] != 8 * f["n_bytes"]: body += [ + "T{\n", "%d bits (only the least-significant %d bits " - "may be nonzero)" % (f["n_bytes"] * 8, f["n_bits"]) + "may be nonzero)" % (f["n_bytes"] * 8, f["n_bits"]), + "\nT}", ] elif f["n_bits"] <= 128: body += ["%d bits" % f["n_bits"]] -- 2.39.2
>From 36207097b0c3de75d562b93e666c54f954da763c Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 18:01:55 +0100 Subject: [PATCH v2 2/5] docs: Shorten overly-wide table heading Using "NXM/OXM Support" makes these tables a little too wide to fit well when rendered in 80 columns, causing warnings from groff. There's already some abbreviation going on here (e.g. "RW?"), so "NXM/OXM?" seems acceptable. Reported-by: Lucas Nussbaum <lu...@debian.org> Reported-at: https://bugs.debian.org/1042358 Signed-off-by: Colin Watson <cjwat...@ubuntu.com> --- build-aux/extract-ofp-fields | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-aux/extract-ofp-fields b/build-aux/extract-ofp-fields index 2f566d2b9..808c6527d 100755 --- a/build-aux/extract-ofp-fields +++ b/build-aux/extract-ofp-fields @@ -323,7 +323,7 @@ def group_xml_to_nroff(group_node, fields): ".TS\n", "tab(;);\n", "l l l l l l l.\n", - "Name;Bytes;Mask;RW?;Prereqs;NXM/OXM Support\n", + "Name;Bytes;Mask;RW?;Prereqs;NXM/OXM?\n", "\_;\_;\_;\_;\_;\_\n", ] content += summary -- 2.39.2
>From 7622daa80dad932cab11febfc8afa6a78b1f84ac Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 18:18:01 +0100 Subject: [PATCH v2 3/5] docs: Tweak width of name column in field property tables groff 1.23.0 has difficulty with hyphenating a number of the entries in the name column of these tables when rendering in 80-column terminals. Setting a minimum width for this column gives it an easier time. Reported-by: Lucas Nussbaum <lu...@debian.org> Reported-at: https://bugs.debian.org/1042358 Signed-off-by: Colin Watson <cjwat...@ubuntu.com> --- build-aux/extract-ofp-fields | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/build-aux/extract-ofp-fields b/build-aux/extract-ofp-fields index 808c6527d..449885981 100755 --- a/build-aux/extract-ofp-fields +++ b/build-aux/extract-ofp-fields @@ -322,7 +322,11 @@ def group_xml_to_nroff(group_node, fields): '.SS "Summary:"\n', ".TS\n", "tab(;);\n", - "l l l l l l l.\n", + # Hardcoding a width of 15 ens is a bit of a hack, but it's wide + # enough to avoid causing troff difficulty with hyphenating long + # identifiers, while still looking reasonable when formatted in wide + # terminals. + "lw15 l l l l l l.\n", "Name;Bytes;Mask;RW?;Prereqs;NXM/OXM?\n", "\_;\_;\_;\_;\_;\_\n", ] -- 2.39.2
>From 12f799ca29d3ee68717470ed59c9dc9319a13846 Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 11:34:15 +0100 Subject: [PATCH v2 4/5] docs: Fix rendering of VLAN Comparison Chart tbl defaults to expecting table entries to be separated by tab characters. However, commit 5a0e4aec1af5cf7741c490bce704577e51e536b9 converted these to spaces and inadvertently broke the rendering. Use semicolons as separators instead; these are less prone to being broken by tree-wide changes, and match the style used by build-aux/extract-ofp-fields. Reported-by: Lucas Nussbaum <lu...@debian.org> Reported-at: https://bugs.debian.org/1042358 Signed-off-by: Colin Watson <cjwat...@ubuntu.com> --- lib/meta-flow.xml | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/lib/meta-flow.xml b/lib/meta-flow.xml index bdd12f6a7..0ac182be1 100644 --- a/lib/meta-flow.xml +++ b/lib/meta-flow.xml @@ -3517,23 +3517,24 @@ actions=clone(load:0->NXM_OF_IN_PORT[],output:123) </p> <tbl> +tab(;); r r r r r. -Criteria OpenFlow 1.0 OpenFlow 1.1 OpenFlow 1.2+ NXM -\_ \_ \_ \_ \_ -[1] \fL????\fR/\fL1\fR,\fL??\fR/\fL?\fR \fL????\fR/\fL1\fR,\fL??\fR/\fL?\fR \fL0000\fR/\fL0000\fR,\fL--\fR \fL0000\fR/\fL0000\fR -[2] \fLffff\fR/\fL0\fR,\fL??\fR/\fL?\fR \fLffff\fR/\fL0\fR,\fL??\fR/\fL?\fR \fL0000\fR/\fLffff\fR,\fL--\fR \fL0000\fR/\fLffff\fR -[3] \fL0xxx\fR/\fL0\fR,\fL??\fR/\fL1\fR \fL0xxx\fR/\fL0\fR,\fL??\fR/\fL1\fR \fL1xxx\fR/\fLffff\fR,\fL--\fR \fL1xxx\fR/\fL1fff\fR -[4] \fL????\fR/\fL1\fR,\fL0y\fR/\fL0\fR \fLfffe\fR/\fL0\fR,\fL0y\fR/\fL0\fR \fL1000\fR/\fL1000\fR,\fL0y\fR \fLz000\fR/\fLf000\fR -[5] \fL0xxx\fR/\fL0\fR,\fL0y\fR/\fL0\fR \fL0xxx\fR/\fL0\fR,\fL0y\fR/\fL0\fR \fL1xxx\fR/\fLffff\fR,\fL0y\fR \fLzxxx\fR/\fLffff\fR +Criteria;OpenFlow 1.0;OpenFlow 1.1;OpenFlow 1.2+;NXM +\_;\_;\_;\_;\_ +[1];\fL????\fR/\fL1\fR,\fL??\fR/\fL?\fR;\fL????\fR/\fL1\fR,\fL??\fR/\fL?\fR;\fL0000\fR/\fL0000\fR,\fL--\fR;\fL0000\fR/\fL0000\fR +[2];\fLffff\fR/\fL0\fR,\fL??\fR/\fL?\fR;\fLffff\fR/\fL0\fR,\fL??\fR/\fL?\fR;\fL0000\fR/\fLffff\fR,\fL--\fR;\fL0000\fR/\fLffff\fR +[3];\fL0xxx\fR/\fL0\fR,\fL??\fR/\fL1\fR;\fL0xxx\fR/\fL0\fR,\fL??\fR/\fL1\fR;\fL1xxx\fR/\fLffff\fR,\fL--\fR;\fL1xxx\fR/\fL1fff\fR +[4];\fL????\fR/\fL1\fR,\fL0y\fR/\fL0\fR;\fLfffe\fR/\fL0\fR,\fL0y\fR/\fL0\fR;\fL1000\fR/\fL1000\fR,\fL0y\fR;\fLz000\fR/\fLf000\fR +[5];\fL0xxx\fR/\fL0\fR,\fL0y\fR/\fL0\fR;\fL0xxx\fR/\fL0\fR,\fL0y\fR/\fL0\fR;\fL1xxx\fR/\fLffff\fR,\fL0y\fR;\fLzxxx\fR/\fLffff\fR .T& r r c c r. -[6] (none) (none) \fL1001\fR/\fL1001\fR,\fL--\fR \fL1001\fR/\fL1001\fR +[6];(none);(none);\fL1001\fR/\fL1001\fR,\fL--\fR;\fL1001\fR/\fL1001\fR .T& r r c c c. -[7] (none) (none) (none) \fL3000\fR/\fL3000\fR -[8] (none) (none) (none) \fL0000\fR/\fL0fff\fR -[9] (none) (none) (none) \fL0000\fR/\fLf000\fR -[10] (none) (none) (none) \fL0000\fR/\fLefff\fR +[7];(none);(none);(none);\fL3000\fR/\fL3000\fR +[8];(none);(none);(none);\fL0000\fR/\fL0fff\fR +[9];(none);(none);(none);\fL0000\fR/\fLf000\fR +[10];(none);(none);(none);\fL0000\fR/\fLefff\fR </tbl> <p> -- 2.39.2
>From 45a2a2245f6c73dc6898f63c8d30ffd138920066 Mon Sep 17 00:00:00 2001 From: Colin Watson <cjwat...@ubuntu.com> Date: Fri, 4 Aug 2023 11:51:30 +0100 Subject: [PATCH v2 5/5] docs: Run tbl preprocessor in manpage-check rule If we omit this, groff 1.23.0 warns: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined) Reported-by: Lucas Nussbaum <lu...@debian.org> Reported-at: https://bugs.debian.org/1042358 Signed-off-by: Colin Watson <cjwat...@ubuntu.com> --- Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile.am b/Makefile.am index db341504d..265cf0a7b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -368,7 +368,7 @@ ALL_LOCAL += manpage-check manpage-check: $(man_MANS) $(dist_man_MANS) $(noinst_man_MANS) @error=false; \ for manpage in $?; do \ - LANG=en_US.UTF-8 groff -w mac -w delim -w escape -w input -w missing -w tab -T utf8 -man -p -z $$manpage >$@.tmp 2>&1; \ + LANG=en_US.UTF-8 groff -t -w mac -w delim -w escape -w input -w missing -w tab -T utf8 -man -p -z $$manpage >$@.tmp 2>&1; \ if grep warning: $@.tmp; then error=:; fi; \ rm -f $@.tmp; \ done; \ -- 2.39.2
