Update the FreeBSD handbook with information on DTrace based on content from a wiki page FreeBSD
Status: Closed Time to complete: 120 hrs Mentors: PÁLI Gábor János Tags: DTrace, SGML,, documentation, FreeBSD, DocBook

Description of task

The FreeBSD handbook has a chapter on DTrace, which was ported to FreeBSD: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/dtrace.html

However, it does not contain the latest information on DTrace for current releases of FreeBSD. The following wiki pages have detailed information on how to use DTrace:

http://wiki.freebsd.org/DTrace
http://wiki.freebsd.org/DTrace/userland

Your task is to take the information from the wiki page and put the relevant parts (examples, scripts, etc.) into the handbook chapter on DTrace so that more users make use of DTrace's capabilities. The new content of that chapter needs to conform to our documentation code style guidelines as outlined in the Documentation Project Primer for New Committers (see below).

Task requires: 

A FreeBSD system (in a VirtualBox Virtual Machine) installed on your computer. 
Knowledge of the documentation guidelines for the FreeBSD project: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
Check out a copy of the documentation tree from the documentation repository to get the source code for the chapter

Uploaded Work
File name/URL File size Date submitted
mychanges.diff 10.4 KB December 14 2011 04:35 UTC
mychanges2.diff 10.7 KB December 15 2011 21:31 UTC
mychanges3.diff 10.7 KB December 17 2011 06:24 UTC
mychanges4.diff 10.7 KB December 18 2011 03:01 UTC
Comments
Bharath Mohan on December 6 2011 02:41 UTC Link broken?

The link to the FreeBSD handbook is broken and returns a 404 error. Could you please check this?

Wojciech A. Koszek on December 6 2011 08:12 UTC Link fixed

http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/dtrace.html


That's the correct link, sorry.


 


Wojciech 


 


 

PÁLI Gábor János on December 6 2011 08:25 UTC Fixed also in the task

There was a small typo in the links in the task, I have fixed them (hopefully).

Reid Anderson on December 12 2011 21:04 UTC Task Claimed

I would like to work on this task.

PÁLI Gábor János on December 12 2011 21:20 UTC Task Assigned

This task has been assigned to Reid Anderson. You have 120 hours to complete this task, good luck!

Reid Anderson on December 14 2011 04:38 UTC Submission

Here's what I've managed to come up with so far.


I added a new chapter on using DTrace in userland, and added a couple other things to the rest of the chapter.


 


Let me know if there's anything you want changed/added.


 


Thanks, Reid

Reid Anderson on December 14 2011 04:38 UTC Ready for review

The work on this task is ready to be reviewed.

PÁLI Gábor János on December 14 2011 15:57 UTC I am on It

I am working on the review.

PÁLI Gábor János on December 15 2011 01:57 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

PÁLI Gábor János on December 15 2011 02:08 UTC Things to be Fixed Up

Hey there,


Nice work, but there are a few things to be fixed up.  Here is list of them:


- The list of the new providers and features should not be put to the synopsis.  I would rather put them to the beginning of the "Userland DTrace Support" section, with a text something like "Starting from FreeBSD 9.0, support for the following providers were added.".  Similarly, for the features I would add "Additional DTrace features supported on FreeBSD 9.0 or later:"


- dtruss(1) and truss(1) commands should be marked up with the corresponding entities, i.e. &man.dtruss.1; and &man.truss.1;


- "(ports") is missing after PostgreSQL in the feature list. 


- For the pid provider, you may want to add the link to the original documentation. (See the <ulink> tag.)


- Filenames should be marked up with the <filename> tag.  Every filename, including names for the source code files, DTrace scripts, Makefiles, make(1) includes (.mk files) etc.


- C functions should be marked up with the <function> tag, and their name should contain the parentheses at the end as they are part of the name of the given function.  That is, "sleep" should be written as "sleep()".


-  For the USDT provider, you may want to add the link to the original documentation.


- The warning about linking with libelf(3) should be put in a <note> tag.


- Perhaps it would make sense to refer to the elf(3) manual page by adding &man.elf.3;


- The make(1) command should be marked up as &man.make.1;

Reid Anderson on December 15 2011 04:49 UTC Couple Questions

Thanks for the feedback, I just have a couple quick questions:


Should dtruss/truss be marked up as &man.dtruss/truss.1 every time there mentioned, or just the first time?


Also, should filenames within code listings be marked up with <filename>?


Reid

PÁLI Gábor János on December 15 2011 13:34 UTC The Answers

- Yes, dtruss(1), truss(1), and all the referred commands should be always marked up in the same way.


- No, there are no markups within the <programlisting> tag (well, the only exception, when you want to add callouts).


- By the way, I forgot to add that user-issued commands within the <screen> tag should be marked up with <userinput>.


 


 

Reid Anderson on December 15 2011 21:33 UTC Next Revision

I think that I've fixed everything, let me know if there's anything you still want changed.


 


Thanks, Reid

Reid Anderson on December 15 2011 21:34 UTC Ready for review

The work on this task is ready to be reviewed.

PÁLI Gábor János on December 16 2011 13:16 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

PÁLI Gábor János on December 16 2011 13:23 UTC Details

Hi,


It is almost done, but there are a few things left:


- Paragraph within the <note> tag must be stilled marked up with <para>.  Otherwise it will not compile.


- You forgot to replace all occurences of dtruss(1) with &man.dtruss.1; -- please do it, even in the titles.


- There is no libelf(3) manual page but elf(3), hence the correct entity for libelf is &man.elf.3;  You may want to put it as "...link your program with the elf(3) library."


- bsd.trace.mk is not marked up with <filename>.


- The &nbsp; ("non-breakeable space") is only need if there is a version number after &os; ("FreeBSD"), i.e. "&os;&nbsp;9.0".


 

Reid Anderson on December 17 2011 06:24 UTC Ready for review

The work on this task is ready to be reviewed.

PÁLI Gábor János on December 17 2011 09:54 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

PÁLI Gábor János on December 17 2011 09:59 UTC It is almost done...

...but there are a few missing things:


- When dtruss(1) is marked up as &man.dtruss.1; you cannot put it in <literal> tags.  (Do you check your SGML sources before submission?)


-  It seems the program listings for "provider.d" and "db.d" accidentally contain the invocation of the cat(1) command in their first lines, e.g. "% cat provider.d".  I suppose they are not part of the original files.


 

PÁLI Gábor János on December 17 2011 20:51 UTC Deadline extended

The deadline of the task has been extended with 0 days and 12 hours.

Reid Anderson on December 18 2011 03:01 UTC Ready for review

The work on this task is ready to be reviewed.

PÁLI Gábor János on December 18 2011 04:14 UTC Task Closed

Congratulations, this task has been completed successfully.