Just a little user report intended to suggest areas of improvement in the manual.

While reading the manual, I got to section 11.1 (“Channels”), and reached the statement that the way to merge two channels is to apply the first element of pijul log --channel feature. This confused me because the earlier definition of a channel is “Formally, a channel is a pointer to a set of changes (the state of a channel is a set of changes).”, and I see no particular reason why that set of changes should necessarily contain a single change on which all the other changes depend.

When I tried to use the manual to resolve the question “might I not have to apply multiple different changes in order to merge one channel into another”, I looked at 12.11 (“pijul log” in the Reference section), but this gives essentially no information about the semantics of pijul log.

If I understand correctly how Pijul works, I believe the docs could be improved by:

• being explicit that a channel may have multiple “tips”;
• noting that the “merge one channel into another” operation may require applying multiple changes;
• adding more information about the semantics of pijul log in its reference section.

(I would try and propose a patch, but I am not at all sure I understand the semantics well enough.)