Page MenuHomeFreeBSD

Add a new Scripting section to the dtrace(1) man page.
Needs ReviewPublic

Authored by raichoo_googlemail.com on Aug 11 2018, 9:08 PM.

Details

Reviewers
gnn
bcr
Group Reviewers
manpages
Summary

I'm working on adding a new scripting section to the man page, I'm planning to include some stuff from the dtrace tracing guide (http://dtrace.org/guide). Basically I want people to be able to have everything they need for scripting DTrace in the base install without the need to check the internet for documentation. I'm starting this off with documenting most of the variables that are available in scripts. Functions and other things will follow as a separate pull request.

Diff Detail

Repository
rS FreeBSD src repository
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

raichoo_googlemail.com set the repository for this revision to rS FreeBSD src repository.
markj added a subscriber: markj.Aug 15 2018, 8:51 PM
bcr added a subscriber: bcr.Aug 16 2018, 12:54 PM

Here are two suggested fixes.

cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
654

s/probe represented/probe are represented/

683

s/identifiers/identifies/

raichoo_googlemail.com marked an inline comment as done.Aug 16 2018, 1:05 PM
raichoo_googlemail.com updated this revision to Diff 46768.

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.

bcr accepted this revision.Aug 19 2018, 7:00 PM

Bump the .Dd at the top of the file, then it's fine.
@markj , can you commit it? Thanks!

In D16688#357541, @bcr wrote:

Bump the .Dd at the top of the file, then it's fine.
@markj , can you commit it? Thanks!

Will do, but I haven't gone through it in detail yet. I'll get to it in the next couple of days.

pi retitled this revision from Add a new Scipting section to the dtrace(1) man page. to Add a new Scripting section to the dtrace(1) man page..Aug 20 2018, 4:04 AM

@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? :)

bcr added a comment.Aug 23 2018, 6:57 PM

@raichoo_googlemail.com That's fine then. A bump is typically necessary for any kind of content changes. But if those changes belong to the same commit or were written around the same time, it's fine to bump it just once. In this case, markj will take care of it when he commits it.

@bcr Noted. I'll keep that in mind in the future :)

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.

markj added a comment.Jan 3 2019, 5:09 PM

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.

My apologies, this got lost in my queue as we were working on 12.0.

Taking a closer look, this appears to be a direct copy of the material on dtrace.org, which is covered by a different license than the CDDL used for the dtrace.1 man page: http://dtrace.org/guide/license.html#license

Are you sure that the licenses are compatible? More generally, what's the point of duplicating content from dtrace.org in the man page? We should certainly at least include a link in the dtrace(1) man page, and possibly import the handbook itself (https://github.com/illumos/illumos-docbooks/tree/master/raw/dtrace) into the base system or the docs repo, but I don't like the duplication introduced by this diff.

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.

bcr added a comment.Jan 3 2019, 6:28 PM

Can we rewrite these examples somewhat so that they are not identical but provide the same general concepts/ideas?

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.

markj added a comment.Jan 3 2019, 7:08 PM

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.

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 haven't read the full license. I'm not claiming that it prohibits what you're doing, but it needs to be verified.

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.

Mh, something like man dtrace-handbook? I could get behind that.

I haven't read the full license. I'm not claiming that it prohibits what you're doing, but it needs to be verified.

Absolutely.

bcr added a comment.Jan 3 2019, 8:50 PM

Right, examples should have been "variables". I agree with Mark on this one. We need to be careful with licenses even if it is just for docs.
So if I would ask you to describe the types of DTrace variables (for example), could you come up with a description that's complete enough for the man page without being too close to the original?
Otherwise, Mark's suggestion for converting the Guide would work for you. Question is, whether this is just your requirement or is it common enough that it warrants a general inclusion in the man page?