Suggested addition to documentation

Started by dd-b, October 23, 2020, 07:53:42 PM

Previous topic - Next topic

dd-b

For whatever reason, I had trouble really understanding (I mean, remembering it consistently when it mattered :-) ) the (to my mind) very weird way "GetValue()", "SetNewValue()", and "GetNewValue()" interact. Despite it being plainly laid out in the documentation. For some reason it seems such a bizarre way to do things that it tool a long time for my mind to accept that the doc *really meant that*.  ("New value" can be simple English describing a value that has been recently set; it's being used in the documentation as a special term defined for this software, indicating that the new values are sequestered from the original values, and are not returned by GetValue() calls.)

It would have been helpful if that had been pointed out. And then if GetInfo() for example pointed out that it returned the values as originally read and did not show values set with SetNewValue() in the current session.

None of this behavior is in any way contrary to what the documentation says happens! But I found it very easy to read the documentation and remain confused on how it worked; a few more direct pointers would have saved me most of a day I expect!

Phil Harvey

Thanks for the suggestion.  I'll see what I can do.

Does something along these lines make sense?:

ExifTool queues all new values that you assign via SetNewValue, then applies them to any number of files through one or more calls to WriteInfo.  These queued value may be accessed through GetNewValue.  Completely separately, you may be reading existing metadata from files via ExtractInfo (or ImageInfo) that may be accessed through GetInfo or GetValue.

In reality, GetNewValue and GetValue are really unnecessary functions.  In most cases you already know what new value you have set (so GetNewValue isn't necessary), and GetInfo (or ImageInfo) should normally be used instead of GetValue.

- Phil
...where DIR is the name of a directory/folder containing the images.  On Mac/Linux/PowerShell, use single quotes (') instead of double quotes (") around arguments containing a dollar sign ($).

dd-b

Yes! At least, I'd like to hope that if I'd read that, I would have understood how it worked much sooner.  (Always hard to be really sure after the fact!)

At the very least, reading that later, after I'd figured it out, I'd be saying "How the heck did I not understand that? I'm an idiot!" :-)

Phil Harvey

OK, thanks.  I've settled on adding this as the second paragraph in the WriteInfo description:

     ExifTool queues all new values that are assigned via calls to
    "SetNewValue", then applies them to any number of files through one or
    more calls to "WriteInfo". These queued values may be accessed through
    "GetNewValue", and are completely separate from metadata extracted from
    files via "ExtractInfo" or "ImageInfo" and accessed through "GetInfo" or
    "GetValue".


- Phil
...where DIR is the name of a directory/folder containing the images.  On Mac/Linux/PowerShell, use single quotes (') instead of double quotes (") around arguments containing a dollar sign ($).