2 files changed, 183 insertions, 1 deletions
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index a2821c7f..1b3caf4a 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -1,3 +1,3 @@
 tmpdir = $(mandir)/man1
-tmp_DATA= digikam.1 showfoto.1
+tmp_DATA= digikam.1 digitaglinktree.1 showfoto.1
 EXTRA_DIST=$(tmp_DATA)
diff --git a/doc/man/digitaglinktree.1 b/doc/man/digitaglinktree.1
new file mode 100644
index 00000000..fdfe9e09
--- /dev/null
+++ b/doc/man/digitaglinktree.1
@@ -0,0 +1,182 @@
+.\"             -*-Nroff-*-
+.\"
+.TH digitaglinktree 1 "16 Aug 2006 " " " "Linux User's Manual"
+.SH NAME
+digitaglinktree \- Export tag structure of photos in digikam to the filesystem.
+.SH SYNOPSIS
+.B digitaglinktree 
+.B -r\fI rootdir\fR
+
+.B -l\fI taglinkdir\fR
+|
+.B -A\fI archivedir\fR
+
+.B -d\fI database\fR
+
+.B [-H|-f|-a|-v|-C]
+
+.SH DESCRIPTION
+.B "digitaglinktree "
+will create a linktree for all photos in a digikam database that have tags set
+on them. Tags (like eg. "family", "events", ...)  are used in digikam to create
+virtual folders containing images that all have one or more tags assigned. 
+Please note: Photos that have no tags at all assigned are silently ignored by
+this script. The program will not modify or even touch your original photos
+managed by digikam. 
+ 
+
+The script can be used in two ways: If you call it using
+Option  -l \fItaglinkdir\fR  the script will create the user specified 
+directory  \fItaglinkdir\fR and inside this directory it will create sub
+directories for digikam tags  set on the photos. Inside these subdirectories it
+will finally  place symbolic or hard links  (see -H) to photos having the tags
+in question.  As a result you will see the tags of your photos as folders and in
+these folders  you will find links to your original photos.  
+
+
+In this way you can access the collection of all images that share a certain tag
+by changing directory to the folder with the tags name created by this script.
+This allows you e.g. to run JAlbum a photo album software that needs to find the
+pictures to be put into a web album in the filesystem because JAlbum cannot
+access digikams virtual folders directly.
+
+
+The second way of calling this script is the so called archive-mode by setting 
+option  -A \fIarchiveDir\fR.
+
+Archive mode is thought for people who want to archive  tagged photos
+independently of digikams root directories and the photos therein.  This way you
+can put your photos and their tag structure in eg. a tar archive and send it  to
+a friend, who can look at the photos  via their tag structure. In this mode the
+script creates the directory given as  parameter to -A and in this directory two
+more subdirectories. One named  Photos and a second named Tags.  The Photos
+directory contains hard links  to your original photos, and the Tags directory
+contains a subdirectory for each  Tag used by any of your photos. Inside this
+subdirectory there are links (either symbolic or hard links) to the files in the
+Photos directory. This way the archive  directory needs nearly no additional
+space on your harddisk and you have an archive that  allows you or a friend to
+easily look at the photos tag structure. 
+
+Another benefit from using this script is that you have kind of a backup of your
+tag settings for all of your photos. The backup is simply the directory
+structure containing links to the original images that wear the tags.
+This could become important if
+for whatever reason the digikam.db file gets corrupted or even lost.
+
+.PP
+.SH "COMMAND\-LINE OPTIONS"
+.TP
+\fB \-r \fIrootdir\fR 
+\fIrootdir\fR denotes the digikam base directory containing all your photos.
+
+.TP
+\fB \-l\fI taglinkdir\fR
+Parameter \fI taglinkdir\fR denotes a directory in which the tag structure of 
+all your photos stored in 
+rootdir will be exported to by creating subdirectories for each tag and placing 
+symbolic links in these subdirectories that point to the original photo wearing
+the tags. If calling the script with option  -l\fI taglinkDir\fR you also have
+to  specify options -r  \fIrootdir\fR as well as -d \fIdatabase\fR.
+
+.TP
+\fB \-A \fIarchivedirectory\fR 
+\fIarchivedirectory\fR denotes a directory into which the script will export the photos  and their tag
+structure. -A has to be used together with option  -r  \fIrootdir\fR as well as 
+-d\fI database\fR else the script will terminate.  Inside the archive  directory
+the script will create a Photos and a Tags directory. It will put hard links in
+the  Photos directory  that point to your original photos. By using hard links
+you are independent  of changes in your digikam root directory but on the other
+hand you are limited to one filesystem.  So the directory given by 
+-r \fIrootdir\fR and the directory specified for -A \fIarchivedir\fR have to be  one
+the same filesystem. The Tags subdirectory will contain links to the files in
+the Photos directory. This way you have one archive directory that is completely
+self contained. You can tar it, send it to a friend or  just put it somewhere
+for archivel or backup purposes. Usually only those photos will be archived that
+have a digikam tag set on them. By using option -C however you can perform a
+complete archive. See -C for more infos. 
+
+.TP
+\fB \-d \fIdatabase\fR
+\fIdatabase\fR is the complete path including the filename to digikams photo database which
+usually can be found in digikams root directory. The files name  is usually
+digikam.db .
+
+.TP
+\fB \-C\fR
+When the script is called with option -A \fIarchivedir\fR only those photos
+will be archived (by placing links) in the Photos subdirectory of
+\fIarchivedir\fR that have at least one digikam tag set. By setting option -C all
+photos will be  archived to  \fIarchivedir\fR no matter if they have a tag set
+or not. Note: This only changes the contents of the Photos  subdirectory not of
+the Tags subdirectory in the \fIarchivedir\fR directory.
+
+.TP
+\fB \-a \fR
+By default the script will try to create relative symbolic links from the
+directory  \fItaglinkdir\fR  set by option -l to the photo files under  
+\fIrootdir\fR given by option -r. Using this option will result in  absolute symbolic
+links beeing created instead of relative ones.
+
+.TP
+\fB \-H \fR
+By default the script will create soft (symbolic) links from the Tag-Tree to the 
+photos. By setting option -H the script will use hard links instead. Please note 
+that hard links can only be created inside one filesystem. So your photos and the Tag tree
+have to be one the same filesystem. If not you will see a warning about this problem and the script
+will not run.
+
+.TP
+\fB \-f \fR
+In digikam photos can have hierachical tags (tags that have subtags). In this case 
+digitaglinktree would by default add a directory for the tag and a subdirectory for 
+each of the subtags of this tag. By setting \fB \-f \fR a subtag is treated like a 
+regular tag just as its parent tag so digitaglinktree will create all subdirectories 
+for tags and subtags at the same level independent of the tag - subtag hierarchy.
+
+.TP
+\fB \-v \fR
+Prints the scripts version number and exits.
+
+
+.SH CONFIGURATION
+
+The script has to know which version of database is beeing used by digikam. 
+The script needs this information to find the correct sqlite binary to 
+start queries to the database.
+.sp
+You have to configure the script by setting the path to the sqlite binary that
+is used by the script to query the digikam database digikam.db. Since older
+digikam version use sqlite in version 2, but later digikam 0.80 versions
+needs sqlite version 3 you have to take care to install the correct version of
+sqlite for the installed digikam version and to set the path to the correct
+sqlite executable in the scripts head:
+.sp
+Choose
+
+$SQLITE="/usr/bin/sqlite3"; 
+
+for digikam version 0.8x and 0.9x and 
+
+$SQLITE="/usr/bin/sqlite";  
+
+for digikam version 0.7x.
+
+.SH EXAMPLE
+
+A call to digitaglinktree is shown below:
+
+digiTagLinktree -r /home/user/photos -l /home/user/photos/tags \
+            -d /home/user/photos/digikam.db
+
+In this example digikams photo root denoted by -r is /home/user/photos where all of the photos 
+can be found that are managed by digikam. The option -l /home/user/photos/tags
+tells the script that all the subdirectories and symbolic links will be placed in 
+the directory /home/user/photos/tags. Because the link directory is 
+below digikams root directory in this example, you will see a new album in digikam
+after running the script that contains the exported tag structure with all the photos inside. 
+Since only links are used here this tag structure does hardly need any additional space on your
+harddisk. 
+
+.SH AUTHORS
+.B digitaglinktree
+was written by Rainer Krienke <krienke at uni-koblenz.de>