HACKING

Running Sup from your git checkout
----------------------------------

Invoke it like this:

  ruby -I lib -w bin/sup

You'll have to install all gems mentioned in the Rakefile (look for the line
setting p.extra_deps). If you're on a Debian or Debian-based system (e.g.
Ubuntu), you'll have to make sure you have a complete Ruby installation,
especially libssl-ruby. You will need libruby-devel, gcc, and rake installed
to build certain gems like Xapian. Gem install does not do a good job of
detecting when these things are missing and the build fails.

Rubygems also is particularly aggressive about picking up libraries from
installed gems. If you do have Sup installed as a gem, please examine
backtraces to make sure you're loading files from the repository and NOT from
the installed gem before submitting any bug reports.

Coding standards
----------------

- Don't wrap code unless it really benefits from it.
- Do wrap comments at 72 characters.
- Old lisp-style comment differentiations:
   # one for comments on the same line as a line of code
   ## two for comments on their own line, except:
   ### three for comments that demarcate large sections of code (rare)
- Use {} for one-liner blocks and do/end for multi-line blocks.
- I like poetry mode. Don't use parentheses unless you must.
- The one exception to poetry mode is if-statements that have an assignment in
  the condition. To make it clear this is not a comparison, surround the
  condition by parentheses. E.g.:
    if a == b                    if(a = some.computation)
      ...             BUT          ... something with a
    end                          end
- and/or versus ||/&&. In Ruby, "and" and "or" bind very loosely---even
  more loosely than function application. This makes them ideal for
  end-of-line short-circuit control in poetry mode. So, use || and &&
  for ordinary logical comparisons, and "and" and "or" for end-of-line
  flow control. E.g.:
    x = a || b or raise "neither is true"