|
Description
|
[mws, 12Apr2005]
Dean Stanton helpfully offered the following list of nits and fixes for
the DTrace answerbook:
Questions:
Near bottom of p. 175
Should ". . . the DTrace program is contained with a file whose
name is filename.s" say filename.d instead?
Substantive Comments and Errors:
Bottom of Page 271, wererun.d output doesn't match the program
The program contains
printf("CPU distribution over %d seconds:\n\n",
(timestamp - start) / 1000000000);
but the output includes "of imapd":
CPU distribution of imapd over 10 seconds:
Presentation Issues/Suggestions:
Page 36-38, example PID.
Since the preface says italics will be used as a command-line
placeholder, you should consider using italics for the example
PID (12345) where the user is encouraged to type it.
Page 36 shows it as the output of "echo $$" and then as a
part of the predicate in "rw.d" (and again on pages 37 and
38, in the discussion).
Admittedly, the rw.d program is not exactly a "command-line",
but italics would serve as a reminder to a reader that 12345
will need to be replaced. By page 39, $1 is used instead,
and it doesn't need to be changed by the reader.
The same issue comes up in chapter 19 (page 203), where I
suggest using 12345 for the PID, rather than 494621, and I
still recommend italics (bold italics where the user will
type the PID on the command line).
Page 121's only text paragraph
"This behavior the data to be denormalized . . ." is mangled.
It looks like a whole line of text is missing after "behavior".
Page 178, near __SunOS_5_10
Text doesn't say that the output of uname -r is edited to have
a _ in place of a decimal point, though the example shows that.
You also may prefer to use `back quotes` rather than 'these'.
Typos or Details:
Near top of Page 100
"The examine desclaration is shortened the declaration for
illustrative purposes." is garbled. It should probably say
something like "The examined dclaration is shortened for
illustrative purposes."
Near top (line 4) of Page 107
"one a value" should probably say "a" but not say "one".
Top of p. 114
"per process nam" should say "per process name".
jstack, middle of p. 135
"jstack() is an alias for ustack() that uses the jstackframes
option for the number of stack frames the value specified by
, and for the string space size the value specified by the
jstackstrsize option." is mangled (near "by ,"). I also
suggest not reversing the order of "XXX option for the number
of YYY" in the second half of the sentence. This suggestion
fixes both: jstack() is an alias for ustack() that uses the
jstackframes option's value if _nframes_ is not provided and uses
jstackstrsizevalue if _strsize_ is not provided." [Replace
_word_ with "word" in the proper font.] Consider using italics
for Latin phrase "in situ" near the end of this paragraph.
chill(), top of page 141
". . . use of chill() will induce interrupt latency, scheduling
latency, dispatch latency" wants "and" after last comma.
Bottom of page 156
"awchar_t" needs a space after "a" (in addition to the font
change). Likewise for "adtrace" at the end of the first para.
of p. 166.
Chapter 18's Overview, p. 195
The same probe type seems to be referred as both "content-event"
probes and in the next para. as Contention-event probes:
". . . two kinds of probes: content-event probes and
hold-event probes.
"Contention-event probes correspond to . . ."
Chapter 18's Stability section, bottom of p 199.
This section says "stability mechanism*" with an asterisk that
suggests a footnote was intended, but isn't present.
Page 218, "SPARC Limitations" subsection
The last sentence of this subsection is much more difficult to
understand than the x86 section's: "Actual numbers vary, but
typically fewer cannot be instrumented on the SPARC platform."
The reader will wonder "fewer than what". If possible, get a
number, like "five percent" is used for the x86 version. If
not, perhaps you mean "fewer functions cannot be instrumented
on the SPARC platform than on x86."
Page 221, end of Probes section
"There common reasons for this discrepancy . . ." should start
"The common reasons".
Page 236, wait_ticks_io entry in Table 23-1
"No semantic difference between wait_ticks_io and . . ."
should start with "There is no". CR 6245341 affects the
other end of this sentence.
Page 279, sched:::dequeue clause
The decrement operator should be "--" but is not. The word
processor probably "helped" by replacing two hyphens with an
em dash.
xxxxx@xxxxx.com 2005-04-12 18:14:38 GMT
Here are some more . . .
Questions:
Version discussion on page 397
Should the Major release be of form "x" or "x.0" (explicit zero)
or maybe it should suggest that both are allowed:
"x" or "x.0"
Substantive Comments and Errors:
Table 33-2 (pg 353 and 354)
R_ERR %err
appears twice, once on each page. (I don't know if one should be
some other register or if the duplicate should simply be removed.)
Middle of page 360, "two consecutive underscores (--)"
This is just a typo, but it might confuse readers. Ideally, the
two underscores would have a thin space between them, so the reader
will see two, rather than one long underscore (as appears in the
myserv example).
Presentation Issues/Suggestions:
CR 6254120 suggests (Page 36-38, example PID) italics for process IDs,
since they will be different for the reader if he/she trys it. There's
another one I noticed on page 293, one near the bottom of page 349.
I also suggest italics for "mumble" (in 3 places) in the unnumbered
table near the top of page 381, since it represents any identifier the
user provides there.
Near middle of page 313, "~1.6 seconds"
I'd use the word "about" in place of the geeky, informal tilde.
Suggestions for additional index entries
command-line options, 174 [or "see dtrace options"]
D/and the C preprocessor, 178 [add another page to existing entry]
options, 174 [add another page to existing entry]
self, see thread-local variables [with self in Courier font]
[or self for thread-local variables, 62]
this, see clause-local variables [with this in Courier font]
[or this for clause-local variables, 64]
Typos or Details:
Next to curlwpsinfo on p. 67
Space is needed between "the" and "proc(4)" [in different fonts].
Near bottom of p. 175
Should ". . . program is contained with a file whose name . . ." say
"contained in" or "contained within" rather than "contained with"?
(Same sentence I asked about before, but a different point this time.)
First paragraph of p. 345
There's a period missing after "activity" and before "Rather,".
Near bottom of p. 361
There's a space missing after "fires." and before (the next sentence
starts with) "Your . . .".
Bottom of p. 366
There's an extra newline (after "destructive") in the Table, causing
page 367 which would not otherwise be needed.
Near bottom of p. 377
There's a newline missing after [boldface] cdccd400::dtrace and
before "CPU ID . . . " (output heading).
Evolving entry of table continuted at the top of p. 385
I'd use "non-upward-compatible" (rather than "non-upward compatible").
Standard entry of table on p. 385
There's a space missing after "adopted" and before "(without . . .".
The dtrace/options index entries
Because the indexer thought dtrace, Dtrace, and dtrace in Courier font
were different, the list of options split across pages 404 and
405 is in three groups (looks funny).
xxxxx@xxxxx.com 2005-04-22 23:55:57 GMT
|