loading: work on simplifications (and some corrections) of docs

[vtjnash]

Split off doc changes from #29807, to try to get review (or approval to proceed) from Stefan.

[StefanKarpinski]

Thanks for splitting this out—much easier to review this way!

[vtjnash]

Np, I've been meaning to do this for awhile. I just had originally figured that I would start with working on them together.

[vtjnash]

bump.

[vtjnash]

I'll merge in a few days if no further comments.

[StefanKarpinski]

I will also review this week. If I haven't gotten to it by triage, then you can merge.

[StefanKarpinski]

There are definitely some good clarifications and improvements here. The middle bit that changes the description of how path maps work seems fairly wrong so we should probably drop that part. I've made a number of edit suggestions in places where I felt that the edits were incorrect or unclear.

[StefanKarpinski]

This is not correct: if there's project file then it's always interpreted as a project environment, never as a package directory—that's the litmus test for which one you have.

[StefanKarpinski]

Suggested change

	Package directories provide a simpler environment, but less powerful or controlled, and they exist in two flavors (depending on whether they contain a project file). The set of root packages available is defined simply as the set of files in the directory that "look like" packages. A package `Name` is determined to exist if it finds one of the following files:
	Package directories provide a simpler kind of environment with less control and without the ability to handle name collisions. In a package directory, the set of root packages available is just determined by the subdirectories that "look like" packages. A package `X` is determined to exist in a package directory if it contains one of the following "entry point" files:

[StefanKarpinski]

Perhaps you were thinking above of what dependencies the packages in a package directory can load? If there's a project file in a package in a package directory, its deps section determines what it can load and what each dependency name means. Otherwise, package names are looked up at the top level like in the REPL or Main.

[vtjnash]

I agree, I wanted to motivate the later sections, but the first part of this change doesn't read correctly.

[StefanKarpinski]

I've applied my concrete editing suggestions. I still think switching from X to Name as a placeholder for a package name is confusing and that X is a much more obvious placeholder name. The changes in the middle are not resolved and seem to confuse project environments, package directories and stacked environments. A project environment must have a project file and is a more basic notion than a stacked environment: the load path is in no way involved in any of the behaviors of project environments or package directories. The load path search mechanism only comes in when you combine project environments and package directories by stacking them.

[vtjnash]

Yep, I like most of those suggestions, and have attempted to re-work a few of the remaining areas to be clearer. If GitHub isn't showing a simple diff, looking at the commits on the command line may be nicer: git show --word-diff=color HEAD^

[StefanKarpinski]

Some proposed edits.

[StefanKarpinski]

Some requested changes.

[StefanKarpinski]

I've reviewed this again and I think the changes are generally correct now, so you can merge when you're happy. You may want to take another pass through and edit it further.

[vtjnash]

OR the file packages/Priv/HDKrT—or is the intent to correct the code to match?

[StefanKarpinski]

Yes, I think that should be corrected, but that can be done separately. In the meantime, we should not document something that we don't want people to use. Since these directories are not generally setup manually, I'm quite certain that we can still change this as a "minor change".

[vtjnash]

Suggested change

	Package directories provide a simpler kind of environment without the ability to handle name collisions. In a package directory, the set of top-level packages is the set of subdirectories that "look like" packages. A package `X` is exists in a package directory if the directory contains one of the following "entry point" files:
	Package directories provide a simpler kind of environment with more cumbersome handling of name collisions and less careful reproducibility of versions. In a package directory, the set of top-level packages is the set of subdirectories that "look like" packages. A package `X` is exists in a package directory if the directory contains one of the following "entry point" files:

[StefanKarpinski]

If you're just in a package directory environment, you cannot handle package name collisions at all. In a stacked environment where some of the things in the stack are package directories name collisions are fine but that's a property of the stack, not the package directory so I don't think that's relevant to this description.

I'm guessing that "less careful reproducibility of versions" is referring to the fact that one can't snapshot the exact set of versions in a project file, but I feel like that's incidental: if you check the full contents of a package directory into git and version control it, then it's equally reproducible, it's just less simply to snapshot.

So I stand by my wording of this.

[vtjnash]

Great. I looked though and only had one final change to suggest, if you approve.