So an enterprising autist went and wrote an Amazon review of my book, RTF Pocket Guide:
I was really looking forward to this book as I have been fighting the rtf spec for over a year.
First off, this is not a reference like the other Pocket References from O'Reilly. It is a basic intro to rtf (and in all fairness it does say that in the begining of the book).
But even as in intro, it covers very little. For example, nothing about lists (ie bulleted or numbered paragraphs). So it's very very basic.
Second, it's wrong in places. The biggest mistake I saw was that it says you cannot embed jpeg or png files in a rtf file. You can and it's well documented in the Microsoft spec.
In short, if you know nothing about rtf, this is an ok start. But that's about it.
Now, this reviewer is not an idiot. He's a jackass. It's a fine but crucial distinction.
If the reviewer were an idiot, his review would look like "i got this book because my boss said i had to make some invoices and stuff and i looked at this book and tried to do it in visialpascal but it kept saying the slashbacks were wrong and i think the book should have mentioned that and also had an invoiced example so i give it just 2 stars".
Only a jackass, however, would have thought that a wee little Pocket Guide (the book is not, in fact, a Pocket Reference!) would be immensely useful to someone who's been bashing his head against the RTF spec for a year. Moreover, only a jackass would criticize a book for failing to be a reference, without noticing that nothing suggests that it should be.
If an idiot noticed an error (usually imaginary, since that's the way idiots do things), the idiot would just flail about that error. Only a jackass would take that one error and mythically pluralize it into being a sea of errors -- I've emailed this guy, and this "biggest mistake" he saw is the only mistake he could name; and his supposed correction here is more false than what he's correcting; notably, I didn't say you can't embed jpegs or pngs. I said you can't easily embed graphics, but then I have examples of not-quite-easily embedding graphics. Now, it turns out that there is an easier way for jpegs and pngs (but not gifs), although it is not, in fact, well documented, it's extremely cryptically documented, so much that he's apparently the first person I know who knew of this -- and I've been looking for a while!
His parting snort is that "if you know nothing about rtf, this is an ok start. But that's about it". I know that to be nonsense, because the honcho of the RTF support in AbiWord, Hubert Figuière, is quite experienced with RTF, and he told me, unbidden, that he found it very valuable, and is considering rewriting AbiWord's RTF-import code based on his reading my book.
So I emailed the reviewer-jackass. I pointed out the, um, problems with his review, and I said that I would greatly appreciate if he would change his review, particularly the part where he misrepresents what I said. I suggested an alternate wording for that bit. And he went and revised his review -- but instead of removing the obnoxious bits (i.e., all of it), he simply added this sentence to the end: The author has asked me to add the following - which I do agree with: "The biggest mistake I saw is that it missed a simple way to embed jpg's and png's in documents, and instead suggested complicated workarounds."
Now, the fact he could make sense of the RTF spec's graphics-embedding pseudo-BNF counts for something here -- he's no idiot. And he's not quite an idiot savant. Maybe the most apt term would be "jackass savant" -- his general powers of reading and writing seem, er, limited -- but give him a complicated BNF and look out!
However, good did come of this: I challenged the jackass savant to show real code that actually carried out easy image embedding. He showed some old Java code out of which I got nothing; but knowing that it was at least possible, did drive me to again scrutinize the pseudo-BNF for graphics embedding until I did see how to drop in hex-encoded jpegs and pngs (but never gifs) -- and I tested it with MSWord, AbiWord, etc, to make sure it was actually supported. And it was! So, happy day, things just got easier for image embedding.
So I filed an erratum at the ORA web site (which never occurred to the jackass savant, of course) mentioning this easy-embedding feature, and directing the reader to some sample input and output, along with a sample Perl implementation of the embedder. I think I'll put the code in the next RTF::Writer release.