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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

debdrup created this revision.Apr 14 2020, 1:49 PM

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
0mp added inline comments.Apr 14 2020, 2:05 PM
share/man/man7/stats.7
81 ↗(On Diff #70550)

Missing commas.

debdrup updated this revision to Diff 70556.Apr 14 2020, 3:36 PM

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

debdrup marked 7 inline comments as done.Apr 14 2020, 3:39 PM

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.

debdrup updated this revision to Diff 70559.Apr 14 2020, 3:54 PM

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.

debdrup updated this revision to Diff 70560.Apr 14 2020, 4:10 PM

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

brueffer added inline comments.Apr 14 2020, 7:58 PM
share/man/man7/stats.7
30 ↗(On Diff #70560)

.Fx should be on a new line like so:

The
.Fx
userland

debdrup updated this revision to Diff 70593.Apr 15 2020, 10:13 AM

Fix .Fx macro to be on its own line

debdrup marked an inline comment as done.Apr 15 2020, 10:14 AM

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

Thank you for catching it again :)

0mp added a comment.Apr 15 2020, 11:53 AM

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.

debdrup updated this revision to Diff 70602.Apr 15 2020, 2:21 PM

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?

gbe added a subscriber: gbe.May 1 2020, 1:23 PM

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

debdrup updated this revision to Diff 71678.May 12 2020, 7:42 AM

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
bcr added a subscriber: bcr.May 13 2020, 6:49 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).

debdrup updated this revision to Diff 71731.May 13 2020, 7:33 PM

Remove BUGS section

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

debdrup marked an inline comment as done.May 13 2020, 7:33 PM
bcr accepted this revision as: manpages, bcr.May 14 2020, 8:38 AM

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

debdrup added a comment.EditedMay 14 2020, 8:53 AM

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.