Add example for downloading foo/bar/baz target files

[erickt]

This extends section 5.5.2 to include examples on how a client should download artifacts from a subdirectory. It uses the approach that python-tuf and go-tuf use, where downloading a target path like path/to/file.ext when consistent snapshots are enabled are fetched from path/to/$HASH.file.ext.

[lukpueh]

Thanks for the PR, @erickt! TBH I'm not quite sure about this addition.

The paragraph specifically talks about filenames, and how consistent snapshots affect them. I don't think it needs to talk about the full TARGETPATH. (It doesn't talk about the base URL of the repository either.)

If we do decide to accept this addition, we should change occurrences of filename (case-sensitive) with path or relative path, because e.g. PATH/TO/FILENAME.EXT is not a filename.

Maybe others can weigh in? (cc @mnm678, @trishankatdatadog, @JustinCappos)

Independently, I agree with your request in #63 to clarify/standardize TARGETPATH, and I have proposed a fix in #67.

[mnm678]

I agree with @lukpueh. This paragraph is referring just to the file, not the base url and path used to find the file. There might be a place to clarify how to download target files from a subdirectory elsewhere in the spec (maybe 3.1.1 or 4.5).

[lukpueh]

@trishankatdatadog, do you disagree with the concerns I and @mnm678 raised? Do you think we should merge the PR as is?

[trishankatdatadog]

LGTM, I already approved last week

[lukpueh]

As discussed in the meeting yesterday, this section in the spec is not the right place for this example. I agree with @mnm678 that sections 3.1.1 or 4.5 are better suited.

[lukpueh]

As per tuf-spec.md#L408-L413

3.1.1 Target files
The filenames and the directory structure of target files available from
a repository are not specified by the framework. The names of these files
and directories are completely at the discretion of the application using
the framework.

I wonder if that paragraph deliberately ignores the fact that TUF does indeed specify filenames of target files, albeit only if "consistent snapshots" are used.

If we add @erickt's example to 3.1.1, we have to briefly mention consistent snapshots. I think it's worth it. What do others think?

[trishankatdatadog]

We should resolve this PR, but someone needs to take over ownership

Cc @joshuagl @mnm678

[joshuagl]

I'll take a stab at this next week.