[Bug 290778] 15.0R Hardware Notes cut off ice(4) before listing supported devices

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=290778

            Bug ID: 290778
           Summary: 15.0R Hardware Notes cut off ice(4) before listing
                    supported devices
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Some People
          Priority: ---
         Component: Website
          Assignee: doc@FreeBSD.org
          Reporter: bigsneaky@duck.com

The ice(4) Intel Ethernet 800 Series Driver seems to be correctly included in
the archetypal Hardware Notes: the following line appears in
https://github.com/freebsd/freebsd-doc/blob/main/website/archetypes/release/hardware.adoc

> &hwlist.ice;

But the automatic generation of the Hardware Notes seems to fail, looking at
the output in
https://github.com/freebsd/freebsd-doc/blob/main/website/content/en/releases/15.0R/hardware.adoc

In particular ice(4) entry cuts off prematurely and runs immediately into the
igc(4) driver.

> The ice driver supports 100Gb Ethernet adapters with these QSFP28 modules:
> The igc driver supports the following models:

It ought to have generated a bulleted list of supported devices. Compare to the
Hardware section of the ice(4) man page which the Hardware Notes are generated
from, https://man.freebsd.org/cgi/man.cgi?ice(4)

> The ice driver supports 100Gb Ethernet adapters with these QSFP28 modules:
> • Intel(R) 100G QSFP28 100GBASE-SR4 E100GQSFPSR28SRX
> ...

I have filed this as a "website" bug, though I suspect ultimately the bug
either lies in the tooling that automatically generates the Hardware Notes from
the man pages, or maybe something formatted weirdly in the man page itself
which is confusing the tooling,
https://github.com/freebsd/freebsd-src/blob/main/share/man/man4/ice.4

I'll quote part of the relevant section for convenience. Note that bulleted
lists of devices starting ".Bl -bullet -compact" on other man pages are
generating correctly on the Hardware Notes. While ice(4) is somewhat unusual in
that its Hardware section contains multiple bulleted lists, so does e.g. ixl(4)
and that does generate correctly.

> .Sh HARDWARE
> The
> .Nm
> driver supports the Intel Ethernet 800 series.
> Some adapters in this series with SFP28/QSFP28 cages
> have firmware that requires that Intel qualified modules are used; these
> qualified modules are listed below.
> This qualification check cannot be disabled by the driver.
> .Pp
> The
> .Nm
> driver supports 100Gb Ethernet adapters with these QSFP28 modules:
> .Pp
> .Bl -bullet -compact
> .It
> Intel\(rg 100G QSFP28 100GBASE-SR4   E100GQSFPSR28SRX
> .It
> Intel\(rg 100G QSFP28 100GBASE-SR4   SPTMBP1PMCDF
> ...


If I was going to stake a guess, is the tooling cutting off when it hits the
"\(rg" in the first bullet point? I note that the em(4) and ixl(4) man pages
also have lists of Intel devices in their Hardware sections but without "\(rg",
and they are generating fine in the Hardware Notes. Might be worth pruning all
the "\(rg" from the ice(4) man page and then try regenerating the Hardware
Notes.

As this affects the 15.0R Hardware Notes I guess this is one for @re or @ziaee.

NB Same issue affects 14.2R and 14.3R versions of the Hardware Notes. Maybe at
least the latter would be worth regenerating.

-- 
You are receiving this mail because:
You are the assignee for the bug.