I got about 25% through this PR.

Thanks @richsalz and @levitte for pointing out various mistakes;
I fixed all of them and some further minor issues I found in the course of doing that.

Did you run make md-nits on your machine before creating this PR?

Oh, never heard of that.
So I've installed mdl and I'm working through the findings now...

So I've installed mdl and I'm working through the findings now...

Please be careful what conclusions you draw. mdl is over-zealous on quite a lot of points (to the point of actually being wrong, or at least overly unflexible), until told otherwise in util/markdownlint.rb.

Please be careful what conclusions you draw. mdl is over-zealous on quite a lot of points (to the point of actually being wrong, or at least overly unflexible), until told otherwise in util/markdownlint.rb.

Good point. For this reason I've added three more rule exceptions,
in particular to allow bare URL. I see no point in re-writing, e.g.,

 directly at http://www.delorie.com/pub/djgpp. For help on which

to

 directly at [http://www.delorie.com/pub/djgpp](http://www.delorie.com/pub/djgpp).
 For help on which

as this just adds redundancy, wastes space,
and often adds the need for extra line breaks.

I'm done with all changes due to the reviews, and make md-nits is satisfied.

I didn't mean link references. Some markdown processors, when you would otherwise have [link-text](link-text) allow you to omit the parentheses part.

And while I'm here, just wanted to say that this is amazing work!

I've just rebased this, fixing conflicts with the just merged #12098.
Anything more to do on this PR?

@levitte, since you reviewed this and in my view all requested changes are done,
can you approve this now?

Travis failures are unrelated.

Please be careful what conclusions you draw. mdl is over-zealous on quite a lot of points (to the point of actually being wrong, or at least overly unflexible), until told otherwise in util/markdownlint.rb.

Good point. For this reason I've added three more rule exceptions,
in particular to allow bare URL. I see no point in re-writing, e.g.,

 directly at http://www.delorie.com/pub/djgpp. For help on which

to

 directly at [http://www.delorie.com/pub/djgpp](http://www.delorie.com/pub/djgpp).
 For help on which

as this just adds redundancy, wastes space,
and often adds the need for extra line breaks.

The sane alternative to disabling the bare URL warning is to write urls within <>: <https://www.example.com/>

A few comments below.

Thanks @romen.

I also have read about 1/3 of the changes so far, and this looks great!

Pleased to hear!

I would mention here (instead than repeating the same comment line by line) that [foo/bar.md] is equivalent to [foo/bar.md](foo/bar.md) and in many places we could prefer the implicit notation for readability and maintainability.

This would be great, but sadly, as mentioned meanwhile in #12232 (comment), I found that this is not supported at least by Firefox and Chrome/Chromium.

The other general note that I hope we will be able to address is that it seems git (well, the github ui at least, I haven't checked out this PR locally yet to examine more closely) seems to be losing track of some of the renames and instead treating them as o"old file was deleted, here is a new file". This is bad to track changes/blame in the documentation (which is often important in navigating how the project evolved and when features have been added, changed, deprecated, etc.).
IIRC our resident git guru @mspncp recently faced similar problems and of course he found a solution to provide git with enough hints that it was able to track file history/renames correctly. @mspncp can you guide us with your magic once more?

I think that in this case git (and the GitHub pages) does the right thing already.
For instance, git log -p shows things like

diff --git a/NOTES.ANDROID b/NOTES-Android.md
similarity index 100%
rename from NOTES.ANDROID
rename to NOTES-Android.md

While you're correct things, there's this at line 2934:

   configuration in one of the `Configurations/*.conf~ files (in

It should probably be:

   configuration in one of the `Configurations/*.conf` files (in

Oops, thanks, fixed.

Strange that mdl does not report such an imbalanced use of "`".

I just went though the rest of CHANGES.md and found many occurrences of "`xyz'"

and changed them to "xyz".

Strange that mdl does not report such an imbalanced use of "`".

Not at all, you are allowed to have multiline inline code blocks

Strange that mdl does not report such an imbalanced use of "`".

Not at all, you are allowed to have multiline inline code blocks

Yes, but I would expect that the number of backticks in a file should still be even.

However, there seems to be an implicit (redendering) rule that
the effect of a backtick stretches at most to the end of its paragraph.

Similarly, there's this line:

  * Make `openssl version' output lines consistent.

where the ' should be converted to a `

Done.

Rebased this mostly for kicking Travis after it had timed out on two runs last time.

I had to handle merge conflicts again.
Can we please finalize this soon?

Hopefully @levitte can add his approval and we can get this in ... it is nice work!

Hopefully @levitte can add his approval and we can get this in ... it is nice work!

Thanks @t-j-h!

@levitte (and also @richsalz and @romen) had already given various good comments, which I addressed,
and it appears to me he simply did not notice that or had no time to check on this.
In any case your approval will be sufficient.

Understood. The approval you require is there. I'm just hoping that @levitte can use the 24 hour delay before merge to also indicate his approval as well given you addressed all of his comments and he did a detailed review.

24 hours has passed since 'approval: done' was set, but as this PR has been updated in that time the label 'approval: ready to merge' is not being automatically set. Please review the updates and set the label manually.

Partly squashed, merged - thanks!

Well, it still seems weird to me that INSTALL.md contains quite thorough details about all aspects of configuration, building and installation, but that the testing details are thrown off to the side, so to say... I'm not sure I'll understand the purpose. But again, I seem to be a minority, so I'll accept this outcome.