Skip to content

libcasper: fix mandoc lint warnings in services man pages#2195

Open
xiujunma wants to merge 1 commit into
freebsd:mainfrom
xiujunma:fix/libcasper-mandoc-lint
Open

libcasper: fix mandoc lint warnings in services man pages#2195
xiujunma wants to merge 1 commit into
freebsd:mainfrom
xiujunma:fix/libcasper-mandoc-lint

Conversation

@xiujunma
Copy link
Copy Markdown

What

Fix three real mandoc -T lint -W warning warnings in lib/libcasper/services/ man pages.

Changes

  • cap_net.3 — drop trailing comma on the last .Nm before .Nd (mdoc convention).
  • cap_netdb.3 — same: drop trailing comma on the single .Nm before .Nd.
  • cap_pwd.3 — change .Xr cap_endpwent 3 to .Xr endpwent 3. The page documents cap_endpwent, so .Xr cap_endpwent 3 is a self-reference. The surrounding text describes the cap_pwd functions as "respectively equivalent to" a list of libc functions (getpwent, getpwnam, setpwent, …) — the intended trailing entry is therefore endpwent(3). This is the only content change in the PR.

Verification

mandoc -T lint -W warning before:

mandoc: lib/libcasper/services/cap_net/cap_net.3:43:36: WARNING: bad NAME section content: text
mandoc: lib/libcasper/services/cap_net/cap_net.3:46:5: WARNING: unknown library name: Lb libcap_net
mandoc: lib/libcasper/services/cap_netdb/cap_netdb.3:28:24: WARNING: bad NAME section content: text
mandoc: lib/libcasper/services/cap_netdb/cap_netdb.3:31:5: WARNING: unknown library name: Lb libcap_netdb
mandoc: lib/libcasper/services/cap_pwd/cap_pwd.3:43:5: WARNING: unknown library name: Lb libcap_pwd
mandoc: lib/libcasper/services/cap_pwd/cap_pwd.3:93:5: WARNING: cross reference to self: Xr cap_endpwent 3

mandoc -T lint -W warning after:

mandoc: lib/libcasper/services/cap_net/cap_net.3:46:5: WARNING: unknown library name: Lb libcap_net
mandoc: lib/libcasper/services/cap_netdb/cap_netdb.3:31:5: WARNING: unknown library name: Lb libcap_netdb
mandoc: lib/libcasper/services/cap_pwd/cap_pwd.3:43:5: WARNING: unknown library name: Lb libcap_pwd

The three remaining unknown library name: Lb libcap_* warnings are intentionally out of scope. The .Lb libcap_* invocations in the pages are correct mdoc; the warnings come from mandoc's bundled library-name database not knowing these names. Fixing that belongs in mandoc upstream, not in these pages.

Out of scope

  • cap_sysctl.3 has a sections out of conventional order: Sh RETURN VALUES warning. Real defect; saved for a separate, larger PR because the fix requires moving a whole section.
  • The Lb libcap_* warnings noted above.

- cap_net.3: drop trailing comma on last .Nm before .Nd
- cap_netdb.3: drop trailing comma on last .Nm before .Nd
- cap_pwd.3: fix self-xref to cap_endpwent(3); should be endpwent(3)
  (the page documents cap_endpwent, and the surrounding list mirrors
  the libc pwent functions it is equivalent to)

Signed-off-by: Xiujun Ma <xiujun.ma@live.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant