Bug 739858 – Deduplicate information on slot operators

• Product: Documentation
• Status: RESOLVED FIXED

[Description Florian Schmaus 2020-09-01 09:29:37 UTC]

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

[Comment 1 Florian Schmaus 2020-09-01 09:35:47 UTC]

Created attachment 657714 [details, diff]
0001-Deduplicate-information-on-slot-operators.patch

[Comment 2 Ulrich Müller 2020-09-01 10:15:56 UTC]

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?

[Comment 3 Larry the Git Cow 2022-02-21 05:22:01 UTC]

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 <[e-mail]>
AuthorDate: 2021-12-23 19:17:28 +0000
Commit:     Sam James <[e-mail]>
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 <[e-mail]>
    Bug: https://bugs.gentoo.org/739858
    Closes: https://github.com/gentoo/devmanual/pull/259
    Signed-off-by: Sam James <[e-mail]>

 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 <[e-mail]>
AuthorDate: 2021-12-23 19:10:36 +0000
Commit:     Sam James <[e-mail]>
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 <[e-mail]>
    Bug: https://bugs.gentoo.org/739858
    Signed-off-by: Sam James <[e-mail]>

 general-concepts/dependencies/text.xml | 36 ++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 13 deletions(-)

[Comment 4 Larry the Git Cow 2022-06-24 09:14:47 UTC]

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 <[e-mail]>
AuthorDate: 2021-12-23 19:19:10 +0000
Commit:     Ulrich Müller <[e-mail]>
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 <[e-mail]>
    Bug: https://bugs.gentoo.org/739858
    [Commits squashed; small fixes according to style guide.]
    Signed-off-by: Ulrich Müller <[e-mail]>

 general-concepts/dependencies/text.xml | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

[Comment 5 Ulrich Müller 2022-06-24 09:16:19 UTC]

Anything left to do here? Please reopen if there is.