diff --git a/Makefile b/Makefile
index 0c9102996ad488121812d479399e3f0d05ed09fa..f9390dfd5328d89fe39bb2bef1edb17925826c53 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@ VERSION=1.1
PREFIX?=/usr/local
BINDIR?=$(PREFIX)/bin
MANDIR?=$(PREFIX)/share/man
+DOCDIR?=$(PREFIX)/share/doc
.DEFAULT_GOAL=all
phosta:
@@ -12,21 +13,27 @@
phosta-alias.5: phosta-alias.5.scd
scdoc < {body}lt; > $@
-all: phosta phosta.1 phosta-alias.5
+phosta-examples.7: phosta-examples.7.scd
+ scdoc < {body}lt; > $@
+
+all: phosta phosta.1 phosta-alias.5 phosta-examples.7
clean:
- rm -rf phosta.1 phosta-alias.5
+ rm -rf phosta.1 phosta-alias.5 phosta-examples.7
install: all
- mkdir -p $(DESTDIR)/$(BINDIR) $(DESTDIR)/$(MANDIR)/man1 $(DESTDIR)/$(MANDIR)/man5 $(DESTDIR)/$(PCDIR)
+ mkdir -p $(DESTDIR)/$(BINDIR) $(DESTDIR)/$(MANDIR)/man1 $(DESTDIR)/$(MANDIR)/man5 $(DESTDIR)/$(MANDIR)/man7 $(DESTDIR)/$(DOCDIR)/phosta/
install -m755 phosta $(DESTDIR)/$(BINDIR)/phosta
install -m644 phosta.1 $(DESTDIR)/$(MANDIR)/man1/phosta.1
install -m644 phosta-alias.5 $(DESTDIR)/$(MANDIR)/man5/phosta-alias.5
+ install -m644 phosta-examples.7 $(DESTDIR)/$(MANDIR)/man7/phosta-examples.7
+ install -m644 LICENSE $(DESTDIR)/$(DOCDIR)/phosta/LICENSE
uninstall:
rm -f $(DESTDIR)/$(BINDIR)/phosta
rm -f $(DESTDIR)/$(MANDIR)/man1/phosta.1
rm -f $(DESTDIR)/$(MANDIR)/man5/phosta-alias.5
+ rm -f $(DESTDIR)/$(MANDIR)/man7/phosta-examples.7
-check: phosta phosta.1 phosta-alias.5
+check: phosta phosta.1 phosta-alias.5 phosta-examples.7
@find test -perm -111 -exec '{}' \;
diff --git a/README.md b/README.md
index bbb477687f69c4513c0154f61c85876e4fbe7be7..7a686fe218ec3f56c5f3a36c7b6deca6509ac5b6 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,9 @@ # Photo Stats
This project is a small statistic generator for the terminal which accumulates data about your photographical habits.
-It is mainly a selfcontained [SQlite](https://sqlite.org) database that stores the data which is extracted from the exif data of your images using [exiftool](https://exiftool.org/) and provides some methods to query the gathered data and gain some statistical insight.
+It is mainly a selfcontained [SQlite](https://sqlite.org) database that stores the data which is extracted from the EXIF data of your images using [exiftool](https://exiftool.org/) and provides some methods to query the gathered data and gain some statistical insight.
+
+For extensive usage information see `man phosta`.
## features
- loading of EXIF data from media files to a self-contained database
@@ -83,17 +85,21 @@ | RICOH | Caplio R7 | 201 | 3.9% |
'-----------------------------+---------------+-------+---------'
```
-## requirements
-The famous `exiftool` needs to be installed on your system.
+## Installation
+Clone the repo, then run
+```
+$ make
+$ sudo make install
+```
-Simply clone the repo or manually download the scripts from https://git.sr.ht/~rwa/photo-stats/blob/master/phosta and put the file into a folder that is included in your `$PATH`.
+For ArchLinux, `phosta` is available as an [AUR package](https://aur.archlinux.org/packages/phosta) that takes care of the dependencies.
-For ArchLinux, `phosta` is available as an AUR package that takes care of the dependencies.
-
-To run the script, open a shell and invoke `perl phosta`, on most systems it should be sufficient to just invoke `phosta` (after you granted execute-permissions to the script).
+To run the script, open a shell and invoke `phosta`.
#### prerequisites for running the pure scripts
+- exiftool
+- SQLite 3
- Perl 5.30 (or newer)
Additionally the following perl modules need to be installed:
@@ -103,6 +109,7 @@ - File::HomeDir
- File::Spec::Functions
- Perl::DBD::SQLite
- Perl::DBI
+- Perl::Modern
- Text::SimpleTable::AutoWidth
- Term::AnsiColor
- Scalar:Util
diff --git a/phosta b/phosta
index 750cb2b9c6d8a6b3684f33b6d461acd8ac55124e..4bee1abe535cd0a0caf2a5f34eb3a5ddd3b271fb 100755
--- a/phosta
+++ b/phosta
@@ -1,5 +1,5 @@
#!/usr/bin/perl
-# Copyright(c) René Wagner 2019-2020
+# Copyright(c) René Wagner 2019-2023
# https://src.clttr.info/rwa/photo-stats
# published under BSD 3-Clause License
@@ -19,7 +19,7 @@
$Getopt::Std::STANDARD_HELP_VERSION = 'true';
my $VERSION = '1.1';
-my $PROGRAM = 'Photo Stats';
+my $PROGRAM = 'phosta';
my $configfile = catfile(File::HomeDir->my_home, '.phosta.conf');
my $aliasfile = catfile(File::HomeDir->my_home, '.phosta.alias');
@@ -40,12 +40,18 @@ our $opt_f=undef;
our $opt_e=0;
our $opt_W=80;
our $opt_T='auto';
+our $opt_h=undef;
getconfig();
-getopts('vcrp:n:g:s:t:D:E:o:f:eW:T:') or die "Invalid parameters provided! See 'phosta --help' for more details.";
+getopts('hvcrp:n:g:s:t:D:E:o:f:eW:T:') or die "Invalid parameters provided! See 'phosta --help' for more details.";
validate() or die "Invalid parameters provided! See 'phosta --help' for more details.";
my $dsn = "DBI:SQLite:dbname=$opt_D";
+
+if ($opt_h) {
+ main::HELP_MESSAGE();
+ exit 0;
+}
if ($opt_c) { unlink $opt_D; }
if ( !-e $opt_D ) { create_db($opt_D) or die 'database could not be created'; }
@@ -444,9 +450,8 @@
sub main::VERSION_MESSAGE()
{
say $PROGRAM . ' - version ' . $VERSION;
- say 'published under BSD 3 - Clause License';
- say 'Copyright(c) 2019-2020 René Wagner';
say 'https://git.sr.ht/~rwa/photo-stats';
+ say 'Copyright(c) 2019-2023 René Wagner - published under BSD 3 - Clause License';
}
sub main::HELP_MESSAGE
@@ -491,16 +496,5 @@ say ' -1 deletes the current setting';
say ' -T <value> : show results as always as a table (on) or not (off) or auto (chart when single field is selected), default is auto';
say ' allowed values: auto, on, off';
say '';
- say 'examples:';
- say ' phosta -E jpg,jpeg,tiff -D ~/Documents/stats.db -p ~/Pictures';
- say ' load EXIF data of files with the extensions jpg, jpeg and tiff in folder ~/Pictures to the database located in ~/Documents/stats.db';
- say '';
- say ' phosta -s model -g month -t 20190101-20121231 -o month,count';
- say ' show number of pictures taken with a specific camera body in 2019 grouped by month, sorted by newest month first';
- say '';
- say ' phosta -n 10 -s lens -o count';
- say ' show top 10 lenses used the most';
- say '';
- say ' phosta -s model -f maker!=ricoh';
- say ' show camera models where the maker field does not contain the term "ricoh"';
+ say 'For further information see the man pages phosta(1), phosta-alias(5) and phosta-examples(7).';
}
diff --git a/phosta-alias.5.scd b/phosta-alias.5.scd
index 794056503048e1af819a08e100c6aa9ef77c2b0f..6e38c94acf6e10759405a224a51261de80df7088 100644
--- a/phosta-alias.5.scd
+++ b/phosta-alias.5.scd
@@ -1,15 +1,28 @@
PHOSTA-ALIAS(5)
# NAME
+.phosta.alias - configuration of word replacement for *phosta*(1)
+
+# SYNOPSIS
+*phosta* allows to configure automatic word replacement during the import of data.
+This allows to sanitize and unify ambigous naming used by different image processing tools.
-\~/.phosta.alias\ is the config file for name replacement
+This is configured via the user-defined config file _~/.phosta.alias_.
+
+The replacement takes place when importing the EXIF data in our database. Every occurence of *old string* will be replaced by *new_string*. The search is *case-sensitive*.
# 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.
+```
+Old company new company
+lensname real lensname
+```
# SEE ALSO
-_phosta_(1)
+*phosta*(1), *phosta-examples*(7)
# AUTHORS
diff --git a/phosta-examples.7.scd b/phosta-examples.7.scd
new file mode 100644
index 0000000000000000000000000000000000000000..b34a52ad168ab227f69991c4df9d6b8046bff854
--- /dev/null
+++ b/phosta-examples.7.scd
@@ -0,0 +1,39 @@
+PHOSTA-EXAMPLES(7)
+
+# NAME
+phosta-examples - collection of example calls with params for *phosta*(1)
+
+# SYNOPSIS
+*phosta* allows to configure automatic word replacement during the import of data.
+This allows to sanitize and unify ambigous naming used by different image processing tools.
+
+# EXAMPLES
+- load EXIF data of files with the extensions jpg, jpeg and tiff in folder _~/Pictures_ to the database located in _~/Documents/stats.db_
+```
+phosta -E jpg,jpeg,tiff -D ~/Documents/stats.db -p ~/Pictures
+```
+
+## QUERY DATA
+- show number of pictures taken with a specific camera body in 2019 grouped by month, sorted by newest month first
+```
+phosta -s model -g month -t 20190101-20121231 -o month,count
+```
+
+- show top 10 lenses used the most
+```
+phosta -n 10 -s lens -o count
+```
+
+- show camera models where the maker field does not contain the term "ricoh"
+```
+phosta -s model -f maker!=ricoh
+```
+
+# SEE ALSO
+
+*phosta*(1), *phosta-alias*(5)
+
+# AUTHORS
+
+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
index 93d62cd530f37391576104977fb3b057e6aa574b..b6d70759a1d49ac6279c74afab9a694baedc7cec 100644
--- a/phosta.1.scd
+++ b/phosta.1.scd
@@ -1,18 +1,18 @@
PHOSTA(1)
# NAME
-
+phosta - photo statistic processor for your terminal
# SYNOPSIS
-# SYNOPSIS
+# DESCRIPTION
# SEE ALSO
-_phosta_alias_(5)
+*phosta_alias*(5), *phosta-examples*(7)
-# AUTHORS
+# AUTHOR
Maintained by René Wagner <rwa@clttr.info>.
Project repo can be found at https://git.sr.ht/~rwa/photo-stats