The dtrace(1) manpage is missing a lot of information that is only available in the users guide. I want to pull in that information to make it available to the user right away. I'm planning to add more information on scripting later but I think that this is a good place to start. Currently this is supposed to be work in progress, so feedback appreciated.
Details
Details
- Reviewers
gnn 0mp markj - Group Reviewers
manpages - Commits
- rS337926: Add partial documentation for dtrace(1)'s -x configuration options.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Comment Actions
Can you run "mandoc -Tlint" and textproc/igor on your changes and see what the output is? You get a lot of helpful tips on errors and how to fix them.
| cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | ||
|---|---|---|
| 534 ↗ | (On Diff #46540) | There needs to be a line break after a sentence stop in man pages. |
| 538 ↗ | (On Diff #46540) | Another line break here after the sentence stop. |
| 540 ↗ | (On Diff #46540) | Here, too. |
| 546 ↗ | (On Diff #46540) | Line break after the sentence stop here. |
| 552 ↗ | (On Diff #46540) | See above. |
| 556 ↗ | (On Diff #46540) | Another line break here. |
| 568 ↗ | (On Diff #46540) | Line break is needed here after the sentence stop. |
| cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | ||
|---|---|---|
| 530 ↗ | (On Diff #46543) | We should probably look into the available units (m, k, g, etc.) |
Comment Actions
I have extracted the size options from the truncate(1) manpage since this is pretty much the same thing. I should probably also document the bufpolicy option.
Comment Actions
I guess that we may want to deduplicate the .Ar size argument may be suffixed with one of ... paragraph. I am not sure how though.
Otherwise looks fine to me. 👍
Comment Actions
I have moved the size portion up. Apparently this also applies to strsize which I wasn't aware of.
Comment Actions
Drew some formatting ideas from the zfs(8) manpage in an attempt to be consistent with the rest of the world.
| cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | ||
|---|---|---|
| 527 ↗ | (On Diff #46557) | I'd find it a bit clearer to write "A size argument may be ..." instead. Ditto below. |
| 570 ↗ | (On Diff #46557) | I'd suggest writing "per-CPU principal buffer." |
| 580 ↗ | (On Diff #46557) | "on which" |
| 583 ↗ | (On Diff #46557) | No, the -c flag means something else. |
| 585 ↗ | (On Diff #46557) | Missing a period. |
| 587 ↗ | (On Diff #46557) | "Allow," for consistency with other descriptions. |
| 594 ↗ | (On Diff #46557) | "Turn on," again for consistency. |
| 633 ↗ | (On Diff #46557) | This is quite terse. Maybe, "Maximum number of user stack frames to unwind when executing the ustack() action." or something like that? |
| cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | ||
|---|---|---|
| 527 ↗ | (On Diff #46557) | This was more or less copied from the trunacate(1) man page. Yep, this makes a lot more sense. |
| 583 ↗ | (On Diff #46557) | You are absolutely right, I blindly copied this from the dtrace guide without thinking about it, apparently that's also wrong there. |
| 633 ↗ | (On Diff #46557) | Good idea, I also extended the documentation for the stackframes tunable in the process and calling refering to the stack frames "userspace stack frames" and "kernelspace stack frames" |
Comment Actions
This looks good to me, thanks. I would encourage you to flesh some of these out a little more: some of them (e.g., "speculations") are rather terse, and in some cases (e.g., "switchrate") it would be nice to state the default value. I am ok with doing that in follow-up commits though.
| cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | ||
|---|---|---|
| 629 ↗ | (On Diff #46637) | I did not do an exhaustive check, but at least one option is missing: "temporal". (It originated in illumos, so it might not be in whatever dtrace guide oracle maintains.) For that I would write something like, "Sort trace records by timestamp before printing them. Otherwise trace records are fetched from each CPU and printed without sorting. This option is enabled by default." |
Comment Actions
Some options are missing because I'm not that familiar with them. I will certainly try to make the documentation exhaustive at some point ^^. By the way, I have another PR working on the documentation. https://reviews.freebsd.org/D16688 If you find the time, I'd appreciate the feedback :)