Overall notes on the svnbook

Eric Hanchrow 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
  choice.

-- 
If you can't change your underwear, can you be sure you have any?




More information about the svnbook-dev mailing list