Overall notes on the svnbook
offby1 at blarg.net
Tue Mar 27 13:15:55 CDT 2007
As I'm sure you noticed, I recently posted a bunch of suggestions for
The Book. They were in the form of patches to the book's source.
However, I also have a bunch of suggestions that aren't in the form of
patches, since they apply to the book as a whole. Here they are:
* I changed many <warning>s to <note>s, and vice-versa. I couldn't
find any document that explains when we should use which, so I made
up my own rule: warnings are for suggestions which, if they're not
followed, might lead to data loss (e.g. doing "svn revert" when
you've got un-checked-in changes). notes and tips are just about
saving time or typing. (Frankly I don't know what the difference is
between notes and tips).
* I can't believe I'm saying this, but: the jokes in footnotes are
distracting. I always follow footnotes to see if I'm missing some
interesting bit of information, and it's disappointing -- and a
slight waste of my time -- when it turns out that they're just
jokes. If _all_ the footnotes in this book were jokes, that'd be
OK, since I'd come to realize that, and would stop reading them
(sorry!). But many of the footnotes in this book contain useful
straight information. It's hard for me to make this criticism,
because I _like_ this book's light tone, and the jokes. I just wish
they weren't in the footnotes. Put them in parentheses, maybe? For
some reason they don't bother me when they're part of the main text.
* Sometimes the book says "unversioned properties", but other times it
says "revision properties" or "revprops". Shouldn't we pick just
one term and use it consistently?
* We have many different terms for "end-of-line character sequence",
it'd be nice if we standardized on just one. To see what I mean, run
egrep '(\bline.?end|\bend.?line\b|EOL)' *.xml
* Some itemized lists capitalize each item; some don't. It'd probably
be good to be consistent about this. Examples: the list in
svn.developer.insidewc capitalizes each item; the one just after
svn.developer.layerlib.repos.dia-2 doesn't. (O'Reilly's style sheet
has nothing to say about this, which surprises me.)
* What should we call the words we type on a command line, that have
one or two dashes in front of them? Sometimes we call 'em
"options", and sometimes we call 'em "switches".
* We use the word "basename" in a few places, but never define it.
* Sometimes we show examples that use "xargs"; other times we use
backticks. There doesn't seem to be any rhyme or reason to the
If you can't change your underwear, can you be sure you have any?
More information about the svnbook-dev