Rails Guides should declare a DOCTYPE. It runs in Quirks mode on IE8 and looks terrible as a result.
That said, the site is a really useful resource to the Rails community. Thanks to everyone who contributes.
Thanks for pointing this out. It's true, Rails Guides should declare their doctype.
I'm investigating this, it's weird because if you generate the guides locally, the doctype line is included. See lines 94 and 207 of railties/rails_guides/generator.rb, where insert_doctype() is called and defined, respectively.
What I don't understand is why this is not being generated on the server.
I fixed this yesterday in the repo, waiting for some stuff in the server to be able to regenerate.
I saw validation errors nonetheless, working on that now.
I'll write back.
OK, so then we'll go with the XHTML 1.0 Strict doctype, right?
I've also seen validation errors, I'm working on them too.
OK edge guides regeneration is back, runs hourly:
http://edgeguides.rubyonrails.org/
Red thank you for reporting this, there's now a DOCTYPE in all pages, and at least the home validates. Jaime worked yesterday in other pages... how's that going Jaime?
OK edge guides regeneration is back, runs hourly:
Great, thanks!
Red thank you for reporting this, there's now a DOCTYPE in all pages, and at least the home validates. Jaime worked yesterday in other pages... how's that going Jaime?
It's going fine, I'm fixing all guides so they validate for the given DOCTYPE (STRICT). I'll tell you when it's finished.
Excellent Jaime, I see your work in the log.
I've simplified generator flags today: WARN_BROKEN_LINKS and WARN_DUPLICATE_HEADERS are gone, and their sanity checks are now enabled just setting WARNINGS=1.
Authors are encouraged to work always with WARNINGS=1, I'll revise the contribute guide with this and other stuff.
Also put some explicit IDs in some guides to avoid duplications, a few guides remain to be fixed. In principle we'll rely on authors not to have duplicate IDs in their work, warnings suggest how to address that. I prefer that approach to an automated but less predictable ID dedup.
Great, I've been fixing the rest of the guides and now the whole site validates XHTML 1.0 Strict, except for those guides with remaining duplicate IDs.
I've not fixed those yet as there is a little problem with the HTML generation when using explicit IDs:
http://github.com/lifo/docrails/commit/7d7e0627a0490b6b4ddb0ee5429264ccd46f1245
When this is fixed, I'll review and fix those guides too in order to have the whole site ready for strict validation.
Great, I've been fixing the rest of the guides and now the whole site validates XHTML 1.0 Strict, except for those guides with remaining duplicate IDs.
Good work!
I've not fixed those yet as there is a little problem with the HTML generation when using explicit IDs:
http://github.com/lifo/docrails/commit/7d7e0627a0490b6b4ddb0ee5429264ccd46f1245
When this is fixed, I'll review and fix those guides too in order to have the whole site ready for strict validation.
Fixed now.
I've finished fixing the guides, now the whole site validates XHTML 1.0 Strict!
I would like to encourage authors to validate documents before commits to ensure the site keeps validating Strict. It's easy to do with the Web Developer Toolbar, with the option "validate local HTML".
Two things to keep in mind:
1) IDs for headers are generated automatically by the script, but sometimes there are duplicated IDs and we need to set them manually. Look at the associations_basics guide for instance to see some examples of disambiguation, like "h6(#belongs_to-readonly)." and "h6(#has_one-readonly)."
2) When using the "<" char inside the ++ helper (plusplus), for instance to write about html tags or for the "<%=", we need to escape it with "<", as it won't be automatically escaped by Textilize because it puts content inside a <notextilize> tag.
On the next days I'll make a script to help validate the guides automatically.
Thanks guys. Now it renders in standards mode in IE8. Still looks
better in Firefox, but that's not your problem anymore 
Great!
Just to clarify, the only differences I'm seeing are:
* The "Guides Index" part of the top navigation has rounded corners and a drop shadow (very nice) in Firefox. IE doesn't do either yet. * The code blocks have no newlines in IE. All of the code displays in one line and the box has a scrollbar. The top margin on the code box doesn't match - in IE the code displays much closer to the top of the surrounding gray box than in Firefox. I think maybe the CSS is compensating for a newline? The top margin on the code tag is much smaller than the bottom margin.
Otherwise, the page displays pretty much the same.
That's a pity.
Please if anyone has the environment and skills to try to fix that it would be awesome, you could ask for commit right and work directly in the CSS in docrails.
There's a related thread about CSS in docrails:
http://groups.google.com/group/rubyonrails-docs/browse_thread/thread/fc4264cd8e6fd2d0
The conclusion was that making it validate the W3C guidelines was not worth the effort, but in any case if there's someone willing to make the site look better on other browsers like IE8, possibly making it validate, it would be cool.
Yeah that would be left to the criteria of whoever takes this. Priority would be that the website looks good, no matter validation, though if correctness is need to accomplish the former that is good also.
I am particulary concerned about code blocks being a single line.
It's finally here. Now you can run this from inside the railties directory in order to get output/*.html validated against the W3C Validator:
rake validate_guides
or, if you just want to validate one guide or a set, use the ONLY environmnent variable:
rake validate_guides ONLY=contribute,generators,credits
This little script makes use of the wonderful w3c_validators gem so you'll need to install it in case you don't have it.
Please, authors and editors, before pushing your changes do a local validation to ensure we always have valid XHTML!
