Content update changes in PHP Coding Standards

[dingo-d]

This is the first part of the updates to the WPCS PHP documentation. In this PR I've gone through the text and replaced all the HTML with markdown syntax.

Some links have been updated - some HTTP to HTTPS replacements; data validation now points to the plugins handbook (as a part of the move from codex to developers documentation); added title refs to trac tickets.

I've looked at the JS coding standards documentation and markdown is used there, so don't see why it shouldn't be used here as well.

The second part of the updates will see what rules can be added from the make post in 2020. There are some ongoing discussions that are not resolved, but I'll add only the one that nobody had any issues with within the comments.

@jrfnl and I agreed that we should add this to the handbook so that the WPCS 3.0.0 release can be made in line with the new additions.

But I'll open a separate PR for that 🙂

Fixes: #19

[jrfnl]

@dingo-d Thank you for doing this! Looks great!

1. If we're now changing the text to markdown anyway, what about using definition links instead of inline links ? May need verification that the WP Parser handles those correctly though.
   A definition link in markdown is:

   Some text with a [descriptive link].
   
   [descriptive link]: http://link.to/

2. Some code samples use characters which need escaping in HTML, like > in ->. I seem to remember there were problems with double escaping when parsing those in the past.
   We may need to verify that after this change is merged, they are still displayed correctly, i.e. displayed as -> not -> and if not, may need to selectively revert those changes.

While reading the code diff, I also noticed various other things. I've left inline comments for these and marked them as "not directly related to this PR".

Those comments don't need to be addressed in this PR, but might warrant a follow-up PR.

[dingo-d]

Thanks for the review @jrfnl. I'll wait on comments on some of the issues you've mentioned from the rest of the team @GaryJones @ntwb @SergeyBiryukov before making changes.

If we're now changing the text to markdown anyway, what about using definition links instead of inline links?

I kinda like inline links more. They do clutter markdown file a bit, but it's easier to see what the link points to.

Some code samples use characters which need escaping in HTML, like > in ->. I seem to remember there were problems with double escaping when parsing those in the past.

Yes, I remember people having to replace those, I cannot test this so I'm unsure if this will cause breakage. I didn't find any instances of encoded HTML in the JavaScript chapter, so I just presumed as long as they are contained in backticks, we should be good (🤞🏼).

[GaryJones]

Assuming the renderer can handle standard Markdown, then changes generally look good.

I'd agree with keeping inline links - easier to follow when reading raw markdown than have to skip to the end of the paragraph/section/file to look for a URL, especially when most/all of the links are unique.

[ntwb]

Looking good, I've added a couple of minor nits, I've got a linting configuration setup locally, I created this quite some time ago using Remark-Lint, I started updating it last night to use Markdown Lint as that's what WordPress are now using for MD linting... I'll try to get this pushed up here in the coming days....

[jrfnl]

Okay.... so originally this PR was a PR to update the document from using HTML to using markdown.

Unfortunately, it has now evolved to include more extensive changes to the document, including removing sections and rewriting some texts.

For the purpose of having a clean history, I'd personally prefer we'd split this PR into two (or more PRs), with the markup changes in one PR and the textual changes in one or more follow-up PRs.

That would also prevent this PR from lingering as the original change proposal was perfectly fine and only gathered very few comments regarding the actual markup changes.
This PR could have (and should have) been merged already, but the PR is now being delayed/dragged out due to the scope of the PR creeping into different territories.

What about if we split this into the following separate PRs ?

1. Purely the markup changes from HTML to Markdown.
2. Textual updates for outdated content (removing references to PEAR, removing the Changelog, updating texts relating to PHP functionality which has since changed etc).
3. Update the code samples for a) correct capitalization and punctuation of inline comments and b) correct use of output escaping in the code samples (and any other suggestions made).
4. Whatever remains.

Having said that, as textual changes are now happening anyway (either in this PR or in follow-up PRs), I've gone through the document again with a fine toothcomb (including the parts of the document which were untouched by the original PR) and left a range of remarks to address.
IMO, nearly all these comments should be addressed in follow-up PRs and not so much in this PR.

[dingo-d]

@GaryJones @ntwb do you agree that I create a separate PR just for markdown changes made (the first few commits), then I can rebase this one and we can handle the changes Juliette suggested here?
That way we don't do much in just one PR.

[GaryJones]

do you agree that I create a separate PR just for markdown changes made (the first few commits), then I can rebase this one and we can handle the changes Juliette suggested here?

Of course :-)

[dingo-d]

@GaryJones @ntwb Juliette and I did a pass through and fixed all the content update changes, can you give it another go so that we can merge this?

Thanks!

[jrfnl]

Looks great! Thanks for getting this sorted @dingo-d ! Looking forward to the next PR with the code sample updates. Great momentum to get it all shiny now.

[jrfnl]

Crossing our t's and dotting our i's... just two final remarks.

[jrfnl]

Let's get this merged!

[SergeyBiryukov]

Thanks for the PR! Left one minor suggestion with a typo fix, looks good to me otherwise 👍