README

   1 Half-arsed divelog software in C.
   2
   3 I'm tired of java programs that don't work etc.
   4
   5 License: GPLv2
   6
   7 You need libxml2-devel, gtk2-devel and GConf2-devel to build this.
   8
   9 You also need to have libdivecomputer installed, which goes something like this:
  10
  11         git clone git://libdivecomputer.git.sourceforge.net/gitroot/libdivecomputer/libdivecomputer
  12         cd libdivecomputer
  13         autoreconf --install
  14         ./configure
  15         make
  16         sudo make install
  17
  18 Usage:
  19
  20         make
  21         ./subsurface dives/*.xml
  22
  23 to see my dives (with no notes or commentary).
  24
  25 Or, if you have a dive computer supported by libdivecomputer (and
  26 connected to /dev/ttyUSB0), you can just do
  27
  28         make
  29         ./subsurface
  30
  31 and select "Import" from the File menu, tell it what dive computer you
  32 have, and hit "OK".
  33
  34 There's a lot of duplicates in the XML files that come as an example,
  35 and subsurface will de-duplicate the ones that are exactly the same
  36 (just because they were imported multiple times).  But at least two of
  37 the dives have duplicates that were edited by Dirk in the Suunto Dive
  38 Manager, so they don't trigger the "exact duplicates" match.
  39
  40 Implementation details:
  41
  42 main.c - program frame
  43 dive.c - creates and maintaines the internal dive list structure
  44 libdivecomputer.c
  45 uemis.c
  46 parse-xml.c
  47 save-xml.c - interface with dive computers and the XML files
  48 profile.c - creates the data for the profile and draws it using cairo
  49
  50 A first UI has been implemented in gtk and an attempt has been made to
  51 separate program logic from UI implementation.
  52
  53 gtk-gui.c - overall layout, main window of the UI
  54 divelist.c  - list of dives subsurface maintains
  55 equipment.c - equipment / tank information for each dive
  56 info.c      - detailed dive info
  57 print.c     - printing
  58
  59 WARNING! I wasn't kidding when I said that I've done this by reading
  60 gtk2 tutorials as I've gone along.  If somebody is more comfortable with
  61 gtk, feel free to send me (signed-off) patches.
  62
  63 Just as an example of the extreme hackiness of the code, I don't even
  64 bother connecting a signal for the "somebody edited the dive info"
  65 cases.  I just save/restore the dive info every single time you switch
  66 dives.  Christ! That's truly lame.
  67
  68 Also, I don't actually integrate directly with libdivecomputer, I just
  69 read the XML files it can spit out.  But I included my own raw dive
  70 profile xml files for anybody who isn't a diver, but decides that they
  71 want to educate me in gtk.
  72
  73 NOTE! Some of the dives are pretty pitiful.  All the last dives are from
  74 my divemaster course, so they are from following open water students
  75 along (many of them the confined*water dives).  There a lot of the
  76 action is at the surface, so some of the "dives" are 4ft deep and 2min
  77 long.
  78
  79 Contributing:
  80
  81 Please either send me signed-off patches or a pull request with
  82 signed-off commits.  If you don't sign off on them, I will not accept
  83 them. This means adding a line that says "Signed-off-by: Name <email>"
  84 at the end of each commit, indicating that you wrote the code and have
  85 the right to pass it on as an open source patch.
  86
  87 See: http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
  88
  89 Also, please write good git commit messages.  A good commit message
  90 looks like this:
  91
  92         header line: explaining the commit in one line
  93
  94         Body of commit message is a few lines of text, explaining things
  95         in more detail, possibly giving some background about the issue
  96         being fixed, etc etc.
  97
  98         The body of the commit message can be several paragrahps, and
  99         please do proper word-wrap and keep columns shorter than about
 100         74 characters or so. That way "git log" will show things
 101         nicely even when it's indented.
 102
 103         Reported-by: whoever-reported-it
 104         Signed-off-by: Your Name <youremail@yourhost.com>
 105
 106 where that header line really should be meaningful, and really should be
 107 just one line.  That header line is what is shown by tools like gitk and
 108 shortlog, and should summarize the change in one readable line of text,
 109 independently of the longer explanation.