@NextTurn : Thanks for your contribution! The author, @, has been notified to review your proposed change.

@NextTurn : Thanks for your contribution! The author, @, has been notified to review your proposed change.

@NextTurn I like your can-do attitude and automation-based approach. This set of changes is a little ambitious for a single PR, and one of these changes should probably be discussed first. There's no problem with changing the spelling of See also sections throughout. I'd ask that PRs for this change be broken into multiple PRs by top level directory, however, to make them easier to review, and to minimize the impact of merge conflicts on work that's in flight. Thanks for taking the challenge on in the first place!

The bullet issue is something else. When we moved all the documentation into markdown, the conversion failed to honor existing single line breaks as intended. The See also links were all coalesced into a single paragraph. So were parameter lists, many procedures, syntax sections and EBNF grammars, among other things. It took a while to find and fix those issues. At first, we tried adopting the markdown "standard" of using two spaces before a line break to create a break without creating a new paragraph. This proved very fragile in practice, as most people use editors that don't show the spaces. In fact, many editors have settings to strip trailing spaces, which would invisibly break our careful formatting.

In some cases, such as the See also sections, we experimented with bullets to make it easy for contributors to maintain the line breaks between the links. Colleagues in the Visual Studio and .NET repos picked this style up for new and modified content. Unfortunately, it wasn't a universal solution for the line break issue within documents, and was a gratuitous divergence from the MSDN style. After more experimentation, the C++ doc team decided the best way to be consistent about line breaks within documents, and to preserve our preferred formatting in the face of editors (and contributors) that might silently break it, was to make all breaks into explicit (X)HTML <br/> tags. These have the great advantage of being highly visible to any inexperienced contributor, using any editor, unlike the trailing spaces. And it 's just a shortcut to getting the same results as two trailing spaces in the markdown to HTML converter. We did it for internal consistency, and to preserve the original style. However, since the Visual Studio and .NET documentation teams generally adopted the bullets in See also sections, that left us with an inconsistency across document sets. If I had my druthers, they'd all adopt our break tag solution instead. We might pick up the bullet style after some discussion with my colleagues about how consistent we need to be, but for now it's consistency for consistency's sake with something that I don't like.

I'm going to close this PR in favor of requesting new ones, to avoid dealing with merge issues. Definitely don't let my comments discourage you from making more PRs for problems and inconsistencies you see. My one request is, if it's something big or global, raise an issue first, so we can see what you have in mind and possibly provide some insight or make suggestions. And thanks for making the documentation better.