Merge branch 'feature/upstream' into develop

3 files changed, 411 insertions, 112 deletions

diff --git a/doc/analyze-pv-structure.1.pod b/doc/analyze-pv-structure.1.pod
new file mode 100644
index 0000000..6b7f9cc
--- /dev/null
+++ b/doc/analyze-pv-structure.1.pod
@@ -0,0 +1,159 @@
+=head1 NAME
+
+analyze-pv-structure - Analyzes the location of metadata in a variety of RAW, jpeg and video files
+
+=head1 SYNOPSIS
+
+B<analyze-pv-structure> [options] source [outfile]
+
+Positional Options:
+    source
+    outfile
+
+Options:
+    -h, --help
+    --clear, -c
+    --keep-names, -k
+    --no-dng, -d
+    --video
+    --only-video
+    --include-jpeg, -j
+    --only-jpeg, -J
+    --show-errors, -e
+    --load, -l
+    --verbose, -v
+
+=head1 DESCRIPTION
+
+B<Analyze PV Structure> analyzes photos and videos to help determine how much of a file
+needs to be read to extract its metadata, embedded thumbnail or render a thumbnail. It is
+associated with Rapid Photo Downloader.
+
+It uses exiv2 to extract photo metadata,and ExifTool to extract video metadata.
+
+To work, this program requires that the scanned photos and videos not be in the Linux
+kernel's disk cache. To ensure this, the program provides option, specified by the command line
+argument '--clear', to instruct the kernel to sync and then drop clean caches, as well as
+reclaimable slab objects like dentries and inodes. This is a non-destructive operation and will
+not free any dirty objects. See https://www.kernel.org/doc/Documentation/sysctl/vm.txt
+
+Specify an outfile if you want to share the analysis of your files with others.
+
+=head1 REQUIREMENTS
+
+To run this program, you need to install vmtouch. Get it at http://hoytech.com/vmtouch/
+
+To see an optional but helpful progress bar, install pyprind: https://github.com/rasbt/pyprind
+
+=head1 OPTIONS
+
+=over
+
+=item B<-h, --help>
+
+Show help message and exit.
+
+=item B<source>
+
+Directory in which to recursively scan for photos and videos, or a previously saved outfile.
+
+=item B<outfile>
+
+Optional file in which to save the analysis.
+
+=item B<--clear, -c>
+
+Clear the sync and drop clean caches (see note above). The script will prompt for super user
+permission to execute this.
+
+=item B<-v, --verbose>
+
+Displays program information on the command line as the program runs.
+
+=item B<-l, --load>
+
+Don't scan. Instead use previously generated outfile as input.
+
+=item B<-k, --keep-names>
+
+If saving the analysis to file, don't first remove the file names and paths from the analysis.
+Don't specify this option if you want to keep this information private when sharing the analysis
+with others.
+
+=item B<-d, --no-dng>
+
+Don't scan DNG files.
+
+=item B<--video>
+
+Scan videos.
+
+=item B<--only-video>
+
+Scan only videos, ignoring photos.
+
+=item B<-j, --include-jpeg>
+
+Scan jpeg images.
+
+=item B<-J, --only-jpeg>
+
+Scan only jpeg images.
+
+=item B<-e, --show-errors>
+
+Don't show progress bar while scanning, and instead show all errors output by exiv2 (useful if
+exiv2 crashes, which takes down this  script too).
+
+=back
+
+=head1 EXAMPLES
+
+sudo analyze-pv-structure -c /home/user/Pictures/ pv_analysis
+
+=over
+
+Analyze photos found in the user's Pictures folder, clear the system caches prior to analysis,
+and save the analysis in the file pv_analysis without any filename or path information.
+
+=back
+
+analyze-pv-structure -v pv_analysis
+
+=over
+
+Output verbose analysis of the previously saved outfile pv_analysis.
+
+=back
+
+
+analyze-pv-structure --video /home/user/Videos/
+
+=over
+
+Analyze videos (and any photos) found in the user's Videos folder.
+
+=back
+
+=head1 SEE ALSO
+
+rapid-photo-downloader(1)
+
+=head1 AUTHORS
+
+B<Analyze PV Structure> was written by Damon Lynch <damonlynch@gmail.com>.
+
+This manual page was written by Damon Lynch.
+
+=head1 COPYRIGHT
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3, or (at your option) any
+later version.
+
+On Debian GNU/Linux systems, the complete text of the GNU General
+Public License can be found in `/usr/share/common-licenses/GPL'.
+
+=cut
+
diff --git a/doc/rapid-photo-downloader.1.pod b/doc/rapid-photo-downloader.1.pod
new file mode 100644
index 0000000..f9fdd0c
--- /dev/null
+++ b/doc/rapid-photo-downloader.1.pod
@@ -0,0 +1,252 @@
+=head1 NAME
+
+rapid-photo-downloader - Downloads, renames and backs up photos and videos from cameras, phones,
+memory cards and other devices
+
+=head1 SYNOPSIS
+
+B<rapid-photo-downloader> [options] [path]
+
+Options:
+
+    -h, --help
+    --version
+    --detailed-version
+    -v, --verbose
+    --debug
+    -e, --extensions
+    --photo-renaming {on,off}
+    --video-renaming {on,off}
+    -a {on,off}, --auto-detect {on,off}
+    -t {on,off}, --this-computer {on,off}
+    --this-computer PATH
+    --photo-destination PATH
+    --video-destination PATH
+    -b {on,off}, --backup {on,off}
+    --backup-auto-detect {on,off}
+    --photo-backup-identifier FOLDER
+    --video-backup-identifier FOLDER
+    --photo-backup-location PATH
+    --video-backup-location PATH
+    --ignore-other-photo-file-types
+    --auto-download-startup {on,off}
+    --auto-download-device-insertion {on,off}
+    --thumbnail-cache {on,off}
+    --delete-thumbnail-cache
+    --forget-remembered-files
+    --import-old-version-preferences
+    --reset
+    --log-gphoto2
+    --camera-info
+
+
+=head1 DESCRIPTION
+
+B<Rapid Photo Downloader> imports photos and videos from cameras, phones,
+memory cards and other devices at high speed. It can be configured to
+rename photos and videos with meaningful filenames you specify. It can also
+back up photos and videos as they are downloaded. It downloads from and backs
+up to multiple devices simultaneously.
+
+Unique to Rapid Photo Downloader is its Timeline, which groups photos and
+videos based on how much time elapsed between consecutive shots. Use it to
+identify photos and videos taken at different periods in a single day or
+over consecutive days.
+
+Files are downloaded from two different types of sources: (1) one or more
+automatically detected devices like cameras, phones, memory cards, and external
+drives; and (2) a single manually specified path, shown in the user interface as
+"This Computer".
+
+=head1 PATH
+
+Optional value that when specified, is parsed to determine if it represents an
+automatically detected device or a path on this computer.
+
+If the path represents an automatically detected device, automatic detection of
+devices is turned on, as in the B<--auto-detect> option. Furthermore, downloading from a manually
+specified path as in the B<--this-computer-location> option is turned off.
+
+Otherwise, the path is assumed to be a manually specified path as in the
+B<--this-computer-location> option, in which case downloading from this computer is turned on
+and downloading from automatically detected devices is turned off.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-h, --help>
+
+Show help message and exit.
+
+=item B<--version>
+
+Displays information about the currently installed version and exits.
+
+=item B<--detailed-version>
+
+Displays information about the currently installed version and its libraries and exits.
+
+=item B<-v, --verbose>
+
+Displays program information on the command line as the program runs.
+
+=item B<--debug>
+
+Displays debugging information on the command line as the program runs
+
+=item B<-e, --extensions>
+
+Displays image file extensions the program recognizes and exits.
+
+=item B<--photo-renaming {on,off}>
+
+Turn on or off the the renaming of photos while downloading,
+overwriting existing program preferences. If turned on,
+the renaming scheme used will incorporate the photo's metadata date, time,
+the number of downloads today, and the file extension in lower case:
+S<C<YYYYMMDD-HHMM-E<lt>DownloadsTodayE<gt>.E<lt>LowercaseExtensionE<gt>>>,
+e.g. 20160512-1309-23.jpg.
+
+=item B<--video-renaming {on,off}>
+
+Turn on or off the the renaming of videos while downloading,
+overwriting existing program preferences. If turned on,
+the renaming scheme used will incorporate the video's metadata date, time,
+the number of downloads today, and the file extension in lower case:
+S<C<YYYYMMDD-HHMM-E<lt>DownloadsTodayE<gt>.E<lt>LowercaseExtensionE<gt>>>,
+e.g. 20160512-1429-26.mp4.
+
+=item B<-a {on,off}, --auto-detect {on,off}>
+
+Turn on or off the automatic detection of devices from which to download, 
+overwriting existing program preferences.
+
+=item B<-t {on,off}, --this-computer {on,off}>
+
+Turn on or off downloading from this computer (see description above),
+overwriting existing program preferences.
+
+=item B<--this-computer-location PATH>
+
+The PATH on this computer from which to download, overwriting existing program 
+preferences.
+
+=item B<--photo-destination PATH>
+
+Sets the PATH where photos will be downloaded to, overwriting existing program
+preferences.
+
+=item B<--video-destination PATH>
+
+Sets the PATH where videos will be downloaded to, overwriting existing program
+preferences.
+
+=item B<-b {on,off}, --backup {on,off}>
+
+Turns on or off the backing up of photos and videos while downloading, overwriting
+existing program preferences.
+
+=item B<--backup-auto-detect {on,off}>
+
+Turns on or off the automatic detection of backup devices, overwriting
+existing program preferences.
+
+=item B<--photo-backup-identifier FOLDER>
+
+Sets the FOLDER in which backups are stored on the automatically detected photo backup 
+device, with the folder's name being used to identify whether or not the device
+is used for backups. For each device you wish to use for backing up photos to, 
+create a folder on it with this name. Overwrites existing program preferences.
+
+=item B<--video-backup-identifier FOLDER>
+
+Sets the FOLDER in which backups are stored on the automatically detected video backup 
+device, with the folder's name being used to identify whether or not the device
+is used for backups. For each device you wish to use for backing up videos to, 
+create a folder on it with this name. Overwrites existing program preferences.
+
+=item B<--photo-backup-location PATH>
+
+Sets the PATH where photos will be backed up when automatic detection of backup devices
+is turned off. Overwrites existing program preferences.
+
+=item B<--video-backup-location PATH>
+
+Sets the PATH where videos will be backed up when automatic detection of backup devices
+is turned off. Overwrites existing program preferences.
+
+=item B<--ignore-other-photo-file-types>
+
+Do not download photos with the following extensions: TIF, TIFF and MPO.
+
+=item B<--auto-download-startup {on,off}>
+
+Turns on or off starting downloads as soon as the program itself starts.
+
+=item B<--auto-download-device-insertion {on,off}>
+
+Turns on or off starting downloads as soon as a device is inserted.
+
+=item B<--thumbnail-cache {on,off}>
+
+Turns on or off use of the Rapid Photo Downloader Thumbnail Cache. Turning it off does not
+delete existing cache contents.
+
+=item B<--delete-thumbnail-cache>
+
+Deletes all thumbnails in the Rapid Photo Downloader Thumbnail Cache, and exits.
+
+=item B<--forget-remembered-files>
+
+Forgets which files have been previously downloaded, and exits.
+
+=item B<--import-old-version-preferences>
+
+Imports preferences from an old program version (S<0.4.11> or earlier), and exits. Requires the
+command line program S<gconftool-2>.
+
+=item B<--reset>
+
+Resets all program settings to their default values, deletes all thumbnails in the Thumbnail
+cache, forgets which files have been previously downloaded, and exits.
+
+=item B<--log-gphoto2>
+
+Includes gphoto2 debugging information in log files, which can be useful when analyzing
+any problems libgphoto2 might have accessing a camera.
+
+=item B<--camera-info>
+
+Print information to the terminal about attached cameras and exit.
+
+=back
+
+=head1 ENVIRONMENT
+
+If the environment variable RPD_SCAN_DEBUG is set to any value, the program's scan
+operation will output volumous debug information to stdout.
+
+
+=head1 SEE ALSO
+
+analyze-pv-structure(1)
+
+=head1 AUTHORS
+
+B<Rapid Photo Downloader> was written by Damon Lynch <damonlynch@gmail.com>.
+
+This manual page was written by Damon Lynch.
+
+=head1 COPYRIGHT
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3, or (at your option) any
+later version.
+
+On Debian GNU/Linux systems, the complete text of the GNU General
+Public License can be found in `/usr/share/common-licenses/GPL'.
+
+=cut
+
diff --git a/doc/rapid-photo-downloader.pod b/doc/rapid-photo-downloader.pod
deleted file mode 100644
index 43a97f9..0000000
--- a/doc/rapid-photo-downloader.pod
+++ /dev/null
@@ -1,112 +0,0 @@
-=head1 NAME
-
-rapid-photo-downloader - imports photos and videos from cameras, memory cards and other devices
-
-=head1 SYNOPSIS
-
-B<rapid-photo-downloader> [options]
-
-Options:
-  --version         
-  -h, --help        
-  -v, --verbose
-  -q, --quiet
-  -e, --extensions
-  --focal-length=FOCAL_LENGTH
-  -a, --auto-detect
-  -l PATH, --device-location=PATH
-  --reset-settings
-  
-=head1 DESCRIPTION
-
-B<Rapid Photo Downloader> imports photos and videos from cameras, memory cards and Portable
-Storage Devices, providing a variety of flexible, user-defined options for subfolder creation,
-photo and video renaming, and backup. It can download from more than one device in parallel.
-
-
-=head1 OPTIONS
-
-=over
-
-=item B<--version>
-
-Displays information about the currently installed version and exits.
-
-=item B<-h, --help>
-
-Show help message and exit.
-
-=item B<-v, --verbose>
-
-Displays program information on the command line as the program runs.
-
-=item B<-d, --debug>
-
-Displays debugging information on the command line as the program runs
-
-=item B<-q, --quiet>
-
-Only display output errors and warnings to the command line as the program runs.
-
-=item B<-e, --extensions>
-
-Displays image file extensions the program recognizes and exits.
-
-=item B<--focal-length=FOCAL_LENGTH>
-
-If an aperture value of 0.0 is encountered, the focal length metadata will be set to the 
-number passed, and its aperture metadata to f/8.
-
-=item B<-a, --auto-detect>
-
-Automatically detect devices from which to download, overwriting existing program preferences.
-
-=item B<-l PATH, --device-location=PATH>
-
-Manually specify the PATH of the device from which to download, overwriting existing program 
-preferences.
-
-=item B<--reset-settings>
-
-Resets all program settings and preferences to their default values and exits.
-
-=back
-
-=head1 ENVIRONMENT VARIABLES
-
-=over
-
-=item B<LOCALEDIR>
-
-If set, overrides the system-wide directory in which translation data will be searched for.
-
-=item B<LANG>
-
-The system-wide locale used for translations.
-
-=back
-
-=head1 BUGS
-
-* Support for downloading directly from cameras is experimental. Not all cameras are supported.
-
-Please report bugs at https://bugs.launchpad.net/rapid
-
-=head1 AUTHORS
-
-B<Rapid Photo Downloader> was written by Damon Lynch <damonlynch@gmail.com>.
-
-This manual page was written by Damon Lynch.
-
-=head1 COPYRIGHT
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.
-
-On Debian GNU/Linux systems, the complete text of the GNU General
-Public License can be found in `/usr/share/common-licenses/GPL'.
-
-=cut
-