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.
Tags
None
Referenced Files
Unknown Object (File)
Dec 23 2023, 12:31 AM
Unknown Object (File)
Jul 15 2023, 10:07 PM
Unknown Object (File)
Jul 2 2023, 8:18 AM
Unknown Object (File)
Jun 26 2023, 11:03 PM
Unknown Object (File)
Jun 14 2023, 3:22 PM
Unknown Object (File)
Jun 12 2023, 2:09 AM
Unknown Object (File)
May 29 2023, 9:22 PM
Unknown Object (File)
May 4 2023, 4:30 PM
Subscribers

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 - subversion
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

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.

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.

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

@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.

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.

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.

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.

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?