guides.rubyonrails.org needs Doctype

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:

http://edgeguides.rubyonrails.org/

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 "&lt;", 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 :wink:

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!