exifcomment & other utilities man pages??

[tester0077]

In trying to use/test some of the utilities, I can't seem to find any man pages. Even --help does not seem to help for at least exifcomment.

[clanmills]

There are no man pages for the sample programs. Exiv2 is open source and the code is the primary documentation! Many of the samples were written for the test suite, or as illustrations on the web-site. Most of the samples provide usage. For example:

1316 rmills@rmillsmbp:~/gnu/github/exiv2/0.27-maintenance/build $ bin/exifcomment 
Usage: bin/exifcomment file
1317 rmills@rmillsmbp:~/gnu/github/exiv2/0.27-maintenance/build $ 

In December 2015, I created the file <exiv2dir>/samples/exiv2samples.1 to provide documentation for those programs. Higher priority matters have blocked progress.

Last year I rewrote our developer documentation as the markdown files README.md and README-CONAN.md. While man pages are much loved by many, their usefulness on Windows in limited. Perhaps the time has come to add another document README-SAMPLES.md to deal with this subject.

Would you like to join Team Exiv2 and work on README-SAMPLES.md?

[tester0077]

I don't think I have the resources and time to commit to becoming a member of the Exiv2 team, though I do have a big interest in Exiv2; this is mainly because I understand it is used as a basis of the metadata support for the genealogy app Gramps. In fact, it was because of this that I got interested in both metadata & eventually Exiv2. FWIW, Gramps is supposed to support image metadata, but for various reasons, this feature is not working in the current release, though a fix is 'in the works', as I am told. Also, initially I was very disappointed in the *.md files because I did not have a good viewer for them and they were very hard to read and make sense of. By now I have found that Notepad++ does an excellent job of displaying as well as, presumably, allowing editing and authoring such files under Windows.

The main issue for me is that, at this stage, I am very unfamiliar with both the purpose, limitations, requirement and usage of these utilities as well as writing/creating md files. With my current workload, I will try to work this in, as I discover more about all of these issues.

Now that I have found this feature/plug-in for NP++, I will try to record my notes as an md file and every so often I will try to pass them on to you, if that is workable.

[clanmills]

OK. If you do anything about this, I'll be pleased to accept your contribution. I'm not going to do anything about this. I'll delete samples/exiv2samples.1 because I'm not going to develop a man page. In fact, one of the reasons I didn't do the work was because I hardly know the man page mark-up codes. A mark-down file takes less effort and works on multiple platforms.

I have to confess to a dislike of mark-down languages. They are loosely defined and code that looks ok on one renderer (I use MacDown on MacOS-X) may present issues on others. Anyway it is what it is.

[D4N]

We could use sphinx or pandoc to convert markdown or reStructured text documents into proper man pages without having to deal with their weird syntax. Someone would still need to write the docs though.

[tester0077]

Yes, the issue of all of those 'standards' (and their associated idiosyncracies & learning curves) are a real pain. It is what got me into this particular predicament in the first place - the frustration of having even commercial software ignoring the metadata standards and dropping or scrambling data already present, using different nomenclature for data they did handle and placing data into inconsistent slot when they did handle it. I will have a go at the samples md file, but again, my knowledge of the language will slow me down, not to mention that I will have to figure out what each sample does and explain it to myself before committing it to 'paper' :)

[tester0077]

@D4N - whether or not Exiv2 has a real 'man' page, makes no difference to me, as long as there is some explanation ;-)

[clanmills]

I'm going to write README-SAMPLES.md and add it to the 0.27.2 release. I will delete exiv2samples.1. The reason I haven't dealt with this is the man page mark-up language.

It shouldn't take very long to put something together. For v0.27.2, let's keep the review of this file to a minimum as something is better than nothing.

@tester0077 If you'd like to "own" this file in future, your contribution will be greatly appreciated.

[tester0077]

@D4N - whether or not Exiv2 has a real 'man' page, makes no difference to me, as long as there is some explanation ;-)

[tester0077]

Re the file exiv2samples.1, I would keep it, if only for the Linux side of things. Still. it only describes Exiv2 itself. I will try to 'own' the exiv2 samples.md.

The answer re mandoc on this link: https://superuser.com/questions/841137/how-to-parse-man-pages-in-windows does give a useful utility to view man pages under windows or to convert them to HTML, which makes it much easier to read :-) exiv2samples.zip

As a start, I was wondering which of the samples exist merely to run regression tests and which can be used to test specific feature of Eviv2?

[clanmills]

I have started drafting README-SAMPLES.md and it classifies the programs as "Test" or "Sample". I know what the programs do and the most efficient way forward to is for me to quickly write some documentation.

I'm in Normandy to run in the D-Day Marathon on Sunday. We're also having a short vacation. I'll get the "first draft" of README-SAMPLES.md ready in the next few days.

All documentation (and C++/build/test code) needs development and maintenance. If you could undertake those chores, that would be wonderful.

exiv2samples.1 is simply a copy of exiv2.1 from December 2015. It was a place-holder and should be ignored. I'm going to delete it.

[tester0077]

Sounds good. I really have no idea what I am getting myself into, but I'll give the 'maintenance' as try ;-)

[tester0077]

All the best for the marathon

[clanmills]

Don't worry. You're not getting into anything much. I'm going to write the document and get it into v0.27.2. We currently have quarterly "dot releases" for v0.27. I review most of our documentation (as time permits) for every release. If you perform the review for README-SAMPLES.md in September and December, that would be one less chore for me.

I hope to issue a PR with the first draft of README-SAMPLES.md in the next day or two. Please remember that this is a new document and I would like to avoid turning this into a week's work.

[tester0077]

Sounds feasible, though my Git skills are less than rudimentary :-( Still, getting to know and use git a bit more is on my todo list (and has been for some time). In the meantime, I have looked over Exiv2 itself and it would seem that it can do most, if not all, of the work I had considered the individual utilities for. As for the document, I quite well understand how these things evolve over several iterations, because issues and potential improvements to wording are generally not appreciated until one gets back to reading it later or a new user, unfamiliar with the whole topic, tries to make sense of it :-) The many command line option for exiv2 still sort of scare me, particularly because all I really needed/wanted was to evaluate libexiv2 so as to get some idea of what I can expect of its cousin pyexiv2/3 (I understand is being) used in Gramps. My basic problem started from my inexperience with the metadata standards and how these were (mis)applied by the several metadata editors I have used over the years to add data to the images for my family tree research. Now I am stuck with several sets of images which may or may not differ from each other (aside from resolution deterioration because of jpg repacking) in which metadata was placed where. Hence I need a way to try and sort this out and hopefully end up with a new and 'improved' set, where all of the metadata I need/want is in the same place and can be viewed in Gramps for confirmation of those important details.

There are a couple of issues I have run up against in the meantime, but I will start new threads for them.

[clanmills]

The PR has been submitted: https://github.com/Exiv2/exiv2/pull/921 And will be integrated into branch 0.27-maintenance and will ship with Exiv2 v0.27.2 It will also be integrated into 'master'.

Let's have no further discussion of this matter until I work on v0.27.3 in September.

[clanmills]

I'm going to close this. README-SAMPLES.md shipped in v0.27.2. It has been updated in the branch 0.27-maintenance when I modified samples/taglist.cpp in support of #987

If you wish to discuss/changes to README-SAMPLES.md, please open a new issue.