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