Abiguity between "package reference" and "recipe reference" in docs

[santhonisz]

Hi there,

I've been reviewing the Conan 2 docs and have just noticed a bit of abiguity between the concepts of "package reference" and "recipe reference".

For example, the Package Reference section documents:

Recipe attributes that can define the main pkg/version@user/channel package reference.

This could be misconstrued as pkg/version@user/channel is a "package reference" - this is not the case as a package reference also includes a package id.

When we look at the documentation for the conan list command it (correctly) refers to the same pattern as a "recipe reference" e.g.

Using it you can list:

• Recipe references (name/version@user/channel).
• Recipe revisions (name/version@user/channel#rrev).
• Package IDs and their configurations (name/version@user/channel#rrev:pkgids).
• Package revisions (name/version@user/channel#rrev:pkgids#prev).

This seems to be quite confusing as it may appear there are two terms for the same thing (even thought they're not the same).

I'm not sure what the best approach would be to making this more concise e.g some or all of the following:

• Rename the Package Reference section to Recipe Reference
• Enhance the Package Reference docs to explain the differences between the package reference and recipe reference.
• Add documentation in the Tutorial section explaining about references
• Add a Glossary e.g. like the Glossary from the Conan 1 docs, which provides an accurate definition of both terms.

[AbrilRBS]

Hi @santhonisz thanks a lot for your suggestion, sorry for the late replay, this repo is checked less frequently than the main one and we missed getting back to you sooner!

I'll be implementing a few of your suggestions to alleviate this problem, thanks a lot for pointing it out