Re: Start of Systemtap Tapset Reference manual

[William Cohen <wcohen at redhat dot com>]

Peter Teoh wrote:
> not sure if my suggestion has any relevancy or unanticipated or not, but 
> I will just describe it.
>
> what i am proposing is:   do the minimal work to create the 
> documentation, maximize the consistency with that of Linux Kernel, so 
> that UNIFICATION of systemtap with Linux Kernel source may one be possible.

I haven't thought about the issue of pulling the documentation into the kernel 
at this time. I was just thinking about the short term describing all the probe 
points and functions in systemtap in a manner that will keep up to date with 
changes in the tapsets. Trying to make it so the documentation isn't totally 
separated from the code.

However, with markers/tracepoints there will need to have this type of 
description in the kernel documentation. There are text files in Documentation 
directory: markers.txt and tracepoints.txt. When specific markers and 
tracepoints are put in the kernel those would certainly should end up in Documents/.

>
> How?
> a.   When create the documentation, for example, the current 
> systemtap/doc always assumed that the entire subdirectory can be moved 
> to become Linux Kernel's Documentation's subdirectory, perhaps 
> "systemtap" as the name.
>
> b.   So when a user go to Linux Kernel source and enter "make htmldocs", 
> or "make pdfdocs", a htmlized or pdf-ized document will be created under 
> DocBook.  Ie, there will be ZERO scripting effort from systemtap 
> developer, and all existing infrastructure provided by Linux Kernel 
> source's "script" subdirectory can be reused.

I was able to do a "make htmldocs" on some kernels to take a look at the html on 
Fedora 9 machine (needed to have a number of "xmlto*" packages installed). 
However, unsuccessful with the "make pdfdocs". I got the following error:

! TeX capacity exceeded, sorry [hash size=60000].
\FlowObjectSetup ...x \csname x@\Label \endcsname
                                                  \@madelink \else \bgroup \...
l.342013 {9\p@}}
                0\endSeq{}\endNode{} for success, <\/ \Node%
!  ==> Fatal error occurred, no output PDF file produced!
Transcript written on kernel-api.log.
make[1]: *** [Documentation/DocBook/kernel-api.pdf] Error 9


Looks like I might be running into the internal limits. Are there workaround for 
that?


> On a wider scale, the above can be generalized further.   But I would 
> like some feedback before venturing too far.


-Will