Aperture is a database. The core record in Aperture is the Image. The database is a list of Images, with a whole bunch of data about each Image stored alongside the Image as one record . (You can get some sense of this by clicking Photos at the top of the Library tab of the Inspector and changing to List View.) Apple doesn't like the word "database"; Aperture databases are called "Libraries".
Every Image has a Master. The Master is a file. It is the image-format file that you imported into the Aperture Library. Those files have names. That is refered to as the File Name.
When the User Guide needs to indicate the inclusion of a file name in a field or as a variable, it is written as "filename". This is, I'm pretty sure, now standard practice (e.g.: "Insert the file name in 'filename'.").
The Image is created from a Master + Version pair. The Version is, literally, a text file of proprietary instructions that tells Aperture how to adjust (hence "adjustment" in Aperture, and not "edits") the Master to create the Image. Every Image has a Version (and a Master), but the Version of the first Image created from the Master has no instructions (i.e.: "Don't make any adjustments") and is treated as though it is invisible. The default name of the Version is the file name of the Master. The name of the Version is used as the name of the Image. You can use any name you want for your Versions.
On the Metadata tab of the Inspector you can have shown:
- the Version Name. It is editable.
- the File Name. This is the file name of the Master file. It is the name used by your OS to reference the file. To change it, you must go to "Metadata→Batch Change". You should never change the file name of any Master except through Aperture. It is possible to use Aperture completely and never change a Master's file name.
To see both of the above in one Metadata view, change the Metadata Preset (using the drop-down) to "File Info".
Rest assured this is a confusing topology, and is not spelled out anywhere I have seen. This is just what I understand from using Aperture. (If anyone knows better, please speak up.)
That is nice, comprehensive survey, Kirby. Should be included in the manual.
Perhaps one more small point:
Usually you do not have to worry about file names or version names,
- only on the hopefully rare occasions when you have to track down missing referenced master files and need to know the file name,
- or when you are exporting or sharing to other Apllications.
When you share your images to the Media Browser, you will only see the file names, and you should pick file names that let you identify your images easily. When you export to the web or to other Applications, the file names should better not contain special characters, like "Umlaute", and characters used by the operating system should be avoided too. Some third party programs have difficulties, if the file names are longer then 30 characters, or contain "/", "\", "|", so better avoid those characters.
Thank you so much Kirby (couldn't figure out how to go to List View in Photos.)
Let me see if I have this right.
1. File is short for master file, image is short for master image; each of which is just one aspect of the same composite whole. The viewable image in its first incarnation manifests the master file before adjustments, although still referred to as "version" after adjustments - but in truth it is an adjusted form of the original "version".
2. At the outset, both master and version - adjusted or not, share and keep the same name by default, referred to as file name - which name also identifies the viewable image. But, while a version's name can be changed easily in the Metadata Inspector's Version Name field, this change does not affect the name of the master, or file name, which remains intact.
3. To change the file name - or master's name, go to "Metadata→Batch Change".
4. It is good to keep both version name and file name identical for many technical and practical reasons. Make sure they both show in Metadata View to keep tabs on them.
Kirby, please be kind enough to comment on/amend any of the above to make sure I get it absolutely right. Clarity here is of the essence. And, as you say, it is nowhere available.