- User Since
- Aug 11 2018, 8:23 AM (23 w, 3 d)
Thu, Jan 3
It makes sense to me to include command line arguments in the man page. What I'm not clear on is how far you want to go here. Are you going to document the entire language? Just variables? Variables, subroutines, and aggregate functions? Why take this approach instead of converting the docbook source to something that can be read in a terminal? There is, e.g., docbook2mdoc available in ports.
To be clear, I would very much like to see improvements in FreeBSD's dtrace documentation. I'm not convinced that importing text from dtrace.org is a good way to go about that.
What "examples" do you mean here? It's basically just describing the variables. I could certainly rewrite the sentences. It admittedly feels a bit weird to do something like this but if that's what the license requires I can take up on that task.
I have already made such a change by importing documentation from the Handbook into the manpage. I've talked to @bcr asking the same question at the Essen Hackathon and he told me it would be okay. I personally would like to have something like this in the manpage since I use dtrace quite a bit and I'm missing proper documentation that is being shipped with FreeBSD that I can consume on the terminal. The manpage seems to be the obvious place for this since it's where people look first.
Bumping this since it's been laying dormant for quite a while. Does this still need work to get merged? I've had people asking me things at 35c3 that have been documented here.
Aug 23 2018
@bcr Noted. I'll keep that in mind in the future :)
@bcr The date has already been bumped in the last diff (which has already been merged). Both of these patches were written more or less at the same time, do I still need to bump the date, and if so, what date? :)
Aug 16 2018
I have updated the patch regarding one of the comments. The other one should stay as it is since it's more consistent with the rest of the manpage is phrased.
Aug 15 2018
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 :)
Aug 13 2018
Aug 11 2018
Drew some formatting ideas from the zfs(8) manpage in an attempt to be consistent with the rest of the world.
Added time units
I have moved the size portion up. Apparently this also applies to strsize which I wasn't aware of.
Fixed a typo
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.