Page MenuHomeFreeBSD
Differential D56646

Make links to drivers man in hardware.adoc
ClosedPublic
Actions

Authored by vladlen on Apr 26 2026, 1:35 PM.
Tags
Referenced Files
Unknown Object (File)
Sun, May 31, 12:31 AM
Unknown Object (File)
Sun, May 31, 12:28 AM
Unknown Object (File)
Wed, May 27, 11:08 PM
Unknown Object (File)
Sun, May 24, 12:46 AM
Unknown Object (File)
Tue, May 19, 8:36 AM
Unknown Object (File)
Mon, May 18, 11:23 AM
Unknown Object (File)
Sat, May 16, 3:39 AM
Unknown Object (File)
Tue, May 12, 8:35 PM
View All 20 Files
Subscribers
adrian
mhorne
Tokens
"Like" token, awarded by mhorne.

Details

Reviewers
ziaee
carlavilla
Group Reviewers
releng
Commits
R9:40cd8602b5b1: Make links to drivers man in hardware.adoc
Summary

Summary

Restore and improve driver references in generated hardware.adoc in the releases documentation.

Details

This patch makes the following improvements to the hardware notes generation script:

  1. Driver name ihas been changed to man page link.

Replaces driver names (from .Nm) in the HARDWARE section with links to the corresponding manual pages (e.g. man:uplcom[4] or external link when names differ, f.e for ar40xx).

  1. Fix escaped underscores (\_)

Converts \_ to _ in the generated output.
This eliminates rendering issues and avoids manual fixes (previously ~30 occurrences per release).

  1. Correct HARDWARE section extraction

Fixes truncation caused by sed stopping at # inside entities (e.g. ®).
Now the full section is properly included up to the next header.

Background

Reported in Bugzilla:
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=283060

Users noticed:

Missing links to manual pages in newer releases
Broken rendering due to escaped underscores (noticed by me)
Incomplete HARDWARE sections in hardware.adoc for ice, idc, atp, ultp drivers (all have # symbol in HARDWARE section text)

This patch addresses all three issues in the tooling.

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

vladlen requested review of this revision.Apr 26 2026, 1:35 PM
vladlen created this revision.
vladlen added inline comments.Apr 26 2026, 1:41 PM
website/tools/hardware-notes-processor.rb
29

HARDWARE section is looked up to the next # in the beginning of the line (not # in any location inside of the line)

32

this code block extract Nm from man file (only 1st appearence) and replace driver_name with man:driver_name[4] or link to page, if driver name and man name are different (only ar40xx in 14.4R hardware.adoc)

33

this line changes \_ to _ (mandoc escaped _, but it is useless and render driver names with \_ symbols). I suppose, it was manual work in night before release.

carlavilla accepted this revision.Apr 26 2026, 4:07 PM

Thank you so much for taking care of this :)

This revision is now accepted and ready to land.Apr 26 2026, 4:07 PM
vladlen added a comment.Apr 26 2026, 4:53 PM
In D56646#1297538, @carlavilla wrote:

Thank you so much for taking care of this :)

I will wait other comments some time and commit.
I suspect, that some drivers description have \[ symbols also.

mhorne awarded a token.Apr 27 2026, 1:58 PM
mhorne added a subscriber: mhorne.

VERY GOOD!

website/tools/hardware-notes-processor.rb
47–48

Seems like a fine way to handle discrepancies.

Maybe @ziaee can look at this ar40xx page specifically. Is it right w.r.t. MLINKS and .Nm entries?

Closed by commit R9:40cd8602b5b1: Make links to drivers man in hardware.adoc (authored by vladlen). · Explain WhyApr 28 2026, 5:43 AM
This revision was automatically updated to reflect the committed changes.
vladlen added a commit: R9:40cd8602b5b1: Make links to drivers man in hardware.adoc.
vladlen mentioned this in D56681: website: fix wrong use of backslash in hardware.adoc.Apr 28 2026, 6:19 AM
ziaee added a subscriber: adrian.Apr 29 2026, 11:18 PM

Sorry I didn't have time to review this. This is absolutely wonderful, thank you so much for doing this. I wanted this for a long time but couldn't make it myself. Could you make the links also bold to match the drivers without manuals?

website/tools/hardware-notes-processor.rb
33

I had a sed line in my hardware notes generation script.

47–48

Yeah, no, I messed this manual up. The directory in src is ar40xx but the kernconf device is ar40xx_switch. I'm not really sure what the correct fix is, but I'd like to align the two... --@adrian?

mhorne added inline comments.Apr 30 2026, 12:35 PM
website/tools/hardware-notes-processor.rb
47–48

Perhaps just a new MLINK to create ar40xx_swtich.4 would be sufficient. Most driver manuals only have one .Nm.

vladlen added a comment.EditedWed, May 20, 4:35 PM
In D56646#1299250, @ziaee wrote:

Sorry I didn't have time to review this. This is absolutely wonderful, thank you so much for doing this. I wanted this for a long time but couldn't make it myself. Could you make the links also bold to match the drivers without manuals?

@ziaee

Hi Alex,
I am preparing the next fix for this script (replace '\[' to '[' , mandoc generates \[, if driver descrition has [ in the text).

I could also add the feature you are asking for.
Now hardware-notes-processor.rb generates messages to stdout and skips processing.
The current list for 15.1R is:

WARNING: The manual page man4.i386/ep does not exists
WARNING: The manual page man4.i386/ex does not exists
WARNING: The manual page man4.i386/fe does not exists
WARNING: The manual page hme does not exists
WARNING: The manual page pcn does not exists
WARNING: The manual page sf does not exists
WARNING: The manual page sn does not exists
WARNING: The manual page tl does not exists
WARNING: The manual page txp does not exists
WARNING: The manual page man4.i386/vx does not exists
WARNING: The manual page wb does not exists
WARNING: The manual page xe does not exists
WARNING: The manual page man4.i386/ce does not exists
WARNING: The manual page man4.i386/cx does not exists
WARNING: The manual page man4.i386/cp does not exists
WARNING: The manual page man4.i386/ctau does not exists
WARNING: The manual page ufintek does not exists

I have other proposal.
If line
&hwlist.man4.i386/ep;
generates this warning

WARNING: The manual page man4.i386/ep does not exists

then I can put this line again into the hardware.adoc. It can be easily found by '&hwlist' string.

  1. If this driver is not supported by this release, then this line can be manually removed one time.
  2. if driver supported by it does not have HARDWARE section, this line will be updated

next time, when HARDWARE section added before reease date.

  1. If HARDWARE section is not added, this line will be removed day before release.

In this case hardware.adoc will be improved during every run
make generate-hardware-notes
One times to copy from template and every run to add new HARDWARE sections.

What do you think?

carlavilla added a comment.Wed, May 20, 4:54 PM
In D56646#1309125, @vladlen wrote:
In D56646#1299250, @ziaee wrote:

Sorry I didn't have time to review this. This is absolutely wonderful, thank you so much for doing this. I wanted this for a long time but couldn't make it myself. Could you make the links also bold to match the drivers without manuals?

@ziaee

Hi Alex,
I am preparing the next fix for this script (replace '\[' to '[' , mandoc generates \[, if driver descrition has [ in the text).

I could also add the feature you are asking for.
Now hardware-notes-processor.rb generates messages to stdout and skips processing.
The current list for 15.1R is:

WARNING: The manual page man4.i386/ep does not exists
WARNING: The manual page man4.i386/ex does not exists
WARNING: The manual page man4.i386/fe does not exists
WARNING: The manual page hme does not exists
WARNING: The manual page pcn does not exists
WARNING: The manual page sf does not exists
WARNING: The manual page sn does not exists
WARNING: The manual page tl does not exists
WARNING: The manual page txp does not exists
WARNING: The manual page man4.i386/vx does not exists
WARNING: The manual page wb does not exists
WARNING: The manual page xe does not exists
WARNING: The manual page man4.i386/ce does not exists
WARNING: The manual page man4.i386/cx does not exists
WARNING: The manual page man4.i386/cp does not exists
WARNING: The manual page man4.i386/ctau does not exists
WARNING: The manual page ufintek does not exists

I have other proposal.
If line
&hwlist.man4.i386/ep;
generates this warning

WARNING: The manual page man4.i386/ep does not exists

then I can put this line again into the hardware.adoc. It can be easily found by '&hwlist' string.

  1. If this driver is not supported by this release, then this line can be manually removed one time.
  2. if driver supported by it does not have HARDWARE section, this line will be updated

next time, when HARDWARE section added before reease date.

  1. If HARDWARE section is not added, this line will be removed day before release.

In this case hardware.adoc will be improved during every run
make generate-hardware-notes
One times to copy from template and every run to add new HARDWARE sections.

What do you think?

I like that idea

vladlen added a comment.Wed, May 20, 5:57 PM

What do you think?

I like that idea

I added the review https://reviews.freebsd.org/D57133

Revision Contents
Changeset List

PathSize
website/
tools/
29 lines

Diff 176694

View Options

website/tools/hardware-notes-processor.rb

Loading...