[Responding belatedly to a 2019-07-28 review that I missed, as I was looking for 
reviews in Bug#583 instead of in the emacs-devel archive. Sorry about that.]

> the test which describes in detail how Emacs finds the init
> file should be in the section by that name; otherwise it makes no
> sense to have that section in the first place.  The "Init File"
> section should just mention the possible places and refer to that
> other section for the details.

I gave it a shot by installing the first attached patch, which also fixes a few 
other confusions and/or inaccuracies that I spotted.

The documentation also needs to be updated to replace ~/.emacs.d, either with 
~/.config/emacs or with something more general, in places where the 
documentation refers to the value of user-emacs-directory. That should be fairly 
mechanical, and can wait until we have the details nailed down.

>> >  (defconst user-emacs-directory
> ...
> Can this be a defconst?

It's been a defconst ever since it was added to Emacs in 2007. However, the 
manual has always said it's a variable and there are quite a few uses of (setq 
user-emacs-directory ...) in the wild, so I installed the second attached patch 
to make it a defvar.

I think the other issues in the review were addressed earlier.