docs: add explanation to sort primop

[hsjobeki]

Motivation

Reading through the docs of sort. I found them a bit hard to understand.
I think the code examples could benefit from some prose that explains them upfront.
It is non-obvious how to interpret the code. especially -> does this mean nix's implication operator?

Context

---

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[Ericson2314]

Suggested change

	If a is NOT less than b; b is NOT less then a; a and b are equal according to the comparator.
	If b is equal to c then it follows that a is equal to c
	First, let us define *equivalence* with respect to some comparator:
	If x is *not* less than y and x is *not* less then y, then x and x are equivalent according to the comparator.
	Having done that, now we can define the transitivity of this equivalence:
	If a is equivalent to b and b is equivalent to c, then it follows that a is equivalent to c,

I think using different variables here make the prose much less confusing. Your version IMO made the mistake of extending the a: b: ... scope too far: the second a and b are not the same.

[hsjobeki]

Okay, i can make the sentence more correct in that regard. But my other point was to avoid the term transitivity in its own definition. Because at that point i (or the reader) doesn't understand what it means.

I also wonder if we need to define the eq function, when the point is to explain the concept, we shouldn't over formalize, but make sure the required property is understood by keeping the explanation simple.

[hsjobeki]

Sentence updated. Can you check again ?

[xokdvium]

It is non-obvious how to interpret the code. especially -> does this mean nix's implication operator?

The code is valid nix and can be e.g. copied into the repl.

[hsjobeki]

@xokdvium @Ericson2314 updated the PR. Can you check again?

[hsjobeki]

It is non-obvious how to interpret the code. especially -> does this mean nix's implication operator?

The code is valid nix and can be e.g. copied into the repl.

Code alone isn’t enough. clear prose is needed to explain intent and prevent misinterpretation.
Readers shouldn’t be forced to test things in the REPL to figure out the semantics. Nor rely on prior knowledge of the -> operator