Proposal for Tapset Reference Documentation

[William Cohen]

One of the things needed for systemtap tapsets is better reference
documentation. The current documentation for the tapsets is a set of
man pages describing probe points and functions availabe in systemtap
tapsets. The reference manpages are not tied to actual tapset code and
it is easy for them to get out of sync as changes and additions are
made to the tapsets. Much of the documentation for Fedora and Red Hat
Enterprise Linux is being generated using docbook/XML. The Systemtap
Beginners Guide is currently being writtend as XML that can be used to
generated PDF and HTML using the Publican package.

Looking through web for ideas on how to co-locate the xml
documentation with code found that C# uses "///" at beginning of line
to mark the rest of the line as XML documentation:

http://www.codeproject.com/KB/macros/MCXDoc.aspx
http://www.winnershtriangle.com/w/Articles.XMLCommentsInCSharp.asp

It would be easy to extract the from a tapset source with a one line
perl script:

while(<STDIN>) { print if s/\s*\/\/\///; }

The output would be directed to appropriate directory in documentation
directory, systemtap/doc/reference/en-US. A script like
testsuite/systemtap.examples/examples-index-gen.pl could extract the
xml from each of the tapset stp files and write a matching xml file.

-Will