search

aFarkas / html5shiv

This script is the defacto way to enable use of HTML5 sectioning elements in legacy Internet Explorer.
http://paulirish.com/2011/the-history-of-the-html5-shiv/
9.89k stars 2.56k forks source link

Conflicting information in README: Browser support and implementation? #104

Closed mhulse closed 10 years ago

mhulse commented 11 years ago

I'm probably missing something obvious here ... If so, let me apologize in advance for my ignorance.

With that said, could someone help me to understand why the README says this in one spot:

The HTML5 Shiv enables use of HTML5 sectioning elements in legacy Internet Explorer and provides basic HTML5 styling for Internet Explorer 6-9, Safari 4.x (and iPhone 3.x), and Firefox 3.x.

... and a bit further down, it says:

Include the HTML5 shiv at the top of your <head> in a conditional comment before any stylesheets. 

<!--[if lt IE 9]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->

Just curious if using <!--[if lt IE 9]> (to be clear, that's "less than IE 9, right?) will cancel out the scripts positive effects on Internet Explorer 9, Safari 4.x (and iPhone 3.x), and Firefox 3.x?

I've gotten the approval to drop IE < 9 for one of my latest projects, and I'm trying to determine if I can stop using html5shiv; if it's meant to only be applied to IE < 9, then I wont use it ... On the other hand, if it helps to make IE9 (and the others mentioned above) behave better, then I'd gladly keep it in my templates. :+1:

Anyway, hoping someone can shed some light.

Many thanks for the awesome code!!!! Amazing stuff!!!!

mhulse commented 11 years ago

So, if I'm understanding things here...

If I use the IE conditional comment, then IE 9, Safari 4.x (and iPhone 3.x), and Firefox 3.x won't get these basic styles:

// corrects block display not defined in IE6/7/8/9
'article,aside,figcaption,figure,footer,header,hgroup,nav,section{display:block}' +
// adds styling not present in IE6/7/8/9
'mark{background:#FF0;color:#000}'

Maybe the IE conditional comment should be changed to:

<!--[if lte IE 9]> ... <![endif]-->

... That's "less than or equal to IE 9".

Then the only puzzle piece missing is how does one get the "basic styling" applied to Safari 4.x (and iPhone 3.x), and Firefox 3.x?

I suppose at that point, one would make the choice to 1) not use the conditional comments, 2) not care about older, non-old-IE, browsers or 3) keep conditional comments but use their own techniques to apply said basic styles to older, non-old-IE, browsers?

Feedback anyone?

I'd be more than happy to do a pull request.

mhulse commented 11 years ago

Hehe, am I the only one that fixates on small details like this?

I'd love to know what the pros think in terms of how to optimally install this code.

Do we just target IE < 9 (to clarify, that's IE 6 - 8), or do we ditch the IE conditional comment and allow the code to work on the other old, non-IE, browsers mentioned in the README?

Again, I know this is small potatoes, just seems like it would be good to clarify the usage here.

aFarkas commented 11 years ago

@mhulse

From my point of view, it is best to do the styling via CSS. For example with normalize.css and leave the conditional comments. I will try to update the readme/go through all open issues tomorrow.

Volker-E commented 11 years ago

Correct me if I'm wrong, but I think just about every dev is using html5shiv only when they need to support IE <= 8, IE 9 inclusion is more a side-effect, or? So I'd suggest changing the first sentence to 'The HTML5 Shiv enables use of HTML5 sectioning elements in legacy Internet Explorer and provides basic HTML5 elements styling for Internet Explorer 6-9'.

How about a 'best practice' addition under Installation linking to normalize.css v1? Probably having two examples down there - one with HTML5 lte IE 8 support and normalize.css v1, the other with @mhulse suggestion for change of conditional comment to lte IE 9 explaining that it provides basic styling?

@aFarkas Connected to this issue, I'd also update the link for 'It also applies basic styling for HTML5 elements' as there has been additions since the linked commit.

mhulse commented 11 years ago

@aFarkas Thanks so much for your help! I really appreciate it.

From my point of view, it is best to do the styling via CSS. For example with normalize.css and leave the conditional comments.

Ah, that's good news. I do use normalize.css when starting new projects. I would imagine most people do these days.

I will try to update the readme/go through all open issues tomorrow.

Let me know if I can help with anything.

mhulse commented 11 years ago

@Volker-E I like those ideas.

My idea for changing the first sentence was:

The HTML5 Shiv adds basic HTML5 styling and enables the use of HTML5 sectioning elements in Internet Explorer 6-8.

But, I like your idea of providing two examples:

  1. Example of using HTML5 Shiv/PrintShiv, to target IE <= 8, in conjunction with normalize.css v1.
  2. Example using HTML5 Shiv/PrintShiv, without normalize.css, that targets IE <= 9.

Connected to this issue, I'd also update the link for 'It also applies basic styling for HTML5 elements' as there has been additions since the linked commit.

I see the current link points here:

https://github.com/aFarkas/html5shiv/blob/4525162dd10e6fff7b83d06b28b562586e9fb058/src/html5shiv.js#L214-L217

What would be the updated link?

I'm actually in the process of re-writing the README (not sure if it will help, but I figured it would save Alexander some time). If you could provide the new link, I'll incorporate it into my pull request.

Volker-E commented 11 years ago

@mhulse Current html5shiv.js master's commit link would be https://github.com/aFarkas/html5shiv/blob/e5da0a90797ae8b236d5901fe7b7b8b55b220847/src/html5shiv.js#L215-L220

mhulse commented 11 years ago

@Volker-E Thanks!

mhulse commented 11 years ago

How's this look:

HTML5 Shiv

The HTML5 Shiv enables the use of HTML5 sectioning elements and provides basic HTML5 styling in legacy versions of Internet Explorer.

... ... ... ...

Installation

Using Bower

$ bower install html5shiv --save-dev

This will clone the latest version of the HTML5 shiv into the components directory at the root of your project and also create or update the file bower.json which specifies your projects dependencies.

… or manually

Download and extract the latest zip package from the HTML5 Shiv repository and copy dist/html5shiv.js or dist/html5shiv-printshiv.js into your project.

Put HTML5 Shiv in the <head>

Include the HTML5 shiv at the top of your <head>, before any stylesheets, in an IE conditional comment.

Examples

It is recommended to use HTML5 Shiv in conjunction with normalize.css v1 and use conditional comments to target Internet Explorer 6-8:

<!--[if lte IE 8]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->
<link rel="stylesheet" href="normalize.css">

Alternatively, if you're not using normalize.css, you can also target IE 9 as HTML5 Shiv provides basic HTML5 element styling:

<!--[if lte IE 9]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->

Feedback?

mhulse commented 11 years ago

Also, there's a few spots in the README that say:

... IE8- ...

The minus is not clear to me. Does that mean only IE8, or is that IE 6-8? I'd like to make those spots more explicit.

mhulse commented 11 years ago

I've posted my edits to the README here:

https://gist.github.com/mhulse/5737215

I'd love to get feedback before sending a pull request.

mhulse commented 11 years ago

Based on conversation in #98, could the below line be improved?

HTML5 Shiv works as a simple drop-in solution. In most cases there is no need to configure HTML5 Shiv or use methods provided by HTML5 Shiv.

Makes sense to me, especially now that there's improved installation instructions.

In commit 5df33c1, @drzax made this change:

HTML5 Shiv works as a simple drop-in solution as described above. In most cases there is no need to configure HTML5 Shiv or use methods provided by HTML5 Shiv.

Now that there's an "installation" section, maybe that should read:

HTML5 Shiv works as a simple drop-in solution as described in the installation instructions above. In most cases there is no need to configure HTML5 Shiv or use methods provided by HTML5 Shiv.

thomaswelton commented 11 years ago

I'm confused as to why normalise.css deserves a mention here.

The html5 shiv allows styling of elements that lt IE9 or others wouldn't be able to interpret. Where as normalise.css standardises the affects that the browsers default styles of html5 elements has.

Wether to use normalise.css or a CSS reset should be left to the developer. It shouldn't be a recommendation for this script as it has no impact on the html5 shiv works. And could lead to confusion about this scripts dependencies

mhulse commented 11 years ago

@thomaswelton

Good points. I agree with you about the mentioning of normalize.css (though, Alexander did say that was the best route to take).

Along those same lines, I think the information about Bower is a bit specialized ... I guess it's good to let people know that it's available as a package for Bower, but should it really be featured as the main item under the installation instructions? I think not, but I'm biased, as I don't use Bower.

I digress ...

The point of me having opened this issue is because the current instructions are confusing.

You say:

The html5 shiv allows styling of elements that lt IE9 or others wouldn't be able to interpret.

Going back to my original question, the confusion are these lines from the current README:

The HTML5 Shiv enables use of HTML5 sectioning elements in legacy Internet Explorer and provides basic HTML5 styling for Internet Explorer 6-9, Safari 4.x (and iPhone 3.x), and Firefox 3.x.

... and:

Include the HTML5 shiv at the top of your <head> in a conditional comment before any stylesheets. 

<!--[if lt IE 9]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->

With that said ...

Are you saying that I should change this (in my version of the README):

Put HTML5 Shiv in the <head>

Include the HTML5 shiv at the top of your <head>, before any stylesheets, in an IE conditional comment.

Examples

It is recommended to use HTML5 Shiv in conjunction with normalize.css v1 and use conditional comments to target Internet Explorer 6-8:

<!--[if lte IE 8]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->
<link rel="stylesheet" href="normalize.css">

Alternatively, if you're not using normalize.css, you can also target IE 9 as HTML5 Shiv provides basic HTML5 element styling:

<!--[if lte IE 9]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->

... to this:

Put HTML5 Shiv in the <head>

Include the HTML5 Shiv at the top of your <head>, before any style sheets, in an IE conditional comment:

<!--[if lte IE 8]>
    <script src="components/html5shiv/html5shiv.js"></script>
<![endif]-->

Or something like that ... Ya?

It's much simpler.

mhulse commented 11 years ago

Ok, I've removed the info about normalize.css and added the verbiage about it being a "drop-in solution":

https://gist.github.com/mhulse/5737215

mhulse commented 11 years ago

@aFarkas FYI, my version of the README has a lots of minor editing tweaks (grammar, punctuation, markdown, other). Obviously, once I do a pull request, you'll be able to compare the diffs.

aFarkas commented 11 years ago

@mhulse and other

I didn't looked into the details of your readme. It's better to make a pull request and walk through each change. I have updated the readme.

In general: I don't think, that we should explain everything in detail. Usage is very basic and if we start to explain every possibilty and the inner workings, people will get confused.

Here is what I have changed

  1. html5shiv should be included after all stylesheets (This is a performance advice). and was a "regression" in the documentation.
  2. IE8- is replaced by Internet Explorer 6-8 (but I think IE6 and mostly IE7 already died)
  3. updated link to basic styling information
  4. Clarifyed that main shiv is for IE6-8 and basic styling is for IE9 and Safari 4.x etc.

@mhulse

Would you make a pull request for your changes based on the new readme? As I said, I haven't fully looked over your changes. We can than discuss all changes on this PR.