Re: Start of Systemtap Tapset Reference manual

[Randy Dunlap <randy.dunlap@oracle.com>]

William Cohen wrote:
> 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/.

I'd prefer that we move all debug/markers/tracing files to some Doc sub-dir,
like Documentation/debugging/ (or make up some other sub-dir name).

>>
>> 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.

OK, or a dedicated systemtap sub-dir.

>> 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?

I haven't seen/found one, but I'd certainly like to.  Some people have
told me that make pdfdocs/psdocs works on some distros, but I haven't
been successful with those lately.  I verify current kernel-doc and
Documentation/DocBook/*.tmpl files by using 'make htmldocs' or
'make mandocs'.  The pdfdocs/psdocs problems are toolchain issues
AFAIK.  They need to be fixed, but I'm not the right person to do
that.  Or maybe I'll just remove those make targets...

IIRC, Alan Cox did tell me one time how to get around that hash
size problem, but I don't have that email now.
I have reduced the size of kernel-api.tmpl somewhat and I'm
considering doing more of that, but that's just another form of
workaround, even if it makes some logical sense to split that
<huge> file up.

Are you seeing this hash table size problem with an unmodified
kernel-api.tmpl or only after you add systemtap entries to it?
I'd say that systemtap info should be in a separate file, even
if there is no hash table problem.


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