                    ***********************
                    *    Logbook Howto    *
                    ***********************

Une documentation en français est disponible dans le fichier "A_LIRE.txt"

If you upgrade from a previous version, please have a look at file
"0CHANGES.txt".

New to version 3 of Logbook: the Subsurface sofware is now required to extract
data from the dive computer. Subsurface has been chosen because:
a) it runs on Linux, MacOSX and Windows;
b) it catches data from nearly any model of existing dive computer;
c) it can import divelogs from many sources (MacDive, Suunto DM3 & DM4,
   JDiveLog and divelogs.de).

Required material:
a) the Subsurface sofware, see http://subsurface-divelog.org,
b) a working distribution of Perl,
c) and a LaTeX distribution (TeXLive, MacTeX, MikTeX, etc.).
Please check that your LaTeX distribution includes the graphic module `pgf'.

Data from your dive computer are read by the Subsurface sofware.
Edit these data under Subsurface to add sites, buddies, notes… then
save the result, say to file "myfile.xml".
Finally, convert the XML file to a LaTeX source file using the sub2latex.pl
script:
  sub2latex.pl <myfile.xml >myfile.tex
and compile this LaTeX file with pdfLaTeX:
  pdflatex myfile.tex
to get your logbook in PDF format.

1) Installation
===============

First unzip the logbook.zip file, this will create a `logbook' directory in
the working directory.

-- The lazy way (for testing):
a) Copy the following four files from the `logbook' directory
   * sub2latex.pl
   * logbook.cls
   * logbook.cfg
   * aliases.tex
   into the working directory.
 b) Check that the `.pl' suffix is associated to the `perl' program, in order
 to be able to type `sub2latex.pl' instead of `perl sub2latex.pl'.
 It should work `out of the box' on Unix-like systems (including MacOSX) and
 also on Windows if perl has been installed by the ActiveState Installer.
 Try the following command:
 sub2latex.pl
 You should get something like this:
 Usage: sub2latex.pl <file.xml >file.tex
 If you get an error message like `sub2latex.pl command not found'
 you can still go ahead by typing:
 perl sub2latex.pl <myfile.xml >myfile.tex

-- The recommended way:
a) copy the Perl script sub2latex.pl to a directory listed in your $PATH
   variable ($HOME/bin, /usr/local/bin, etc.).
b) Unzip file logbook.tds.zip at the root of a local (/usr/local/texmf-local
   or so) or personal ($HOME/texmf, or so) TEXMF directory, see the
   documentation of your LaTeX distribution for the precise location).
   Then update the ls-R database (mktexlsr or similar command).

That's all, but you still have to make sure that the `.pl' suffix is
associated to the `perl' program (see above).

2) Usage and customisation
==========================

Please read the beginning of file `logbook.pdf'.

3) Acknowledgements
===================

Thanks to Matthias Heinrichs and Jan Schubert who provided OSTC.DMP test files
which helped me a lot to start setting up my software.

Thanks to Simon-Bouhet for testing on MacOSX and to Maxime Prot for testing on
Windows.

------------
Daniel Flipo <daniel.flipo@free.fr>
14/07/2015.
