Start of Systemtap Tapset Reference manual

[William Cohen]

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
>