Abiguity between "package reference" and "recipe reference" in docs
- Dominant language
- C++
- Stars
- 125
- Forks
- 382
- Avg merge
- 22h 39m
- Merged PRs (30d)
- 21
Description
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](https://docs.conan.io/2/reference/conanfile/attributes.html#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](https://docs.conan.io/2/reference/commands/list.html) 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](https://docs.conan.io/1/glossary.html) from the Conan 1 docs, which provides an accurate definition of both terms.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.