Merge branch 'feature/upstream' into develop

1 files changed, 159 insertions, 0 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
+