documentation examples

[pennywisdom]

The following is slightly wrong:

https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L1459

Currently says "As a result of this, Alice's layout would have two steps and one inspection." but the example has 3 steps so should be "As a result of this, Alice's layout would have three steps and one inspection."

[pennywisdom]

Furthermore, the explanation below this appears to be copy pasted from the first example and is missing a section:

From this layout file, we can see that Alice is expected to create a foo.py script using vi. The signed link metadata should be done with Alice's key (for simplicity, the same key is used to sign the layout and the first link metadata). After this, Bob is expected to use "tar zcvf ..." to create a tarball, and ship it to Carl. We assume that Carl’s machine already hosts an inspect_tarball.sh script, which will be used to inspect the contents of the tarball.

This needs a sentence explaining that Caroline and Alfred are expected to have run test.py.

Happy to submit a PR is that would be helpful.

[pennywisdom]

Further down in the 3rd example (using VCS and changing to c with compilation step) the example mentions:

Carl must also make sure that the binary contained in the tarball matches the one that Eleanor reported at the end of her step

Yet the inspection in the example layout has expected materials including the source code (src/foo.c) but if this is checking the packaging step, Bob is only adding the binary to the tarball, so the example layout is confusing at it appears to be inspecting for source code that Bob isnt adding. I would have expected the following:

"expected_products": [ ["MATCH", "foo", "WITH", "PRODUCTS", "FROM", "compilation"] ]

[pennywisdom]

Should this: check-out-vcs.[UPSTREAM-DEV1-KEYID-PREFIX].link be checkout-vcs.[UPSTREAM-DEV1-KEYID-PREFIX].link?

(also https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L2020, https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L2020)

https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L1989

Also the name is corresponding to the compilation step but the link metadata name suggests vcs-check-out which is confusing.

Similarly compile-docs suggests the package step as does the verify-vsc-commits metadata link. I was expecting this to correspond to the sublayout step.