Update exiv2 program and manpage #1872
Conversation
Also add URL reference for README-SAMPLES.md .
+ Change command line examples to use bold. + Change flags to use bold and parameters to use italics.
+ Reformat text and add to lens example + Add reference to SEE ALSO section
+ Replace short options with long form, to make reading easier + Rename `--modify` parameter from `file` to `cmdfile` to prevent confusion with the main parameter called `file`
+ Update text + Add `thumbnail` column to table and fix formatting
+ Update formatting for consistency + Correct minor errors and missing data
Codecov Report
@@ Coverage Diff @@
## main #1872 +/- ##
==========================================
+ Coverage 60.51% 60.87% +0.35%
==========================================
Files 96 96
Lines 18845 19041 +196
Branches 9469 9727 +258
==========================================
+ Hits 11404 11591 +187
+ Misses 5155 5138 -17
- Partials 2286 2312 +26
Continue to review full report at Codecov.
|
|
I have already spotted some minor corrections to this, which I intend to fix. |
Changes: + Add long option format in text, as this is easier to understand + Indent command line output + Add bold for options and underline for parameters + Add text and examples + http to https + Update SEE ALSO references
Changes: + Fix filename in example + Indent command line output + Update text
Changes: + Update text + Update formatting for consistency
The long option version of `-e` was missing.
Changes: + Fix :basename: and GPS examples + Add new examples and update text + Format closer to manpage standard
There was a problem hiding this comment.
@postscript-dev Thanks for working on this. It's very helpful to look at all this stuff carefully as I've never really totally understood the exiv2 command-line syntax. It's very likely that in my lack of understanding, I've damaged it over the years!
Good idea to add -e/--extract to the longs in src/exiv2.
I think the syntax of the exiv2 is $ exiv2 verb [option]+ path+. As ex is a verb, the command $ exiv2 ex --extract -e foo.jpg will create the .exv with the Exif metadata. I must admit that I always use the syntax -ee for that as is $ exiv2 -ee --force --verbose foo.jpg
|
Yes, you are quite right. I will make the change. I haven't been using 'action' much. It has been interesting looking at the exiv2 program, as before this I only used |
|
Robin, this morning I was thinking about the use of 'action' and decided to run the example you gave above. I added The reason for the output is during parsing, If I move the I don't usually use the 'action' command, as unless you accept the default for the action (e.g. |
|
Yes. I've never really understood the exiv2 command-line. Like you, I seldom use the action on the command-line. Mostly, you don't need to as It's selected by magic! When I use extract, I normally say something like: 544 rmills@rmillsm1:~/Desktop/Fireplace $ exiv2 -ee --force --verbose ~/Stonehenge.jpg
File 1/1: /Users/rmills/Stonehenge.jpg
Writing Exif data from /Users/rmills/Stonehenge.jpg to /Users/rmills/Stonehenge.exv
545 rmills@rmillsm1:~/Desktop/Fireplace $ I don't know how it knows to use the 556 rmills@rmillsm1:~/gnu/github/exiv2/0.27-maintenance $ grep '^namespace Action' -A 4 src/actions.hpp
namespace Action {
//! Enumerates all tasks
enum TaskType { none, adjust, print, rename, erase, extract, insert,
modify, fixiso, fixcom };
557 rmills@rmillsm1:~/gnu/github/exiv2/0.27-maintenance $ I never criticise Andreas because he did a wonderful job. Occasionally, he use patterns from Design Patterns when easier solutions exist. So, he subdivided the command-line into different tasks. By guessing/deducing the 'action' from the options instead of requiring it on every command, there could be ambiguity and weirdness. I think the action pattern is used by commands such as I purchased a PDF of "Design Patterns" for $10. Good Value. Essential book for every Software Engineer. It's illegal for me to share my copy with you. You can get the Kindle version from Amazon for $10 or so. Design Patterns: |
Robin, there's no criticism or yourself or Andreas, Exiv2 is of a high standard. I am impressed by the features of the Exiv2 library and sample program. Nobody knows every part of the project.
I didn't know this either, but I did a bit of research that makes me think that the first hyphen option that is processed sets the 'action'. The processing happens here. Interestingly, it is possible for a small number of options to combine 'action' choices. e.g. will do both the modify and extract. In this example, the order of
The git analogy is very helpful in understanding this. I don't know if a there is a better implementation, but I wasn't thinking of changing the mechanism. It is hard to know in advance, if an approach will work, I will add some extra text to explain the purpose and also plan to better explain the default settings used by each 'action'. |
|
Yes. You've got the idea about the action. It kind of magics its way into existence. Try to avoid damaging the mechanism because exiv2 has been around for a long time and users will have scripts that work. If you find/fix a bug in the command-line parsing, you could break their scripts! So, keep focus on the man page and try to avoid code changes which could disturb the beast. Better documentation is good for everybody. It might be possible to handle several actions on a single command and those "tasks" are invoked in turn on the file list. The syntax is: 583 rmills@rmillsm1:~/gnu/github/exiv2/0.27-maintenance $ exiv2
exiv2: An action must be specified
exiv2: At least one file is required
Usage: exiv2 [ options ] [ action ] file ...
Manipulate the Exif metadata of images.
584 rmills@rmillsm1:~/gnu/github/exiv2/0.27-maintenance $ Maybe that syntax is a simplification. It might that you can daisy-chain actions something like this: Usage: exiv2 [ options ] [ action ] options [action] file ...My comments about Andreas are only to say that it's possible that command-line processing using a pattern from Design Patterns is overkill and makes the code less flexible and harder to understand. My greatest praise for Andreas is his use of the Visitor Pattern to deal with Tiff. One of the smartest (and least obvious) ideas I have ever encountered. Exif metadata is an embedded Tiff. Regrettably IPTC, XMP and ICC parsing was not written by Andreas and does not use the visitor pattern. Mea culpa. I added the ICC code. I think Gilles added IPTC and Brad added XMP. In my book I have used the Visitor Pattern to handle all metadata (Exif, IPTC, XMP and ICC). Like exiv2, I have used the Factory Pattern to deal with different file formats and the IO Pattern for I/O. In my book, my |
There are three that I think need attention.
1 and 2 are easy to fix, I will take a look at 3 tomorrow. |
|
@postscript-dev As 1 and 2 are easy to fix, I won't comment. There was a discussion recently concerning IPTC. It might be relevant #1395. I see that conversation was with you, so you're aware! |
Changes: + Add missing tag groups in Exif list and reformat + Update text explaining Exiv2 types + Add text explaining tag groups, multiple elements and date/time formats + Format closer to manpage standard
Add references to new sections.
There was a problem hiding this comment.
@postscript-dev Thanks for doing all this stuff.
We had a day out today and a euphonium lesson this evening. I'm too tired tonight to write about the TagNames on the Wiki and will do it on Friday. I'll also have review your progress with the man page tomorrow. Let's think about getting this submitted. We can continue forever to tweak and change. It's usually better to submit and work on other matters for a while.
The change to IfdId that I have discussed with the Krita user is non-trivial. It's probably not difficult, however it's surgery to the TiffVisitor which is the beating heart of Exiv2. Steady hands are needed.
|
I'm happy with the substance of what you've added to the man page. I'm uneasy about the "wide" strings. They don't look good when printed in PDF. We should consider replacing the man page with a document Exiv2.md. The man page can be reduced to a very short description and and link to Exiv2.md on exiv2.org and github.com. I am attaching the drawing concerning Exif tags, so I can reference the drawing in the Wiki. The graphics files are here: svn://dev.exiv2.org/svn/team/rmills/graphics/wiki.graffle
The following drawing is in my book. The graphics are stored at: svn://dev.exiv2.org/svn/team/book/book.graffle |
|
The last part I am working on is the COMMANDS section. When that is pushed, I will convert the file to markdown. |
|
@postscript-dev That will be great, Peter. The man page format is arcane and of no use to Windows users. Mark-down is a 21st format and can provide links to other web resources. Please note: I don't think much of mark-down, however it's better that the awful alternatives. I intend to add more information concerning IPTC and XMP to my drawing in the next few days. |
|
@postscript-dev Today, I did some editing on https://github.com/Exiv2/exiv2/wiki/Tag-Name-Syntax Iptc is very easy to understand. Exif is a little more complex with up to four levels of hierarchy in the Exif.Group.Tag syntax. I "kind of" understand Xmp. It's Xmp.NameSpace.Key. You get available name spaces with the command: $ exiv2 --verbose --version --grep xmlns
...
xmlns=xmp:http://ns.adobe.com/xap/1.0/
xmlns=dc:http://purl.org/dc/elements/1.1/
...You can add new namespaces using As far as the man-page is concerned, all you need to know is that the syntax Exif.Group.Key applies. The Key is Regions/mwg-rs:RegionList[1]/mwg-rs:Area/stArea:x and understood by the Adobe XMPsdk. Exiv2 relays this concoction to/from XMPsdk without understanding what it means. If it's invalid, XMPsdk will throw. |
|
Thanks for updating the wiki. Key = Family.Group.Tagname From the wiki:
I think that While working on the man page, I found that it explicitly uses Exif tags, IPTC datasets and XMP properties but I think that this is confusing to the average person. I don't know myself what the differences, if any, are. I was thinking of renaming the terms Exif, IPTC and XMP tags which seems clearer.
Thanks for pointing this out, I have added it to the man page. Another thing that I hadn't thought about, was the extra syntax that XMP keys allow. I will add a note about this too. I have learned a huge amount about exiv2 while working on the man page. |
|
Key. Yes, that's correct. My bad. I'll update the page now. I did notice that it's very awkward to talk about Tag and TagName when they are different. Right, by say "Key" we are discussing the third element of the TagName tuple. And then Tag is simply an appreviation for TagName. That's good. Andreas is a smart guy. His English is better than mine and he's a native German speaker (Swiss). |
|
I've updated the page. I'm sure I'll be editing that a few more times before we are finished on this! In the brief discussion of XMP Tags, I did not change the word "Namespace". If you believe it's more consistent to say "prefix", you are welcome to change the page. At least we're making an effort to document and explain this stuff. For most of my 13 years working on Exiv2, the tag names were an undocumented mystery! Sadly, it's very common for clever engineers to fail to document their creations. Explaining their genius to mortals is beneath them. When this happens, the Technical Writer has an impossible job. I suspect that happenedd with the Adobe XMPsdk. The documentation, API and cmake build scripts are close to incomprehensible. However, the code is well written, has stood the test of time and works very well. |
|
BTW, I strongly discourage you from documenting XMP "Key" values. Delegate it to Adobe. It's not the responsibility of Exiv2 to explain what happens in the XMPsdk. |
|
I was only thinking of mentioning that the XMP key syntax can be extended and then linking to Adobe. As long as people know that this format exists, then they can look it up. |
|
I agree that it's confusing that Exif discusses tags, IPTC discusses datasets and XMP discusses properties. The words tag, dataset and property refer back to the specification of the different standards. Exiv2 provides the user with a uniform way in which to experience the metadata from different standards. Confusing? It's attempting to make it less confusing! |
|
Luckily there are people like both of you that work in making the documentation better. I can just say that I really appreciate your efforts ❤️ |
Update the `COMMANDS` and `EXIV2 GROUPS, TYPES AND VALUES` sections, including any related sections. Changes: + Add new examples and update text + Fix spelling errors
Original manpage file text is replaced with a note pointing to the Exiv2 website.
Changes: + Update BMFF types in FILE TYPES section + Add text in FILE TYPES explaining formats + Change IPTC datasets and XMP properties to IPTC and XMP tags + Fix text and formatting
Changes: + Swap `EXIV2 GROUPS, TYPES AND VALUES` and `MODIFY` COMMANDS` + Move `Exiv2 key syntax` to top of section + Swap `AUTHORS` and `SEE ALSO` sections + Fix text and formatting + Add `PREVIEW IMAGES AND THUMBNAILS`, `ICC PROFILES` and `IMAGE COMMENTS` sections + Update FILE TABLE + Renamed "raw" XMP metadata to "raw" metadata to prevent confusion with "raw" XMP
postscript-dev
changed the title
|
Thanks @piponazo. Unless there are any corrections, I think that this is now finished. The only part that I haven't fully tested is the FILE TABLE section. I added a couple of things, but this could do with more work. Now that the manpage is in markdown, whoever is updating the website, will need to make a change. There is a script that converts manpage to HTML which will need to be updated. |
|
@postscript-dev: it looks like some tests are failing. I'm on a phone right now, so I can't quite tell what's wrong, but most likely we have test that is checking the "usage" message. |
|
Thanks, I will look into this now. |
|
The CIFuzz failure is unrelated. If you could approve #1900 then that should get resolved. |
exiv2 program changes:
--helpand usage--extractlong option for-eManpage changes: