Polish MD Documentation

[tajmone]

Fix typos and improve markdown formatting of c-xrefactory.md:

• Improve formatting:
  • Format keyboard keys using <kbd> tag.
  • Improve used symbols like em-dashes, etc.
  • Format notes as block-quotes.
  • Examples:
    • Style "Before/After Refactoring" in emphasis instead of strong, and fix inconsistent formatting of colon.
  • Examples code:
    • Wrap code in fenced blocks with lang ID, to allow syntax highlighting.
    • Apply consistent indentation (4 spaces).
    • Remove slash escapes before square brackets (possibly auto-inserted by an editor).
• Cross references:
  • Fix broken links (wrong anchor IDs).
  • Convert all X-Refs to reference-style links, and place their definitions at doc end.
  • "Refactorer" TOC: Add missing link references definitions.
  • Add "Refactoring" to main TOC entries.
• Fix inconsistent heading levels (h1 -> h2).
• Fix LICENSE link (branch was renamed from master to main).

[tajmone]

One Sentence Per Line!

@thoni56, please allow me to reformat all markdown documents using "one-sentence-per-line" instead of wrapping text at 72.

The downsides of wrapping text at a fixed column are many — from harder to read diffs in commits changes, to having to constantly fix the wrapping when editing text. Furthermore, in many contexts it's not possible to honour the wrapping convention, e.g. in tables, and verbatim and code blocks.

Editing wrapped markdown documents is harder in general, whereas the one-sentence-per-line" approach allows a smoother editing experience (especially when needing to move around individual sentences).

The only rationale for wrapping at 72 would be to allow better previewing of the raw document in the terminal, but modern terminals are getting smarter nowadays, so this might not even be true any longer. Markdown docs in repositories are mainly intended for online previewing, so keeping the source document wrapped is not a priority. Also, these considerations should only apply to the README files, not to documentation.

I also noticed that in numerous places there are multiple spaces between words, which I guess were inserted by a "wrapping editor" that automatically justifies the text to make it flush to the right — very bad in lightweight markup documents, since it forces to use RegExs in search-&-replace operations, e.g. to edit all occurrences of a group of words, since they might have different spacing in-between! So, that should also be fixed.

Author?

Who is the author of the c-xrefactory.md document? Did you write it, or has it been adapted from the original documentation?

I'm asking because I was thinking of porting the documentation to AsciiDoc, since it's a much better format for these types of documents (automatic x-refs, advanced tables that can be wrapped, and tons of other formatting features which would render this document nicer to read and easier to maintain).

But since AsciiDoc document require specifying the author in the header, I'd like to correctly provide the author name.