                    ***********************
                    *    MODE D’EMPLOI    *
                    ***********************

Those who do not read French should have a look at file "README.txt".

Lors d'une mise à jour à partir d'une version précédente, consultez le
fichier "0CHANGES.txt" pour la liste des changements intervenus.

La version 3 a été complètement remaniée : l'extraction des données de
l'ordinateur de plongée se fait désormais sous Subsurface qui présente les
avantages suivants :
1) il tourne aussi bien sous Linux, MacOSX que Windows ;
2) il prend en compte la plupart des ordinateurs de plongée du marché ;
3) il permet d'importer des journaux de plongée générés par d’autres sources
telles que MacDive, Suunto DM3 & DM4, JDiveLog et même divelogs.de.

Pré-requis : il est nécessaire de disposer sur le PC d’accueil tournant
sous Linux, MacOSX ou Windows
a) de Subsurface, voir http://subsurface-divelog.org,
b) de Perl (normalement installé de base sur Linux et MacOSX),
c) d’une distribution LaTeX (TeXLive, MacTeX, MikTeX, etc.).
Il convient de s’assurer que le module graphique « pgf » fait partie
de la distribution LaTeX utilisée.

Les données de l'ordinateur de plongée sont lues par Subsurface.
Elles peuvent être éditées et complétées sous Subsurface, le résultat est
ensuite sauvegardé sous forme d'un fichier XML par Subsurface.
Ce fichier peut être converti en fichier source LaTeX par le script Perl
sub2latex.pl, puis éventuellement édité et enfin compilé sous pdfLaTeX pour
obtenir un carnet de plongée en PDF.

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

-- récupérer le fichier logbook.zip et le dézipper ce qui crée dans le
répertoire courant un sous-répertoire « logbook » contenant tout le matériel
nécessaire.

-- Installation simplifiée (pour test) :
a) recopier dans le répertoire de
   travail les quatre fichiers
   * sub2latex.pl
   * logbook.cls
   * logbook.cfg
   * aliases.tex

b) s'assurer que le suffixe « .pl » est associé à la commande « perl »
 de façon à pouvoir lancer directement la commande « sub2latex.pl » au
 lieu de devoir taper « perl sub2latex.pl »).
 Ce doit être le cas sur les systèmes Unix (Linux, MacOSX) et aussi sous Windows
 à condition que perl ait été installé avec l'installeur ActiveState…
 Tester la commande suivante :
 sub2latex.pl
 Vous devriez obtenir ceci :
 Usage: sub2latex.pl <file.xml >file.tex
 et non un message d'erreur du genre « sub2latex.pl command not found ».
 Sinon, essayer ceci :
 perl sub2latex.pl <monfichier.xml >monfichier.tex

-- Installation recommandée :
a) Recopier le script Perl sub2latex.pl dans un répertoire listé dans la
   variable $PATH ($HOME/bin, /usr/local/bin, etc.).
b) Dézipper le fichier logbook.tds.zip
   * soit à la racine de l’arborescence TEXMF personnelle ($HOME/texmf pour
   TeXLive, $HOME/Library/texmf pour MacTeX),
   * soit, si on veut que logbook soit accessible à tous les utilisateurs de
   la machine, à la racine de l’arborescence TEXMF locale
   (/usr/local/texlive/texmf-local pour TeXLive) ; il faut alors ensuite
   mettre à jour la base de données ls-R (commande mktexlsr ou similaire
   selon la distribution TeX utilisée).
   Ainsi les trois fichiers logbook.cls, logbook.cfg et aliases.tex ainsi que
   les scripts perl seront vus quelque soit le répertoire de travail.

N.B. : l'exécution de la commande sub2latex.pl nécessite toujours que le
suffixe « .pl » soit associé à la commande « perl » (voir ci-dessus).

2) Utilisation
==============

a) Extraire les données de plongée avec le logiciel Subsurface, éditer ce
fichier pour ajouter les informations manquantes (site de plongée, binôme,
etc.) et sauvegarder le résultat au format Subsurface (fichier XML).

b) Convertir le fichier XML obtenu en fichier LaTeX avec la commande

  sub2latex.pl <monfichier.xml >monfichier.tex

où « monfichier.xml » est le nom du fichier créé par Subsurface et
« monfichier.tex » est le nom du fichier source LaTeX à créer.
les "<" et ">" sont *INDISPENSABLES* !

À la première utilisation réussie, la totalité du fichier XML est
convertie en LaTeX. Chaque lancement ultérieur du script sub2udcf.pl
stocke la date de la dernière plongée effectuée dans le fichier
~/.divetools/.lastdive-sub, ainsi seules les nouvelles plongées sont
converties lors des utilisations successives. Il suffit de supprimer le
fichier ~/.divetools/.lastdive-sub pour obtenir à tout moment la conversion
de l'intégralité du fichier XML créé par Subsurface.

c) Ensuite il reste à éditer « monfichier.tex » pour lui ajouter les notes et
informations personnelles et à le compiler pour obtenir le fichier PDF final :

  pdflatex monfichier.tex

Édition du fichier .tex : si les données fournies par l'ordinateur de plongée
ont été complétées sous Subsurface (numéros des plongées, nom des sites, des
binômes, volume des bouteilles, pression de départ et pression finale, notes,
etc.) aucune édition du fichier .tex n'est nécessaire, ces informations étant
transcrites par le script sub2latex.pl. Sinon, les commandes suivantes
facilitent la saisie de ces informations directement dans le fichier .tex :

-- La commande \DiveNr{} donne le numéro de plongée ; il suffit de la
renseigner une fois dans la première plongée du fichier, les numéros seront
décrémentés automatiquement (ou incrémentés si l’option « sorted » est passée
à la classe logbook) pour les plongées suivantes.

-- Les commandes \Area{} et \Buddy{} doivent être renseignées dans la première
plongée du fichier et ensuite seulement s’il y a changement de zone ou de
binôme.

-- La commande \Spot{} (site de plongée) doit être renseignée à chaque plongée.

-- Une valeur par défaut est prévue dans le fichier « logbook.cfg » pour le
volume des bouteilles, il convient de l’ajuster selon le type de bouteilles le
plus utilisé. Ensuite, à chaque fois qu’on laissera vide l’argument d’une
commande \TankVolGas1{}, \TankVolGas2{}, etc. la valeur par défaut sera
utilisée. Si pour une plongée donnée, on donne un volume, par exemple
\TankVolGas2{6} (il s’agit de litres), cette valeur sera mémorisée pour les
plongées suivantes (elle remplace la valeur par défaut) tant qu’une nouvelle
valeur ne sera pas donnée. Ceci me semble pratique lorsqu’on plonge avec la
même configuration pendant plusieurs plongées consécutives ou successives.
Idem pour \TankVolDiluent{} et \TankVolOxygen{} en mode CCR.

-- Les commandes \PstartGas<n>{}, \PendGas<n>{} doivent être renseignées si on
souhaite voir affichées les consommations pour le gaz correspondant :
consommation totale en litres et SAC (consommation rapportée à la surface, en
litres par minute). Elle peuvent l’être automatiquement si l’ordinateur
intègre la gestion d’air. Idem pour \DiluentPStart{}, \DiluentPEnd{},
\OxygenPStart{} et \OxygenPEnd{} en mode CCR.

-- Enfin, deux environnements sont prévus pour les commentaires : l’un
(« notes ») est toujours affiché dans le fichier PDF de sortie, l’autre
(« private ») ne l’est que si on passe l’option « public » à la classe
logbook, ce qui laisse un espace pour les commentaires trop personnels
ou trop subjectifs...

3) Personnalisation
===================

-- Le fichier logbook.cfg permet de modifier la présentation des plongées.

-- Le préambule des fichiers .tex créés est entièrement configurable : il
suffit de créer un fichier « logbook.pre » contenant le préambule désiré
(complet, \begin{document} exclu), il sera automatiquement pris en compte
par le script sub2latex.pl à la place du préambule standard.

Bien sûr, on pourrait aussi modifier directement le script sub2latex.pl,
mais il faudrait ensuite refaire le travail à chaque mise à jour...

-- Un postambule quelconque peut être ajouté après le \end{document},
(par exemple variables locales pour Emacs), il suffit de créer un fichier
« logbook.post » contenant les lignes souhaitées.

4) Limitations
==============

-- Le système de mesure « Imperial » n’est pas pris en compte, seuls le sont
le système international (SI) et le système métrique, l’affichage final est
en unités métriques (mètres, bars, litres, minutes, °Celsius).

-- Il n’y a pas de correction de fuseau horaire prévue pour l’instant.
Les heures lues dans l’ordinateur de plongée sont reportées telles quelles.

7) Remerciements
================

Merci à Matthias Heinrichs et à Jan Schubert pour m'avoir fourni les
fichiers de test OSTC.DMP qui m'ont permis de débuter le développement.

Merci à Benoît Simon-Bouhet pour ses tests sous MacOSX,
à Maxime Prot pour ses tests sous Windows.

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