photo-stats

commit 11aa35b6305752b6b75902f20e91d8fb072d1766
parent c4eef1a47a875107b19e64b22a0cb22a23925a3e
Author: René Wagner <rwa@clttr.info>
Date:   Sun,  2 Apr 2023 19:55:13 +0200

create man page for phosta-alias and phosta-examples

Diffstat:
M
Makefile
 | 
15
+++++++++++----
M
README.md
 | 
21
++++++++++++++-------
M
phosta
 | 
28
+++++++++++-----------------
M
phosta-alias.5.scd
 | 
17
+++++++++++++++--
A
phosta-examples.7.scd
 | 
39
+++++++++++++++++++++++++++++++++++++++
M
phosta.1.scd
 | 
8
++++----

6 files changed, 94 insertions(+), 34 deletions(-)
diff --git 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.1: phosta.1.scd
 phosta-alias.5: phosta-alias.5.scd
 	scdoc < $< > $@
 
-all: phosta phosta.1 phosta-alias.5
+phosta-examples.7: phosta-examples.7.scd
+	scdoc < $< > $@
+
+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
@@ -2,7 +2,9 @@
 
 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 @@ A total of **5090 images** matched your criteria.
 '-----------------------------+---------------+-------+---------'
 ```
 
-## requirements
-The famous `exiftool` needs to be installed on your system.
-
-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`.
+## Installation
+Clone the repo, then run
+```
+$ make
+$ sudo make install
+```
 
-For ArchLinux, `phosta` is available as an AUR package that takes care of the dependencies.
+For ArchLinux, `phosta` is available as an [AUR package](https://aur.archlinux.org/packages/phosta) 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 @@ Additionally the following perl modules need to be installed:
 - File::Spec::Functions
 - Perl::DBD::SQLite
 - Perl::DBI
+- Perl::Modern
 - Text::SimpleTable::AutoWidth
 - Term::AnsiColor
 - Scalar:Util
diff --git 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 @@ use Data::Dumper;
 $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,13 +40,19 @@ 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 result_to_table
 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 @@ sub main::HELP_MESSAGE
 	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
@@ -1,15 +1,28 @@
 PHOSTA-ALIAS(5)
 
 # NAME
+.phosta.alias - configuration of word replacement for *phosta*(1)
 
-\~/.phosta.alias\ is the config file for name replacement
+# 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.
+
+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
@@ -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
@@ -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