On Fri, Aug 04, 2023 at 12:54:31PM +0100, Colin Watson wrote:
> On Wed, Jul 26, 2023 at 10:21:34PM +0200, Lucas Nussbaum wrote:
> > > an.tmac:lib/ovs-fields.7:762: warning: tbl preprocessor failed, or it or
> > > soelim was not run; table(s) likely not rendered (TE macro called with TW
> > > register undefined)
>
> I've sent a patch set for this upstream. It's currently waiting for
> mailing list moderation, but I've attached the messages here.
Frode Nordahl pointed out that this patch set introduces warnings with
earlier versions of groff. Here's an updated version that doesn't.
--
Colin Watson (he/him) [cjwat...@ubuntu.com]
--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
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
--- End Message ---
