The devmanual states the semantic of slot operators in two places: - ebuild-writing/eapi - general-concepts/dependencies Ideally it should only provide the information once to avoid any inconsistencies and to increase maintainability. Reproducible: Always
Created attachment 657714 [details, diff] 0001-Deduplicate-information-on-slot-operators.patch
The EAPI chapter is special insofar as its entries for EAPI n will be removed when all EAPIs older than n are gone from the tree. If they're not yet mentioned elsewhere, then they will be added to the appropriate sections. I'd rather not touch the EAPI 5 section at this point, because the whole section is already slated removal. OTOH, we can of course improve the wording of general-concepts/dependencies if necessary. As for deduplicating, I see that you have preferred the wording from ebuild-writing/eapi. This had in turn been (mostly) taken from PMS: https://projects.gentoo.org/pms/7/pms.html#x1-780008.2.6.3 Now PMS as a specification leans on the side of a very formal writing style, while the devmanual tends to use a more colloquial language. Indeed, tetromino's commit that added the existing wording says in its commit message: "Rephrase [...] to be a bit more readable and a bit less PMS-like." https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9c3bba54f96fc96c0f3e4929b3bc84a3d84d0aa9 Which means that the informal language in general-concepts/dependencies is intentional. We should not revert that. So, could you rework your patch, considering the above points?
The bug has been referenced in the following commit(s): https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5ef9e1d93aad7538c0c30cd076e956c2947ef4d8 commit 5ef9e1d93aad7538c0c30cd076e956c2947ef4d8 Author: Florian Schmaus <flow@gentoo.org> AuthorDate: 2021-12-23 19:17:28 +0000 Commit: Sam James <sam@gentoo.org> CommitDate: 2022-02-21 05:21:44 +0000 general-concepts/dependencies: improve explaination of slot operators The section previously had hard to parse sentences like "[…] and that your package should be rebuilt if the version best matching the runtime dependency is updated to a version with a different slot or subslot" for the := operator. This commit attempts to improve the readability of the section. The change superseeds my proposed change in bug #739858. Thanks to Sam James for reviewing this. :) Signed-off-by: Florian Schmaus <flow@gentoo.org> Bug: https://bugs.gentoo.org/739858 Closes: https://github.com/gentoo/devmanual/pull/259 Signed-off-by: Sam James <sam@gentoo.org> general-concepts/dependencies/text.xml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a4828a6aeeae3b413ecce168b427122cc693f887 commit a4828a6aeeae3b413ecce168b427122cc693f887 Author: Florian Schmaus <flow@gentoo.org> AuthorDate: 2021-12-23 19:10:36 +0000 Commit: Sam James <sam@gentoo.org> CommitDate: 2022-02-21 05:21:40 +0000 general-concepts/dependencies: indent xml for better raw readability This is scavenged from my proposed change for bug #739858. Signed-off-by: Florian Schmaus <flow@gentoo.org> Bug: https://bugs.gentoo.org/739858 Signed-off-by: Sam James <sam@gentoo.org> general-concepts/dependencies/text.xml | 36 ++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-)
The bug has been referenced in the following commit(s): https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6ea40822c59d94513f80f8a6d14c125c8e9aec0c commit 6ea40822c59d94513f80f8a6d14c125c8e9aec0c Author: Florian Schmaus <flow@gentoo.org> AuthorDate: 2021-12-23 19:19:10 +0000 Commit: Ulrich Müller <ulm@gentoo.org> CommitDate: 2022-06-24 09:12:27 +0000 general-concepts/dependencies: add paragraph explaining example Add a small paragraph explaining the existing slot-operator example. This is scavenged from my proposed change for bug #739858. Signed-off-by: Florian Schmaus <flow@gentoo.org> Bug: https://bugs.gentoo.org/739858 [Commits squashed; small fixes according to style guide.] Signed-off-by: Ulrich Müller <ulm@gentoo.org> general-concepts/dependencies/text.xml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+)
Anything left to do here? Please reopen if there is.
