dtrace discuss - Nov 2006 - Conventions for documenting USDT probes?

So now that I''ve got ARC approval for delivering the Xserver
USDT probes in Solaris, I''m wondering how to deliver documentation
for them.   Are there any conventions or existing examples of man
pages doing this?   (Man pages being the only vehicle I really have
to deliver X docs at this time - we have some README''s in
/usr/X11/share/doc, but I doubt most people have found those.)

I see some of the kernel providers have section 7d man pages,
but they all refer to the DTrace answerbook for probe details,
and I wouldn''t think user-space probes should end up in a
kernel driver manpage section anyway.

How are the other projects delivering USDT probes documenting them?

-- 
	-Alan Coopersmith-           alan.coopersmith at sun.com
	 Sun Microsystems, Inc. - X Window System Engineering

On Wed, 1 Nov 2006, Alan Coopersmith wrote:
> So now that I''ve got ARC approval for delivering the Xserver
> USDT probes in Solaris, I''m wondering how to deliver documentation
> for them.   Are there any conventions or existing examples of man
> pages doing this?   (Man pages being the only vehicle I really have
> to deliver X docs at this time - we have some README''s in
> /usr/X11/share/doc, but I doubt most people have found those.)
>
> I see some of the kernel providers have section 7d man pages,
> but they all refer to the DTrace answerbook for probe details,
> and I wouldn''t think user-space probes should end up in a
> kernel driver manpage section anyway.
>
> How are the other projects delivering USDT probes documenting them?
This is an interesting topic. Does anyone from the DTrace team happen to 
know if CR #6431495 will be added anytime soon?:

http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=6431495

In addition to the typical documentation sources, having the info 
available at the exec() of a dtrace would be handy.

Thanks,
- Ryan
--
UNIX Administrator
http://prefetch.net

Hi Alan,

The kernel providers have man pages only because they have corresponding
loadable kernel modules. The correct way to document new provider (and
subroutines, etc.) is in the Solaris Dynamic Tracing Guide which has been
sadly languishing.

I''m not sure who is going to make this happen, but the ideal solution
would
be to turn the existing documentation into a moderated wiki that had some
ability to export the contents back to the standard answerbook SGML. Barring
some enthusiastic contributor, I''d suggest we start building up
documentation
for this and other USDT providers on a wiki somewhere like genunix.org.

Adam

On Wed, Nov 01, 2006 at 11:26:27AM -0800, Alan Coopersmith
wrote:
> So now that I''ve got ARC approval for delivering the Xserver
> USDT probes in Solaris, I''m wondering how to deliver documentation
> for them.   Are there any conventions or existing examples of man
> pages doing this?   (Man pages being the only vehicle I really have
> to deliver X docs at this time - we have some README''s in
> /usr/X11/share/doc, but I doubt most people have found those.)
> 
> I see some of the kernel providers have section 7d man pages,
> but they all refer to the DTrace answerbook for probe details,
> and I wouldn''t think user-space probes should end up in a
> kernel driver manpage section anyway.
> 
> How are the other projects delivering USDT probes documenting them?
> 
> -- 
> 	-Alan Coopersmith-           alan.coopersmith at sun.com
> 	 Sun Microsystems, Inc. - X Window System Engineering
> _______________________________________________
> dtrace-discuss mailing list
> dtrace-discuss at opensolaris.org
-- 
Adam Leventhal, Solaris Kernel Development       http://blogs.sun.com/ahl

On Wed, Nov 01, 2006 at 02:45:16PM -0500, Matty wrote:
> This is an interesting topic. Does anyone from the DTrace team happen to 
> know if CR #6431495 will be added anytime soon?:
> 
> http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=6431495
> 
> In addition to the typical documentation sources, having the info 
> available at the exec() of a dtrace would be handy.
Hey Ryan,

Unfortunately, that''s going to require a bunch of surgery that is
fairly
low priority. I''d expect to see user-land CTF support before this sort
of
self-documentation.

Adam

-- 
Adam Leventhal, Solaris Kernel Development       http://blogs.sun.com/ahl

Hi,

Some other ideas on this topic...The sources for the Solaris Dynamic Tracing
Guide are available on the download center in DocBook XML via the Docs
Consolidation. So, you can edit those files and send them as a patch and
we''ll have a Sun sponsor copy them into the answerbook. Or we could set
up a Project for future changes to the book, so we can just keep the files in a
repository. Let me know what you think, if there is some way I can help.

http://dlc.sun.com/osol/docs/downloads/

Thanks,
Michelle
OpenSolaris Doc PM
 
 
This message posted from opensolaris.org

Michelle Olson wrote:
> Some other ideas on this topic...The sources for the Solaris Dynamic
> Tracing Guide are available on the download center in DocBook XML via the
> Docs Consolidation. So, you can edit those files and send them as a patch
> and we''ll have a Sun sponsor copy them into the answerbook. Or we
could
> set up a Project for future changes to the book, so we can just keep the
> files in a repository. Let me know what you think, if there is some way I
> can help.
> 
> http://dlc.sun.com/osol/docs/downloads/
I''ve found DocBook to be the way to go for any sort of official 
documentation.  I''ve got a lot of experience managing the FreeBSD 
documentation set in this way.

I''d suggest not having a competing wiki, since it just splits the
effort.

What would be great would be an annotation mechanism for the documents, so 
that it''s easy for people to contribute fixes or updates quickly,
without
having to go through the rigamarole of learning DocBook, installing a 
processing environment, and so on.  I''m thinking of something a little
like

    http://www.annocpan.org/

but for DocBook.  I''ve no idea if such a thing exists or not...

As and when my Ultra 40 arrives (http://jc.ngo.org.uk/blog/) I''ll be
making
a point of contributing to the DTrace docs.

N

Hi,

I agree that annotations is a great way to enable contributors to give feedback
on a document without overhead. In the meantime, should we propose a project for
the Solaris Dynamic Tracing Guide, so that those who can do DocBook, might
update the content to current? I have a sponsor for Alan''s Xserver USDT
probes changes, but I also see Adam''s changelog now and I think it
clearly shows we need a project for the document. Thoughts?

Thanks,
Michelle
 
 
This message posted from opensolaris.org