# Notes on the Pijul Manual
- pijul.org/manual really should be up-to-date.
  I remember it being grossly out-of-date just days ago, but it seems to be up-to-date now.
  ...Now it seems old again.
  Guess: I confused myself several times by looking at both the online version and a locally rendered one.
- Weak proposal: (at most a) single sentence per line?
  Not sure how beneficial this would be, given Pijul.
  See pijul/manual#57: there seems to be at least a little demand for shorter lines in the source.
- It would be nice if command sequence examples in the manual could be automatically tested.
- note to self: go over cellarroot/b/discussions/2 again
- note to self: read through the pijul/manual Discussions
- Might be nice to have pijul/pijul be tagged regularly, and to have the manual display which version (i.e. tag) it applies to.
- Huh, no links to [jneem.github.io](https://jneem.github.io/) anywhere.
  That blog series was good!
  See Parts 1–5 at [jneem.github.io/archive](https://jneem.github.io/archive/)
- Not all source material ends up rendered 😱
  Example: `format.md`
  ...Oh, it's commented out in `SUMMARY.md`.
- `pijul.org/manual` should not be available, or redirect to `pijul.org/manual/` (with terminal `/`)
- What are those `.md.NT22VBIWNZHOC` files in the Manual repo?
- Missing sections:
  - contents of a change (high level)
  - internal structure of a change (lower level)
  - contents of a repo (high level)
  - internal structure of a repo (lower level)
  - string representation of conflicts
## By section
### Why Pijul?
Present text is not compelling for either
- people new to VCS
- git users
Perhaps separate chapters/texts is the way to go.
```diff
-/stitched together based on their contents rather than on the edits that took place/
+_stitched together based on their contents rather than on the edits that took place_
```
### Installing
Needs shortening.
Include Windows build instructions.
### Getting started
Move up paragraph on identities.
`pijul key generate` doesn't exist anymore.
We need an actual tutorial that includes not only recording, but also other operations.
Note to self: peruse Zulip & Discourse for prior art. (see "phenomenology" on Discourse)
First-Time Setup: check that this section is up-to-date/necessary.
Clarify the roles of `author.*`.
Authors seem invisible by default. Huh?
"Definitions" needs fleshing out.
Give overview of a repo's structure.
Indicate where config & working copy & changes & tree & pristine &c. live.
"...which can happen even by email exclusively" -- really? Show this functionality.
Provide link to the Nest.
Perhaps note that is has the same purpose as GitHub for git.
### Working with others
SSH: check whether prior authentication/proof is required.
Missing:
- how to add a remote
### Pijul identities
Aspiration:
I know next to nothing about SSH.
This chapter should be understandable to me,
and also to the even less knowledgeable.
( perhaps more applicable to: chapter on the Nest )
When/how are name & e-mail displayed?
( Confusion borne from below mentioned UI bug.
  Might still merit elaboration though. )
How to share the id--name mapping?
( suspected answer: `prove` )
How to prevent pushing patches made using the wrong identity?
( related: how to recover from pushing wrong identity? )
> On success, the location of the generated identity will be displayed to the user (...).
👆 It isn't.
What does ``Linking identity `default` with @`` mean?
Pijul UI bug: `pijul identity new` suggests a display name, but does not allow using it.
On Windows, at least.
Why would I want to encrypt/expire my identities?
What does linking to a remote mean?
Document `pijul id` abbreviation of `pijul identity`.
Also document other abbreviations, if any.
> Patches submitted before proving your identity will show only the key as the author, for example 44hhwRgXtFEeAt6m3KooFCQ5VowqLoQ8YkBP93UZqm9R.
👆 Don't you mean that before proving only keys are displayed, but after proving also/instead the name is displayed?
I'd be surprised by a distinction between pre-proof and post-proof patches.
What exactly _is_ a Pijul identity?
I have a vague memory of a public/private key pair.
How is impersonation avoided?
### Configuration
~~What does 'global' vs. otherwise mean? Describe.~~
(probably mostly for non-programmers)
What is the function of `author.name` &c?
Is `name` actually the local name of the default (to be) identity?
What are `full_name` and `email` doing here?
`key_path`: flesh out a bit more as well.
Table:
Link to `Choice` is fine, but the destination of `Author` does not explain what the available options for the `author` field are.
Should it be an identity key, or a display name, or..?
Same for `Template`.
`Kinds` is not entirely explicit either, but deducible/guessable.
...Actually, the example right below the table explains a lot.
Maybe order could or should be tweaked? Not sure.
Obvious though TOML might be, it may well be new to many people.
Link to `keys.html` is broken.
It'd be nice have all links be automatically checked every once in a while.
What would be some example uses of templates?
Huh, `config.toml` in the one place, bare `config` in the other.
```diff
-have a higher precedence than
+take precedence over
 (or some such)
```
```diff
-If
+Whether
```
Remotes: could use some elaboration.
Also: the linked `reference/remote.html` is empty.
...It isn't empty anymore 😕
Hooks: could use elaboration.
What are some example uses? What are possibilities, what are the limits?
"standard glob syntax": we should explain it anyway, or point to a specification.
### Conflicts
```diff
-occurs
+occur
```
```diff
-which comes first
+which should come first
```
This text speaks of adding/removing 'lines', but Pijul works on bytes, no?
If the talk of lines is meant as a 'simplification' for humans, we should say so or try to avoid it, lest we encourage misunderstanding.
Note to self: check that the listed possibilities are truly exhaustive (as suggested by the text).
Could use a worked example of dealing with conflicts.
how to read conflict markers
how to fix conflicts
`unrecord` vs. `unapply`.
Why does the latter not seem to exist?
We need a good conceptual overview of Pijul somewhere.
For a start, see [jneem.github.io](https://jneem.github.io/)
### Theory
The LaTeX doesn't render.
The SVGs do not contrast with the light themes.
This text's style might be too mathematical for many readers.
I'll skip going over it in detail for now.
### Diff algorithm
~~Drop this chapter, or relegate it to an appendix.~~
This might be useful to understand, actually.
Try for example
```powershell
pijul init reprorepo ; cd reprorepo
echo ".`n.`n." > file  # `n = newline
pijul add file
pijul record --all --message "base"
pijul fork a ; pijul fork b
pijul channel switch a
echo "a`n.`n." > file ; pijul record --all --message "a"
pijul channel switch b
echo ".`nb`n." > file ; pijul record --all --message "b"
pijul channel switch main
pijul pull . --all --from-channel a
pijul pull . --all --from-channel b
cat file
# expected:  ab.  (or a conflict)
# actual:    a.b.
```
👆 the final line is important:
including it leads to the unexpected behavior,
excluding it produces a conflict.
### The Nest
Add note about `.com` vs. `.org`.
#### Creating an account
out of date:
- .org vs .com
- via GitHub/Google/Twitter no longer possible
#### Uploading public keys
I do not know how SSH works, in general, and this section does not enlighten me.
Let's add a very quick getting-started guide.
Note to self: reexamine this section again in the future.
link to `keys.html` is broken.
#### Creating repositories
> (no need to clone it, patches can be pushed directly)
Indeed, currently cloning right after creating results in 404.
See [this Zulip thread](https://pijul.zulipchat.com/#narrow/stream/270757-Nest/topic/404.20when.20cloning.20an.20empty.20repo).
#### Contributing to a project
How to _remove_ patches from a discussion?
To push to a discussion is _just_ to push to a channel.
Point this out.
### Workflows
I expect a well-developed _Workflows_ chapter to be important for Pijul adoption.
Zulip has already produced a number of _how do I do X_ scenarios.
Use these for inspiration for more sections.
TODO: take stock
Also on Discourse: [Phenomenological Pijul (or Pijul from the outside)](https://discourse.pijul.org/t/phenomenological-pijul-or-pijul-from-the-outside/906).
TODO: study the above, and also browse some more
We're missing the most basic scenarios. (How to: record, amend, push, ...)
They might not seem terribly interesting, but I still think it's good to have them around.
( There will be overlap with the tutorial, but that's fine. )
Other missing scenarios:
- the one(s) that the initial, "semi-empty", root-introducing patch is meant to help with.
  Submodules.
#### Working with channels
My understanding:
Channels and branches are wholly different things.
'The' difference is not at all subtle.
It's just that these two different tools can be used to solve some of the same problems.
Question: why channels and not simply separate repos?
Suspected answer: for efficiency only.
"Formally" -- does the non-mathematician know how to interpret this?
A channel is not just _any_ set of changes, right?
It'll always contain all transitive dependencies, no?
> \[...] (a bit like branches in Git).
>
> \[...]
>
> However, channels are different from Git branches, and do not serve the same purpose.
Like branches, but unlike branches.
In what ways?
(And implicitly: why mention it?)
> In Pijul, independent changes commute, which means that in many cases where branches are used in Git, there is no need to create a channel in Pijul.
As evidenced by the many questions about branches and channels, there is a need for more clarity on this point.
We should probably not (only) tell, but also show.
> The identity of a change doesn’t depend on the branch it is on, \[...]
What does 'branch' mean here? Shouldn't it be 'channel'?
> \[...] or in other words, rebase and merge are the same operation in Pijul.
I fear this only makes sense if you understood already.
> This implies that conflicts do not mysteriously come back after you solve them (which is what git rerere is for).
This sentence feels out of place.
If it shouldn't feel out of place, then consider showing in addition to telling.
Many seem unfamiliar with this problem, or to feel it isn't a big deal.
Few know about `rerere`.
> Also, conflicts are between changes, \[...]
This, too, seems like it only makes sense if you understood already.
Evidence: persistent confusion on Zulip, and probably also Discourse and elsewhere.
Should the comparison with Git be moved to a separate chapter?
I feel it distracts a bit.
By the way: see [jvns.ca/#git](https://jvns.ca/#git) for inspiration -- perspectives on 'branches' in particular.
Also:
[What helps people get comfortable on the command line?](https://jvns.ca/blog/2023/08/08/what-helps-people-get-comfortable-on-the-command-line-/)
And while we're at it:
[Patterns in confusing explanations](https://jvns.ca/blog/confusing-explanations/)
> What you can do with channels
I expected a tutorial or demonstrations, but what follows is more of a reference.
We need tutorials as well.
Scenarios, problem statements + solutions.
```diff
-\$
+$
 (in many places)
```
#### Recording, splitting and combining changes
Reminder: there should be a thorough discussion of `log` order somewhere in the manual.
Reminder: somewhere in the manual, lay out exactly which info ends up in the patch.
```diff
-[[author]]
+[[authors]]
```
What is the role of `[[authors]]`?
What happens to these entries?
What if they are inconsistent, or contain typos?
How to add dependencies?
How to edit the implicitly 'staged' diff?
Only deleting portions of it might not be enough.
`pijul reset` is automatically hyphenated but probably shouldn't be.
( Not unique to this string; I just noticed it here. )
> Whatever you remove, the files themselves will still look the same as before the amend, only the record will have changed.
Explicitly note what happens to the hunks that you remove.
Also: what happens to the old change? Will it continue existing, or disappear?
> \[...], but not the content of the change itself.
It has not yet been noted explicitly that this is what `reset` (I expect) is for.
### Reference
It might be useful to show which `pijul` version/build this material was generated from.
~~`generate-reference` seems broken.~~
It's just lacking a manual.
Haven't figured it out yet. Don't know bash...
...Alright, it is outdated: `SUBCOMMANDS:` has become `Commands:`.
Other breakage: (`SUMMARY.md`)
```diff
-    - [pijul ls](./reference/ls.md)
-    - [pijul mv](./reference/mv.md)
+    - [pijul list](./reference/list.md)
+    - [pijul move](./reference/move.md)
```
Pages not listed in `SUMMARY.md`: completion identity tag client dependents.
't Would be nice if mismatch between `SUMMARY.md` and `src/reference` were automatically detected.