This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Start of Systemtap Tapset Reference manual


Don Domingo wrote:
Hi Will,

Thanks for this. As far as format goes, everything is just perfect; I'll be doing a proofread run soon. The only suggestion I have for everyone working on this guide is that for "FIXME: needs description" placeholders, use the <remark> tags so everybody can see clearly which tapsets still need to be defined. I've edited the ones for module_name:string() and stp_pid:long() to demonstrate this.

///<formalpara id="stp_pid">
///  <title>stp_pid:long()</title>
///  <indexterm><primary>stp_pid</primary></indexterm>
///  <para>
///    <remark>FIXME: need description.</remark>
///  </para>
///</formalpara>

To make <remark> work, I also added the SHOW_REMARKS=1 option in the Makefile. This ensures that remarks are displayed by default.

Cheers,
Don

Thanks for the feedback. Remarks would be a better way of handling that.


I find the xml to be rather verbose. The original comments in the tapsets were much more compact. I am considering having something generate the xml from the stylized comments rather than having all the raw xml in the tapsets.

-Will


William Cohen wrote:
Hi all,

The infrastructure is in place to extract xml from the files in systemtap/tapset for the reference manual. I have taken the documentation from the timestamp functions and placed it in the timestamp.stp file. The xml in the timestamp.stp file is preceded by ///.

The process of generating the document is fairly simple. Go to the systemtap/doc/SystemTap_Tapset_Reference. If there have been changes to the tapset files, the xml can extracted from the tapset files with:

make extract-xml

You will need to have publican installed on the computer to build the pdf or html files. There are instructions on publican at:

http://sourceware.org/systemtap/wiki/PublicanQuikHowto

Once publican is installed make the pdf with:

make pdf-en-US

Or if HTML is desired:

make html-en-US

The resulting output will be in placed in the appropriate directory:

systemtap/doc/SystemTap_Tapset_Reference/tmp/pdf
systemtap/doc/SystemTap_Tapset_Reference/tmp/html

I have attached the current Tapset_Reference.pdf to get feedback on this process and refine it, so I don't have to revise a bunch of entries.

-Will



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]