commit c1362a695fcb78b0e9e6830f704c222317cb0ed4
parent 18bfb377715999e7257b3753e9d3eab57cdd4c9e
Author: René Wagner <rwa@clttr.info>
Date: Tue, 11 Apr 2023 22:07:49 +0200
finish manpage for phosta
Diffstat:
4 files changed, 117 insertions(+), 11 deletions(-)
diff --git a/phosta b/phosta
@@ -18,7 +18,7 @@ use Data::Dumper;
$Getopt::Std::STANDARD_HELP_VERSION = 'true';
-my $VERSION = '1.1';
+my $VERSION = '1.2';
my $PROGRAM = 'phosta';
my $configfile = catfile(File::HomeDir->my_home, '.phosta.conf');
@@ -26,7 +26,7 @@ my $aliasfile = catfile(File::HomeDir->my_home, '.phosta.alias');
# read commandline switches
our $opt_E='jpg,jpeg';
-our $opt_D=getcwd . "/photo_stats.db";
+our $opt_D= catfile(File::HomeDir->my_home, '.phosta.db');
our $opt_p='';
our $opt_t=undef;
our $opt_c=0;
@@ -442,7 +442,7 @@ sub main::HELP_MESSAGE
say 'Options with upper-case letters are automatically saved in the user config and can be omitted if no change is required.';
say '';
say 'generic options:';
- say ' -D <file> : path and name of the db file to use, defaults to <workingdir>/photo_stats.db';
+ say ' -D <file> : path and name of the db file to use, defaults to ~/photo_stats.db';
say ' -c : clear the database';
say ' -v : be verbose - print some debug output';
say ' --help : show this help';
diff --git a/phosta-alias.5.scd b/phosta-alias.5.scd
@@ -4,7 +4,7 @@ phosta-alias(5) "phosta" "Alias File Format Definition"
phosta-alias - configuration of word replacement for *phosta*(1)
# SYNOPSIS
-*phosta* allows to configure automatic word replacement during the import of data.
+*phosta* allows to configure automatic word replacement during the data import.
This allows to sanitize and unify ambigous naming used by different image processing tools.
This is configured via the user-defined config file _~/.phosta.alias_.
@@ -13,7 +13,7 @@ The replacement takes place when importing the EXIF data in our database. Every
# SYNTAX
The file _~/.phosta.alias_ is a plain text file. It should hold an alias definition per line.
-An alias definition consists of the old string, which should be replaced, and the new string which should be put in instead, separat by atleast on tabstop.
+An alias definition consists of the old string, which should be replaced, and the new string which should be put in instead, separat by atleast one tabstop.
```
Old company new company
@@ -26,5 +26,5 @@ lensname real lensname
# AUTHORS
-Maintained by René Wagner <rwa@clttr.info>.
+Maintained by René Wagner <rwa@clttr.info>.++
Project repo can be found at https://git.sr.ht/~rwa/photo-stats
diff --git a/phosta-examples.7.scd b/phosta-examples.7.scd
@@ -36,5 +36,5 @@ phosta -s model -f maker!=ricoh
# AUTHORS
-Maintained by René Wagner <rwa@clttr.info>.
+Maintained by René Wagner <rwa@clttr.info>.++
Project repo can be found at https://git.sr.ht/~rwa/photo-stats
diff --git a/phosta.1.scd b/phosta.1.scd
@@ -1,18 +1,124 @@
-PHOSTA(1)
+phosta(1) "phosta" "phosta Documenation"
# NAME
phosta - photo statistic processor for your terminal
# SYNOPSIS
+*phosta* [*-v*] [*-D* _<file>_] ...
+*phosta* is a small statistics processor for your terminal.
+It extracts EXIF data of your images and stores it in an internal database. This allows you to query many different aggregations (like "which lens did i use most recently?") without the need to read over all your images again and again. You don't even need to have access to your images when digging through the stats.
-# DESCRIPTION
+# USAGE
+
+You could use as many different databases as you'd like to, whatever suits your needs (maybe split private and commercial data). Use the *-D* param to specify on which database file you want to operate.
+
+## POPULATE DATABASE
+The first step is to populate your database with the EXIF data extracted from your images. You can import the data of all your images at once or doing incremental imports. Each import will update existing data and add new files based on file path and name.
+
+Different image processing tools may use a different naming for one and the same body or lens. To sanitize your data, *phosta* supports a simple word replacement mechanism during data import, see *phosta-alias*(5) for more information.
+
+## QUERY DATA
+*Selecting Data*++
+What data you are going to see is specified by the *-s* param. urrently the following fields are collected and stored in the database:
+
+- file
+- maker
+- model
+- lens maker
+- lens
+- aperture
+- exposuretime
+- iso
+- focallength
+- focallength35mm
+
+*Grouping*++
+Grouping can be applied based on various pre-defined time ranges.
+
+*Filters*++
+Filtering the raw data allows you to narrow down the result set. You can filter by time range using the *-t* param or apply an arbitrary text filter with the *-f* param.
+
+*Limits*++
+You can limit the output to the top results using the *-n* param. The tool will tell you how many lines are skipped due to this param.
+
+Additionally there's the *-e* switch to skip the "empty" result. The empty result occur especially on some EXIF fields like exposure time, aperture and the like where sometimes invalid values are stored in the images.
+
+*Ordering*++
+By default the ordering starts with the results with the most count and descends. You can enforce an arbitrary ordering by specifying the fields you want to order by with the *-o* param.
+
+Additionally there's the *-r* flag to invert the sort order, which means order in ascending manner.
+
+You can find a set of sample querys in *phosta-examples*(7).
+
+# OPTIONS
+Options in CAPITAL LETTERS (like *-D*) will automatically be persisted in the user's config file located at _~/.phosta.conf_.
+
+## GENERIC OPTIONS
+ *-D* <file>
+ Path and name of the database file to use, either for populating a new database or defining which database should be queried.++
+ The last database used is automatically persisted to the user config so you may skip the parameter for the next query.++
+ default: _~/photo_stats.db_
+
+ *-c*
+ Remove all data from the working database (see *-D*). Use with caution, there will be no additional warning!
+
+## DATA EXTRACTION OPTIONS
+ *-p* <folder>
+ Read the media files that match the extension filter (see *-E*) in the given folder and all subfolders, extract the EXIF data Populate database with the EXIF data of the media files in the specified folder
+
+ *-E* <ext>
+ List of comma separated extensions used for scanning image files.++
+Only media files which match (case-insensitive!) the given extensions are added to the database.++
+Default: _jpg,jpeg_
+
+## QUERY OPTIONS
+ *-e*
+ Skip lines with empty selected or grouping fields.
+
+ *-f* <expr>
+ Filter images based on the given expression, multiple expression can be given as a comma-separated list.++
+This works as a case-insensitive search, multiple expressions need to match all (AND logic), use _field=value_ for CONTAINS and _field!=value_ for NOT CONTAINS++
+Allowed values: _file_, _maker_, _model_, _lensmake_, _lens_, _aperture_, _exposuretime_, _iso_, _focallength_, _focallength35mm_
+
+ *-g* <period>
+ Group result set by a time period.++
+Default: total (which means no grouping by period)++
+Allowed values: _year_, _month_, _week_, _hour_
+
+ *-n* <number>
+ Limit the resultset to <number> of lines.
+
+ *-o* <fields>
+ Sort the output by the given fields (sequence matters!) in descending order.++
+Allowed values: any comma separated combination of the values of *-g* and *-s* param and _count_
+
+ *-r*
+ Sort in reverse (ascending) order, default is descending order
+
+ *-s* <fields>
+ Specify the information you want to include in the output, multiple fields should be listed comma-separated (without withspaces or enclosed in "")++
+Default: none (just show number of images)++
+Allowed values: _file_, _maker_, _model_, _lensmake_, _lens_, _aperture_, _exposuretime_, _iso_, _focallength_, _focallength35mm_
+
+ *-t* <range>
+ only take images into account which have been taken in the given timerange.++
+<range> must be specified as _YYYYMMDD-YYYYMMDD_, you can omit the first or the later value, e.g. _-YYYYMMDD_.
+
+ *-T* <value>
+ Show results as always as a table (on) or not (off) or auto (display as chart only when single field is selected).++
+Default: auto++
+Allowed values: _auto_, _on_, _off_
+
+ *-W* <number>
+ Define maximum width of the output in characters, _-1_ deletes the current setting.++
+Default: 80 (a minimum of 50 is required for meaningful output)
# SEE ALSO
-*phosta_alias*(5), *phosta-examples*(7)
+*phosta_alias*(5), *phosta-examples*(7), *phosta-faq*(7)
# AUTHOR
-Maintained by René Wagner <rwa@clttr.info>.
+Maintained by René Wagner <rwa@clttr.info>.++
Project repo can be found at https://git.sr.ht/~rwa/photo-stats
