This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Language Reference, updated
- From: Martin Hunt <hunt at redhat dot com>
- To: Robb Romans <robb at linux dot vnet dot ibm dot com>
- Cc: SystemTap <systemtap at sources dot redhat dot com>
- Date: Tue, 28 Nov 2006 12:52:10 -0500
- Subject: Re: Language Reference, updated
- Organization: Red Hat Inc.
- References: <200611221532.39260.robb@linux.vnet.ibm.com>
Some comments. I'm copying the list because some of these apply equally
to man pages.
1.4.2 Primes
Example is from man page. Perhaps both should change from
if (isprime (i)) log (sprint(i))
to
if (isprime (i)) printf("%d\n", i)
Reason: Our users are C programmers. log() in C is a math function.
printf is more powerful and more familiar. log() should be deprecated,
but we will probably keep it around forever for compatibility.
1.4.3
Same issue. Change
log ("11th fibonacci number: " . sprint (fibonacci (11)))
to
printf("11th fibonacci number: %d\n", fibonacci (11))
3.2.3
printf statement has a syntax problem. Should read
printf("reading fd=%d\n", fildes)
3.2.4
Again, I think more C-like examples are better. Instead of
function thatfn:string(arg1:long, arg2) {
return sprint(arg1) . arg2
}
Use
function thatfn:string(arg1:long, arg2) {
return sprintf("%d%s",arg1, arg2)
}
3.5 You start off mentioning "guru mode" without an explanation of what
it is or how you use it. Also I don't understand why the phrase "in some
sequence" is used here.
6.0.11 foreach
Don't forget to document "limit" keyword.
7.2 It may be best to explain that
if ([4,"hello"] in foo) {}
is the same as
if (foo[4,"hello"] == 0) {}
And therefore one cannot test for membership of an element with value
0 or ""
8.4.3 instead of
print(@hist_log(v))
should be
print(@hist_log(x))
9.1.1
"stpd prepends the string "ERROR:""
We shouldn't mention "stpd" because the user doesn't really care about
the name of that program and the name is actually now "staprun". Also,
the prepending is done in the kernel. "staprun" just writes the output
to stderr,
9.1.4 SHould mention that normal printf field formatting is available
(%-20, %o, %x, etc). Also mention %p and binary formats here.
9.1.8 There is no such thing as a "warning stream" Output goes to
stderr. Same comment as 9.1.1 re stpd