Page MenuHomeFreeBSD

stats(7): Add a man-page with list of stat utilities.
ClosedPublic

Authored by debdrup on Apr 14 2020, 1:49 PM.

Details

Summary

Add a man-page that contains all of the stat utilities in the base system.
It can be quite handy instead of having to pipe apropos stat through less.
Also connect it to the build

Test Plan

igor stats.7
mandoc stats.7 | less
mandoc -Thtml ./stats.7

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

There is a generated html file of the first version of the man-page available here.

0mp requested changes to this revision.Apr 14 2020, 2:02 PM
0mp added inline comments.
share/man/man7/stats.7
28 ↗(On Diff #70550)

"syndry" is probably a typo, right?

30 ↗(On Diff #70550)

Please replace FreeBSD with .Fx.

36 ↗(On Diff #70550)

Macros are not expanded in the argument to -width. btsockstat is probably what you want.

37 ↗(On Diff #70550)

We should probably just use Xr or at least Nm here instead of Cm.

38 ↗(On Diff #70550)

Bluetooth should probably be capitalized.

61 ↗(On Diff #70550)

Inconsistent use of a period at the end of the description.

This revision now requires changes to proceed.Apr 14 2020, 2:02 PM
share/man/man7/stats.7
81 ↗(On Diff #70550)

Missing commas.

Address typo, .Fx, macro usage, s/Cm/Xr/g, capitalization, inconsistent period, and wordsmithed a bit.

I believe I've addressed the issues.

I'm going to go ahead and ask around for whether I missed any stat commands that haven't got a man-page.
If there are any, they will subsequently need to get one, of course. ;)

Not sure if ministat belongs on the list. It is more for doing statistical analysis, it doesn't actually give you any stats/status about your system

brueffer added inline comments.
share/man/man7/stats.7
30 ↗(On Diff #70556)

The
.Fx
userland

83 ↗(On Diff #70556)

Stray comma

86 ↗(On Diff #70556)

manual page first appeared in

Not sure if ministat belongs on the list. It is more for doing statistical analysis, it doesn't actually give you any stats/status about your system

That's a good point - I'll remove it, and fix another thing pointed out by RhodiumToad on irc.

Remove ministat, add stat, remove erroneous comma, wordsmithed the history section, and addressed issue to clarify that FreeBSD base contains more than just man-pages.

debdrup marked 3 inline comments as done.EditedApr 14 2020, 3:56 PM

Glad to have so many reviews :)

So, here's a question since vkarlsen on irc pointed out that hoststat and purgestat are also in base, but RhodiumToad pointed out that they're specifically for sendmail. Should they be added? I'm not familiar enough with them to write a man-page for them.

Replace Xr with Nm as it, at least in less, bolds the commands making it easier to read.

share/man/man7/stats.7
30 ↗(On Diff #70560)

.Fx should be on a new line like so:

The
.Fx
userland

Fix .Fx macro to be on its own line

I must've missed .Fx on a separate line the first time around.

Thank you for catching it again :)

Replace Xr with Nm as it, at least in less, bolds the commands making it easier to read.

In that case I'd at least add all the Xr to see also.

We can do cross-references to stats(7) from other manpages in subsequent commits.

Cross-reference man-pages listed in this document

I don't really mind cross-referencing all other man-pages now, should I go ahead and do it?

Bumping this, in the hopes it doesn't get lost.

Add licese, taken from commiters guide and bump .Dd

debdrup retitled this revision from Add a man-page with list of stat utilities. to stats(7): Add a man-page with list of stat utilities..May 12 2020, 9:32 PM

Comment about the BUGS section.

share/man/man7/stats.7
122 ↗(On Diff #71678)

I don't think we should make any promises of features arriving in future releases in the BUGS section. We would have to do a follow-up commit to clean these up once these features have (or have not) landed.
Also, man-page should be "manual page" just like above (if you want to keep this section in).

Remove BUGS section

I'm happy to not have bugs, even if it's an easy way to accomplish it. ;)

Thank you, Daniel. I think it is ready to commit now and will take care of it!

Thank you very much :)

You're welcome to do s/man-page/manual\ page/ for the title. :)

This revision was not accepted when it landed; it landed in state Needs Review.May 14 2020, 9:19 AM
This revision was automatically updated to reflect the committed changes.