2 DiverManual
izzy edited this page 2 years ago

Diver Manual

Opposite to the AdminManual, the following pages are describing issues relevant for the diver representing his/her logbook with phpDiveLog. The following issues are covered:

Installation

While the installation of phpDiveLog itself is the duty of the admin, the diver also has to perform some installation tasks: We need to export the data from ADL to a format usable by phpDiveLog, and thus we have to setup the conduit.

Install the Conduit

The conduit itself is not shipped with phpDiveLog, so you have to download it from the ADL website. Further this article assumes you already did so and also installed the conduit. So this is where we start here: The conduit is installed, and you have the phpDiveLog sources unpacked on your disk. All you need from the latter is the content of the install/adl/ directory:

  • copy the contents of the install/adl/template/ dir to ADLs template/ dir
  • copy the contents of the install/adl/ dir to ADLs directory

Configuration

Conduit Configuration

Consult the documentation of ADL concerning the basic configuration of the divelog.ini file. For phpDiveLog we only assume you changed the following parameters here:

  • TablePDBFile points to your AquaPalm-TableDB.pdb file
  • DivePDBFile points to your AquaPalm-DiveDB.pdb file

For the other parameters, please refer to the conduits documentation.

Wrapper Configuration

To convert (and optionally transfer) the data from ADL, phpDiveLog provides the divelog_conduit.sh file – which is configured with the file named config residing in the same directory. These files are intended to be used with the Bash shell available on Linux/Unix machines, and also with Cygwin on Windows hosts. Since phpDiveLog exists, there has never been a request for a Windows script – so if you need it, you may want to open a feature request ticket (and be willing to test the result, since I don't have Windows running and thus cannot test).

As usual with Shell scripts, the configuration parameters follow the syntax "name=value", and please take care to not introduce any spaces directly next to the equal sign:

Conduit Settings

Parameter Shipped Default Explanation
PALMLOCALE de_DE@euro Don't mess this up with your PCs locale settings – we don't touch them. But if they differ from your Palms locale (which will certainly be the case if you run a current distribution with UTF-8 locale), special characters may get messed up or, in the worst case, the Java Conduit hangs if this is not set correctly. In most cases, the setting of de_DE@euro (Latin-1 plus Euro sign) will be the correct choice. For non-Western charsets on your Palm, you may have to experiment a bit until all special chars are drawn correctly. This setting is required by the conduit itself.
RECODEFROM lat1 PalmOS devices use different character sets. If you encounter display problems on your divelog web pages, such as messed-up characters (German Umlauts and the like), you may want to play with this option. If not set to an empty string, the script will use the recode command to convert the character set to UTF8 - you just need to figure out which character set your PalmOS device is using (see also install/charsets.txt). Usually, a good starting point is lat1 for newer devices (PalmOS 5 and up), or cp1252 for older ones (PalmOS 4 and lower).
LOGDIR log If you did not change this in the divelog.ini, you can leave this as-is - otherwise place the same value here as you did there for the LogBookPath.
UNITS bothunits which kind of units you prefer – can be set either to "metric", "imperial" or "bothunits"
PROFUPD -noprofileupdate Creation of the dive profile PNG graphics slows down the conversion process a lot (it takes about 2/3 of the time). Luckily, starting with conduit version 0.99_7 there is a new parameter to skip this step if the PNG already exists: -noprofileupdate. In case you are using an older conduit version, just comment out that line in your config - or better get the latest conduit ;)
DATEFORMAT "%Y-%m-%d %H:%M:%S" just for the "progress display" on the screen to give you an idea how long which step took ;)

Local Transfers

Parameter Shipped Default Explanation
USELOCAL 1 if you want to copy the files to your local webserver, set the value to "1" – otherwise to "0".
PDLBASE "/web/divelog/diver/demo" the divers directory of your local phpDiveLog installation, i.e. where the subdirectories data/ and images/ reside. Will certainly look like <PDL root dir>/diver/<nickname> – see Diver Setup in the admin manual for details.

Remote Transfers

Parameter Shipped Default Explanation
USESCP 0 if you want to copy the files to a remote webserver via scp, set the value to "1"; if you have rsync installed on both the client and the server, you will prefer "2" for a) faster and b) complete sync (including all your additional texts and fotos). For no transfers to any remote server, set this to "0".
SCPBASE "user@machine:/path_to_PDL/diver/demo" the divers directory of the remote phpDiveLog installation, i.e. where the subdirectories data/ and images/ on the remote server reside. Will certainly look like <login>@www.domain.com:/<PDL root dir>/diver/<nickname>, where <PDL root dir> is the base directory of the PDL webtree or, if the "single OS user transfer" is used, the home directory of that OS user – see Diver Setup in the admin manual for details and/or ask the site admin.
RSYNCBASE 1 this defines which source directory should be used with rsync. If you have no local PDL installation on your machine and/or use USELOCAL=0, set this to "2" which advises the script to use the ADL log dir as source. In this case, also make sure that all needed subdirectories (i.e. for the fotos, notes and texts) exist at that place! Otherwise, with a local installation of PDL, you probably don't want to keep all fotos duplicate, so set this to "1" and place all your additional foto and text files where they belong: in your local PDL diver dir – in which case you will need to set USELOCAL=1.

You can use local (USELOCAL=1) and remote (USESCP=1 or USESCP=2) transfers independantly – if you need both, you can enable both at the same time (which would even be required for RSYNCBASE=1).

Site Account Configuration

The site account configuration takes place in two files located directly in your PDL home directory (i.e. diver/your_nickname/):

  • system.conf: contains your preferences concerning site appearance
  • divers.conf: contains personal information about you you want to attach to your online divelog

The system.conf

Optionally, each diver can override some of the systems default settings by putting a file named system.conf in his/her "home directory" ("home directory" refers to the diver/<nick>/ subdirectory of the phpDiveLog installation). The syntax of this file is easy: one parameter per line in the form var=value. Empty lines and lines beginning with a "#" are ignored. Which system options are allowed to be overridden is defined by the site admin, so please ask the admin what you can use - and refer to the admins configuration for the syntax.

One additional parameter in the system.conf is personal. It defines whether the diver wants to display his/her personal data (see diver.conf below) or not. If this parameter is missing (or commented out), noone will be able to browse them via the person.php page, even if a complete diver.conf exists. The same applies if it is set to "0". Set personal = 1 if you want the page to be displayed.

Furthermore, the system.conf contains a few parameters which only can be set on a per-diver-basis: Namely, the "user defined fields" from Aqua DiveLog. There are two fields which you can set manually in its preferences, and they are exported via the conduit. So if you want them displayed along with your dive data, you should set the variables userdef1 resp. userdef2 to the title these fields should have. If then for a dive there are data available for this field(s), they will be shown in the equipment section of the dive.

The divers.conf

This file, if available, must reside in the same directory as the system.conf file (see above). It is intended to provide data for the divers personal page, i.e. name and place of living as well as certifications.

The diver.conf is divided into several blocks - block names are encloses in square brackets. If you do not want to provide data for a specific block at all, you may just completely remove it (or comment it out) at all.

The [person] block, as the name suggests, contains the personal data. Available options in this block are name, firstname, country, state, city and status (where status means your highest certification, e.g. AOWD, DM or Instructor). You can include a photo of yours using the foto option also available in this block. The image used here must be stored in the diver/*/fotos/person/ subdirectory. If you don't specify one, a "dummy" will be used instead. If you want to omit something, just delete or comment out that line. With the buddylist option you define whether these personal data may be included in the buddy list (if enabled by the admin) by setting it to "1" - or not, by either setting it to "0", commenting it out or removing that line completely.

With the [certification] block, there are stronger rules to observe. Data for a certification must include the course (i.e. the certification - makes no sense without ;) and may include the date and place where it was gained. Thus we have three items that belong together, and we may have multiple of this groups. So we group them together by arrays. The consequence is you have to keep the three items together if they belong together, and you must not miss the square brackets at the end of the options name. Plus you have to include either none or all three options - if you don't want to publish e.g. the date, just leave the parameter blank. Otherwise, if you specify it for the next course, the parser will count it to the previous ;) Available options in this block are course[], date[] and place[].

To add more descriptive context, you can make use of other "external sources", such as a text file in your diver "home directory". See Additional Sources for details on this.

The public file

If you want your data to be accessible and findable by visitors - i.e. used in the buddylist and global site index, place an additional file next to the bot configuration files and name it public. It's content is completely ignored (so it may be empty), but its presence will be checked at the corresponding places.

Data Conversion and Transfer

Once you've setup the conduit scripts accordingly, you simply have to change to the directory containing the divelog_conduit.sh script and run it without any parameters – after you got the up-to-date ADL database files from your Palm. Provided your configuration was correct, the script will do all necessary steps:

  • run the conduit to convert the ADL database files to *.csv files
  • adjust the text encoding in those *.csv files if necessary
  • optionally transfer all data (optionally including your images etc., depending on your configuration) to the web server

If your site admin only provided you with FTP access, you may have to do the last step manually. Also, depending on the server account setup, you now may need to invoke the import.php script on the phpDiveLog website to get your data to the web dirs - ask your site admin whether you have to do so or not.

If you re-organized some dive data (especially renumbering the dives and/or sites), you may need to clean the images/ directory (which contains the dive profile images) before you run the conduit script, to make sure they are re-created with the correct names. Of course, in this case you will also have to check your photos and text files and rename them accordingly (see AdditionalInfo for details on those files).

Placing additional Information

You may include additional information like pictures or external (plain text) files into your dive, site, and personal information, which can be done in two different ways:

  • placing files with specific names in the right locations
  • using special macros in your ADL dive/site notes

Dive and Site photos

You can advise phpDiveLog to automatically display fotos connected to your dives and/or divesites. PDL searches two special directories for these images: the diver/<nickname>/fotos/dive/ directory for pictures related to dives, and diver/<nickname>/fotos/site/ for divesite related images. It recognizes the Jpg, Gif and Png image types as valid. Descriptions are to be placed in *.txt files having the same name as the image they describe (see examples in the diver/demo/fotos/ directory).

The naming conventions are taken from the ADL specifications: all dive images have the name diveXXXXX-YYY.*, while the site images are to be named siteXXXX-YYY.txt - where the XXXXX stand for the 5-digit dive/site number (zero-padded from the left, e.g. "00025" for dive/site number 25), and YYY for a 3-digit consecutive number of all images for the related dive/site. With the first phpDiveLog is able to connect the images with the according data records, using the latter you can define the order the images are displayed.

Things to consider:

  • recommended size for these "thumbnails" is 192x144 pixel
  • make the file extensions lower case (i.e. *.jpg|png|gif|txt)
  • when re-numbering your dives, your fotos need to be renumbered accordingly
  • if you want PDL to link the "thumbnail" to the original (larger) image, give the latter the same file name and place it into the "large" subdirectory of the directory the "thumbnail" was placed into

Additional descriptions for your Dives and Sites

The "external notes feature" is mainly intended to save you from editing larger stuff on your PDA - so you store only the core information in ADL, but expatiate upon them here (especially as the fields in the PDA are rather limited in size as well). To create an external "notes" field, simply place a plain text file named diveXXXXX.txt (for dive notes) or siteXXXXX.txt (for site notes) in the notes/ subdirectory of your "diver home directory", replacing the "XXXXX" by the ID of the dive/site filled up with zeros from the left to 5 digits (e.g. a note for dive #57 would be dive00057.txt). This file may contain HTML formatings (e.g. for <B>old or <U>nderlining) as well as all available "tags" (see below). All double-newlines will be replaced by line breaks ("<BR>") to form paragraphs.

Make sure that all text files are using the UTF-8 character set! For Windows, e.g. the standard editor (notepad) can save files in UTF-8 if you select "Save as", and then in the dialog you find some "encodings" box where you can select "UTF-8". With *nix, if your editor does not support this, you can use the recode command for this task (for details, see the man page with man recode).

If you like to create localized versions of your notes, you can do so for all languages that are directly supported by phpDiveLog (see the Setup page). For these, name the files as described above plus add the language code to the end of the filename, so it would be *.txt.de for a German, or *.txt.ru for a Russian text. In these cases you should ensure that the default file (without the language code) also exists, since the localized versions would only be displayed if the visitor has the given language selected on the Setup page. To ensure this, you can make use of symbolic links. If you e.g. have a German and an English description, you could either place the English one as *.txt and the German one as *.txt.de - or name the English one *.txt.en and create an additional symbolic link using the ln -s <name of the English file> <name of the English file without the ".en"> command.

These files will automatically be appended to the corresponding notes fields, if they exist, as if their content would have been entered in the ADL comments fields. Additionally it should be said that you shouldn't use HTML formating to extensive (e.g. by changing background colors etc.) to not mess up the general design of the site.

Personal Information

Additional textual information for the personal page can be created similarly - but here we consider just the diver.txt[.<lang>] file(s) in the divers "home directory", i.e. the directory where the divers system.conf and diver.conf reside.

Image files here must reside in the diver/<nickname>/fotos/person/directory and be named diverYYY.*, where YYY is a consecutive number of their order, left-padded by zeros (e.g. diver002.jpg).

Makros in Textfiles and ADL notes

You may include additional information like pictures or external (plain text) files into your notes by using special tags which are then replaced when phpDiveLog parses your DiveLog information for display. This way you can include images and point to additional information on local and remote sites, or even include other plain text/html files stored on the machine serving your PDL files.

Embedded links are enclosed by the [url] and [/url] tags. Embedded images are enclosed by the [img] and [/img] (left aligned) or [imgr] and [/imgr] (right aligned) tags. External (text/html) files can be included by using the [file] and [/file] tags, nesting of tags (i.e. using the tags in a file included by the [file] tag, and using images as anchors for URLs) is possible. The syntax of the part between the tags is as follows, where square brackets mark optional and angle brackets mandatory parts:

Tag Part between the opening and closing Tag Example
file [rootDir|protocol][path]<filename> [file]/path/to/signature.txt![/file]
url,img,imgr [rootDir|protocol][path]<filename>[|description] [url]http://www.izzysoft.de/|IzzySoft Website[/url]
gps lat;lon[;name]|description [gps]45° 9' 36.0_ N;14° 38' 46.0_ E;Wrack der Pelastis|Koordinaten[/gps]

A special case is the rootDir specification, which has the syntax ~dir[@<buddy>], and ~dir is a single letter, representing …

  • d: fotos/dive
  • s: fotos/site
  • p: fotos/person
  • t: diver/<buddy>/text

The [gps] macro first builds the URL for the configured map service out of the coordinate part and the optional name. Then the entire macro gets replaced by an [url] macro, including the description. So from the divers point of view, this is basically handled as a special form of the [url] macro, including possible nestings.

So giving a more complex example at the end: [url]http://some.divesites.homepage/|[img]~s@demo/site01234-001.jpg|Great Site[/img][/url] should result in the given picture, linked to the given url and with the given text attached.

PDF Export Issues

Since with long descriptions not all of your texts may fit on one PDF page, you can define the "block" which should go here by using HTML comments: <!-- PDF_START --> means to ignore everything before that line for PDF export, and <!-- PDF_END --> means to ignore everything after it. As for now, you may use each of this comments only once per record. You can place them into your ADL notes field or to the "external" notes, and you can even have the starting tag in ADL and the end tag in the external notes. However, the word "record" here spans both – i.e. both notes fields together form a single one.

Resulting text will be checked against the $pdf_max_notechars and $pdf_chars_per_pix settings and truncated accordingly.

One more thing to keep in mind is: the TCPDF engine used to generate the PDFs is very picky when it comes to HTML. So take care to

  • use either plain text - or XHTML if you need tags (PDL however tries to keep track to fix up your code to a certain degree)
  • when using images, always specify HEIGHT and WIDTH – or it may be screwed up in the PDF (text length calculation may also fail then)
  • hmm – some more things may be added here when we find them.