conan-io / conan-io/docs

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

Open
#3,316 1 comment 1 reaction 1 assignee Claimed by @AbrilRBS View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.