The file paths given in the documentation are indeed a bit misleading in my experience, too. I have never noticed before that certain ways of writing the file path actually do work if the InDesign file is in ~/Documents because I never put anything there. Instead I’ve always used relative paths or absolute ones—the latter just needs the right syntax to work.
Now, first of all, it should be said that the very first example given in the Adobe documentation is quite simply stupid: Mac HD:Photos:BillTucker.jpg will never work out of the box, because there is no Photos folder directly in the folder that represents your Mac’s boot drive unless you’ve added one yourself. That’s not how OS X/macOS structures things. The photos folder (which—at least in macOS Sierra—is actually called Pictures) is located in your user folder, i.e., it’s /Users/sambrown/Pictures, assuming your username is sambrown. (When you’re logged in, ~/ is a shortcut way of writing /Users/sambrown/.)
There is, however, a difference between the traditional Mac OS and Unix-based file systems to take into account as well.1. Here’s a brief overview of why this is (or was) such a mess (although that page also uses a nonexistent (Mac HD)/Documents as its example, which should more realistically have been (Mac HD)/Users/sambrown/Documents).
Also note the difference between using a colon and a slash as the directory separator: the colon was standard in Mac OS; the slash is standard in Unix. The directory separator cannot be used in file names… but things are still messy there. Everything in OS X and macOS now displays file hierarchies using slashes (or more graphic elements like the little triangle used now in the Finder) as the directory separator, but if you try to name a file with slashes and colons, you’ll find it’s the colons that it complains about, not the slashes. Oh well.
InDesign is kind of an odd mixture here: it requires the Unix way of traversing file directories, but it doesn’t understand the Unix style of using slashes as file path separators, only colons. And it’s different from both of them in that the path should not begin with a directory separator. So you start with Volumes or Users, not /Volumes or /Users.2
If you have the state.png and BillTucker.jpg images located where your question has them located, you will need the following paths:
Users:sambrown:Pictures:BillTucker.jpg
Users:sambrown:Documents:Games:VL:assets:icons:state.png
At least that works for me, regardless of where the InDesign file is located. If you have files on different drives (whether they’re extra internal or external hard drives or network shares), those have their own separate roots. But since everything in Unix starts with the drive you’re booting from, other drives’ roots appear in a folder inside the current drive; that folder is called /Volumes. So if you have an external drive with all your photos called LotsaPix and you have your Bill Tucker tucked away in a folder called Very important! on that drive, your path would be:
Volumes:LotsaPix:Very important!:BillTucker.jpg
Notes:
Note that Mac OS is not the same as macOS. The former is the old versions of Apple’s operating system up until OS9, before OS X came along; the latter is the rebranded name of versions of OS X starting from Sierra. Mac OS had its own kernel and file system; OS X and macOS are built on a Unix kernel and thus underlyingly have a Unix file system.
The initial slash/directory separator is actually Unix’ way of referring to the root of the file system, which is equivalent to the root of the boot volume, i.e., your computer’s hard drive. Without the initial slash, you’d be looking at a relative path, i.e., Users/sambrown would refer to a folder named sambrown inside a folder named Users inside the current folder. This initial slash was not used in the old Mac OS notation, and InDesign won’t allow it either, but it doesn’t only look in the current folder.
