Fix Guide HTML validation

[nateberkopec]

Hi!

The Ruby on Rails Guides Guidelines say that you should make sure all guides are valid HTML and that bundle exec rake guides:generate should be run with WARNINGS=1 to make sure our internal links are valid. To my surprise, there were quite a few validation errors!

Now, rake guides:validate returns no errors and rake guides:generate WARNINGS=1 returns no warnings.

I left these commits small and separate, please instruct if you wish me to squash them.

Expect a PR soon moving the guides to HTML5, hopefully it won't be too much work!

[AJ-Acevedo]

The project prefers that all Pull Requests are squished and you add [ci skip] to the commit message.

[robin850]

If we want to be HTML 5 compliant, this change is not needed.

[nateberkopec]

Sure - I was aiming for validation with the current, XHTML 1.0 Strict doctype before making any changes for HTML5. This PR is for a validating XHTML 1.0 Strict page, not an HTML5 one. If I switch the doctype to HTML5, I'll make a separate PR.

[nateberkopec]

Squashed to one commit.

[senny]

can't we escape the & instead of using and?

[nateberkopec]

Hmm - I've tried using &amp;, but something along the pipeline is eating it and turning it back into a "&". Probably Nokogiri. I'll look into it.

[senny]

I see... is this the only & in the guides then?

[nateberkopec]

It isn't - but it's the only & that's getting pulled into a title tag, which is what's causing the validation error. And, it looks like we were setting html_safe on the title string, which was causing the title to be inserted without escaping.

html_safe seems unneccesary here, so I've removed it, which causes the & to be escaped. All guides validate correctly.

[nateberkopec]

@vijaydev I have removed my deletion of the invalid link ("WEBrick isn't your only option for serving Rails. We'll get to that later").

This PR still returns: All checked guides validate OK! from rake guides:validate

[JonRowe]

This seems like a positive change, any reason it hasn't been reviewed again? @senny?

[nateberkopec]

Willing to rebase against any changes. LMK.

[senny]

@nateberkopec please do rebase, I'll see that we can move this forward.

[vijaydev]

I had wanted to run this locally and verify the changes, but never got around to it. Sorry about that!
@senny If you are giving this a shot, please do :) Else, I can take this up sometime in the coming week.

[vijaydev]

Now I realize why I never got to this. I end up getting 502 Proxy Errors whenever I run validation on my box. I'm fine with the changes made and once Nate rebases, we can merge.

[senny]

Tried to run validations on this branch as well. Got a few "Proxy Errors" but beside that it still printed tons of validation errors. Am I doing it wrong?

https://gist.github.com/senny/0213ea3b4c5c38947ea2

[robin850]

Hi there,

Sorry if I'm missing something but why would we want to be XHTML 1.0 compliant ? I'm pretty sure less work would be needed if we were at making these guides HTML 5 compliant. I'm also wondering if the result provided by the w3c_validators gem are trustworthy since the last release of this gem was almost 3 years ago.

@senny : I guess you've already generated the guides locally so it is validating the old ones. You can run the following but there will still be the proxy errors:

$ bundle exec rake guides:generate guides:validate

Thanks for your patch by the way! :-)

[nateberkopec]

Thanks to @robin850's suggestion, I've changed this PR to update the guides to valid HTML5.

Here's a gist of my clean rake guides:validate output.

@senny @vijaydev The 502's are just w3c_validators struggling to POST from time to time. It never really happens twice if you just run it again.

EDIT: Rebased and ready to merge.

[senny]

@nateberkopec looking good! Thanks 💛