luca 0.9.89 → 0.9.91

data/site/html5bp-docs/htaccess.md

@@ -0,0 +1,323 @@
+[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation
+table of contents](README.md)
+
+# .htaccess
+
+In Apache HTTP server, `.htaccess` (hypertext access) is the configuration file
+that allows for web server configuration. HTML5 Boilerplate includes a number
+of best practice server rules for making web pages fast and secure, these rules
+can be applied by configuring `.htaccess` file.
+
+**You'll want to have these modules enabled for optimum performance:**
+
+* `mod_setenvif.c` (setenvif_module)
+* `mod_headers.c` (headers_module)
+* `mod_deflate.c` (deflate_module)
+* `mod_filter.c` (filter_module)
+* `mod_expires.c` (expires_module)
+* `mod_rewrite.c` (rewrite_module)
+
+
+## On Windows
+
+You've got a couple of options that depend on how you installed Apache.
+
+1. **WampServer**. This is by far the simplest option. If you have installed
+   WampServer just click on the icon in the task bar, hover over the Apache
+   section in the menu that comes up and then hover over the modules section.
+   You will be presented with a list of modules. Simply click on a module name
+   to enable it (or disable it if it is already enabled). A check mark next to
+   a module indicates that it is enabled. WampServer will automatically restart
+   the Apache service after you enable a module.
+
+2. **Manually editing `httpd.conf`**. This assumes that you have manually
+   installed Apache. You will need to locate the `httpd.conf` file which is
+   normally in the `conf` folder in the folder where you installed Apache (for
+   example `C:\apache\conf\httpd.conf`). Open up this file in a text editor. Near
+   the top (after a bunch of comments) you will see a long list of modules. Check
+   to make sure that the modules listed above are not commented out. If they
+   are, go ahead and uncomment them and restart Apache.
+
+That's it, you're done!
+
+
+## On Linux
+
+These instructions should work on any distribution where `apt-get` has been
+used to install Apache.
+
+1. Open up a terminal and type the following command. Enter your password when
+   prompted.
+
+    `sudo a2enmod setenvif headers deflate filter expires rewrite include`
+
+1. Restart apache by using the following command so the new configuration takes
+   effect.
+
+    `sudo /etc/init.d/apache2 restart`
+
+That's it, you're done!
+
+
+## On Mac
+
+Coming soon...
+
+
+## Security
+
+Do not turn off your ServerSignature (i.e., the `Server:` HTTP header). Serious
+attackers can use other kinds of fingerprinting methods to figure out the
+actual server and components running behind a port. Instead, as a site owner,
+you should keep track of what's listening on ports on hosts that you control.
+Run a periodic scanner to make sure nothing suspicious is running on a host you
+control, and use the ServerSignature to determine if this is the web server and
+version that you expect.
+
+
+## Performance
+
+### Configure ETags
+
+```apache
+FileETag None
+```
+
+Entity tags (ETags) is a mechanism that web servers and browsers use to
+determine whether the component in the browser's cache matches the one on the
+origin server. (An "entity" is another word a "component": images, scripts,
+stylesheets, etc.) ETags were added to provide a mechanism for validating
+entities that is more flexible than the last-modified date. An `ETag` is a
+string that uniquely identifies a specific version of a component. The only
+format constraints are that the string be quoted. The origin server specifies
+the component's `ETag` using the `ETag` response header.
+
+```http
+HTTP/1.1 200 OK
+Last-Modified: Tue, 12 Dec 2006 03:03:59 GMT
+ETag: "10c24bc-4ab-457e1c1f"
+Content-Length: 12195
+```
+
+Later, if the browser has to validate a component, it uses the `If-None-Match`
+header to pass the `ETag` back to the origin server. If the ETags match, a 304
+status code is returned reducing the response by 12195 bytes for this
+example.
+
+```http
+GET /i/yahoo.gif HTTP/1.1
+Host: us.yimg.com
+If-Modified-Since: Tue, 12 Dec 2006 03:03:59 GMT
+If-None-Match: "10c24bc-4ab-457e1c1f"
+HTTP/1.1 304 Not Modified
+```
+
+The problem with ETags is that they typically are constructed using attributes
+that make them unique to a specific server hosting a site. ETags won't match
+when a browser gets the original component from one server and later tries to
+validate that component on a different server, a situation that is all too
+common on web sites that use a cluster of servers to handle requests. By
+default, both Apache and IIS embed data in the ETag that dramatically reduces
+the odds of the validity test succeeding on web sites with multiple servers.
+
+The ETag format for Apache 1.3 and 2.x is inode-size-timestamp. Although a
+given file may reside in the same directory across multiple servers, and have
+the same file size, permissions, timestamp, etc., its inode is different from
+one server to the next.
+
+IIS 5.0 and 6.0 have a similar issue with ETags. The format for ETags on IIS is
+Filetimestamp:ChangeNumber. A ChangeNumber is a counter used to track
+configuration changes to IIS. It's unlikely that the ChangeNumber is the same
+across all IIS servers behind a web site.
+
+The end result is ETags generated by Apache and IIS for the exact same
+component won't match from one server to another. If the ETags don't match, the
+user doesn't receive the small, fast 304 response that ETags were designed for;
+instead, they'll get a normal 200 response along with all the data for the
+component. If you host your web site on just one server, this isn't a problem.
+But if you have multiple servers hosting your web site, and you're using Apache
+or IIS with the default ETag configuration, your users are getting slower
+pages, your servers have a higher load, you're consuming greater bandwidth, and
+proxies aren't caching your content efficiently. Even if your components have a
+far future Expires header, a conditional GET request is still made whenever the
+user hits Reload or Refresh.
+
+If you're not taking advantage of the flexible validation model that ETags
+provide, it's better to just remove the ETag altogether. The Last-Modified
+header validates based on the component's timestamp. And removing the ETag
+reduces the size of the HTTP headers in both the response and subsequent
+requests. This Microsoft Support article describes how to remove ETags. In
+Apache, this is done by simply adding the above line to your Apache
+configuration file.
+
+
+### Gzip Components
+
+Compression reduces response times by reducing the size of the HTTP response.
+
+Starting with HTTP/1.1, web clients indicate support for compression with the
+Accept-Encoding header in the HTTP request.
+
+```
+Accept-Encoding: gzip, deflate
+```
+
+If the web server sees this header in the request, it may compress the response
+using one of the methods listed by the client. The web server notifies the web
+client of this via the Content-Encoding header in the response.
+
+```
+Content-Encoding: gzip
+```
+
+Gzip is the most popular and effective compression method at this time. It was
+developed by the GNU project and standardized by RFC 1952. The only other
+compression format you're likely to see is deflate, but it's less effective and
+less popular.
+
+Gzipping generally reduces the response size by about 70%. Approximately 90% of
+today's Internet traffic travels through browsers that claim to support gzip.
+If you use Apache, the module configuring gzip depends on your version: Apache
+1.3 uses `mod_gzip` while Apache 2.x uses `mod_deflate`.
+
+There are known issues with browsers and proxies that may cause a mismatch in
+what the browser expects and what it receives with regard to compressed
+content. Fortunately, these edge cases are dwindling as the use of older
+browsers drops off. The Apache modules help out by adding appropriate Vary
+response headers automatically.
+
+Servers choose what to gzip based on file type, but are typically too limited
+in what they decide to compress. Most web sites gzip their HTML documents. It's
+also worthwhile to gzip your scripts and stylesheets, but many web sites miss
+this opportunity. In fact, it's worthwhile to compress any text response
+including XML and JSON. Image and PDF files should not be gzipped because they
+are already compressed. Trying to gzip them not only wastes CPU but can
+potentially increase file sizes.
+
+Gzipping as many appropriate file types as possible is an easy way to reduce
+page weight and accelerate the user experience.
+
+
+### Cache busting
+
+A first-time visitor to your page may have to make several HTTP requests, but
+by using the Expires header you make those components cacheable. This avoids
+unnecessary HTTP requests on subsequent page views. Expires headers are most
+often used with images, but they should be used on all components including
+scripts, stylesheets, etc.
+
+Traditionally, if you use a far future Expires header you have to change the
+component's filename whenever the component changes.
+
+The H5BP `.htaccess` has built-in filename cache busting. To use it, uncomment
+the relevant lines in the `.htaccess` file.
+
+Doing so will route all requests for `/path/filename.20120101.ext` to
+`/path/filename.ext`. To use this, just add a time-stamp number (or your own
+numbered versioning system) into your resource filenames in your HTML source
+whenever you update those resources.
+
+#### Example:
+
+```html
+<script src="/js/myscript.20120305.js"></script>
+<script src="/js/jqueryplugin.45.js"></script>
+<link rel="stylesheet" href="css/somestyle.49559939932.css">
+<link rel="stylesheet" href="css/anotherstyle.2.css">
+```
+
+**N.B. You do not have to rename the resource on the filesystem.** All you have
+to do is add the timestamp number to the filename in your HTML source. The
+`.htaccess` directive will serve up the proper file.
+
+Traditional cache busting involved adding a query string to the end of your
+JavaScript or CSS filename whenever you updated it.
+
+```html
+<script src="/js/all.js?v=12"></script>
+```
+
+However, as [Steve Souders](http://stevesouders.com/) explains in [*Revving
+Filenames: don’t use
+querystring*](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/),
+the query string approach is not always reliable for clients behind a Squid
+Proxy Server.
+
+
+## Trailing slash redirects
+
+Trailing slash redirects can be done by adding one of the options below in `.htaccess`.
+
+### Option 1
+Rewrite `domain.com/foo` -> `domain.com/foo/`.
+
+```apache
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$
+RewriteRule ^(.*)$ $1/ [R=301,L]
+```
+
+### Option 2
+Rewrite `domain.com/foo/` -> `domain.com/foo`
+
+```apache
+RewriteRule ^(.*)/$ $1 [R=301,L]
+```
+
+Here are some tips to show you how to integrate the rewrite rules with
+different CMS tools. There are four areas you need to look out for:
+
+### 1. Keep a backup
+
+If you use trailing slash redirects on an existing site, always keep a backup
+of your `.htaccess` and test thoroughly on your staging server before using it on
+a production server.
+
+### 2. Don't replace existing rules, merge
+
+For example, if you use CodeIgniter you may have existing URL rewrite rules like:
+
+```apache
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^(.*)$ index.php/$1
+```
+
+Merge the above with H5BP rules below:
+
+```apache
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$
+RewriteRule ^(.*)$ $1/ [R=301,L]
+```
+
+### 3. Be careful of the order
+
+Make sure you test thoroughly in your staging environment. For the above
+example, the order is add trailing slash first, and add your existing rule
+after:
+
+```apache
+# this adds trailing slash
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$
+RewriteRule ^(.*)$ $1/ [R=301,L]
+
+# this gets rid of index.php
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^(.*)$ index.php/$1
+```
+
+### 4. Double-check `RewriteBase` path is correct
+
+Make sure your `RewriteBase` path points to the correct location and sits above
+any rewrite rules. This usually happens to those have WordPress and ran the
+auto install. For instance, if you have a site at `example.com/blog`, your
+RewriteBase may look like:
+
+```apache
+RewriteBase /blog/
+```
+
+If you already have a working RewriteBase, keep that and don't remove it.

data/site/html5bp-docs/html.md

@@ -0,0 +1,170 @@
+[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation
+table of contents](README.md)
+
+# The HTML
+
+## Conditional `html` classes
+
+A series of IE conditional comments apply the relevant IE-specific classes to
+the `html` tag. This provides one method of specifying CSS fixes for specific
+legacy versions of IE. While you may or may not choose to use this technique in
+your project code, HTML5 Boilerplate's default CSS does not rely on it.
+
+When using the conditional classes technique, applying classes to the `html`
+element has several benefits:
+
+* It avoids a [file blocking
+  issue](http://webforscher.wordpress.com/2010/05/20/ie-6-slowing-down-ie-8/)
+  discovered by Stoyan Stefanov and Markus Leptien.
+* It avoids the need for an empty comment that also fixes the above issue.
+* CMSes like WordPress and Drupal use the body class more heavily. This makes
+  integrating there a touch simpler.
+* It still validates as HTML5.
+* It uses the same element as Modernizr (and Dojo). That feels nice.
+* It can improve the clarity of code in multi-developer teams.
+
+
+## The `no-js` class
+
+Allows you to more easily explicitly add custom styles when JavaScript is
+disabled (`no-js`) or enabled (`js`). More here: [Avoiding the
+FOUC](http://paulirish.com/2009/avoiding-the-fouc-v3/).
+
+
+## The order of meta tags, and `<title>`
+
+As recommended by [the HTML5
+spec](http://www.whatwg.org/specs/web-apps/current-work/complete/semantics.html#charset)
+(4.2.5.5 Specifying the document's character encoding), add your charset
+declaration early (before any ASCII art ;) to avoid a potential
+[encoding-related security
+issue](http://code.google.com/p/doctype/wiki/ArticleUtf7) in IE. It should come
+in the first [1024
+bytes](http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset).
+
+The charset should also come before the `<title>` tag, due to [potential XSS
+vectors](http://code.google.com/p/doctype-mirror/wiki/ArticleUtf7).
+
+The meta tag for compatibility mode [needs to be before all elements except
+title and meta](http://h5bp.com/f "Defining Document Compatibility - MSDN").
+And that same meta tag can only be invoked for Google Chrome Frame if it is
+within the [first 1024
+bytes](http://code.google.com/p/chromium/issues/detail?id=23003).
+
+
+## X-UA-Compatible
+
+This makes sure the latest version of IE is used in versions of IE that contain
+multiple rendering engines. Even if a site visitor is using IE8 or IE9, it's
+possible that they're not using the latest rendering engine their browser
+contains. To fix this, use:
+
+```html
+<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+```
+
+The `meta` tag tells the IE rendering engine two things:
+
+1. It should use the latest, or edge, version of the IE rendering environment
+2. If already installed, it should use the Google Chrome Frame rendering
+   engine.
+
+This `meta` tag ensures that anyone browsing your site in IE is treated to the
+best possible user experience that their browser can offer.
+
+This line breaks validation, and the Google Chrome Frame part won't work inside
+a conditional comment. To avoid these edge case issues it is recommended that
+you **remove this line and use the `.htaccess`** (or other server config)
+to send these headers instead. You also might want to read [Validating:
+X-UA-Compatible](http://groups.google.com/group/html5boilerplate/browse_thread/thread/6d1b6b152aca8ed2).
+
+If you are serving your site on a non-standard port, you will need to set this
+header on the server-side. This is because the IE preference option 'Display
+intranet sites in Compatibility View' is checked by default.
+
+
+## Mobile viewport
+
+There are a few different options that you can use with the [`viewport` meta
+tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4 "Viewport and
+Media Queries - The Complete Idiot's Guide"). You can find out more in [the
+Apple developer docs](http://j.mp/mobileviewport). HTML5 Boilerplate comes with
+a simple setup that strikes a good balance for general use cases.
+
+```html
+<meta name="viewport" content="width=device-width">
+```
+
+## Favicons and Touch Icons
+
+The shortcut icons should be put in the root directory of your site. HTML5
+Boilerplate comes with a default set of icons (include favicon and Apple Touch
+Icons) that you can use as a baseline to create your own.
+
+If your site or icons are in a sub-directory, you will need to reference the
+icons using `link` elements placed in the HTML `head` of your document.
+
+For a comprehensive overview, please read [Everything you always wanted to know
+about touch icons](http://mathiasbynens.be/notes/touch-icons) by Mathias
+Bynens.
+
+
+## Modernizr
+
+HTML5 Boilerplate uses a custom build of Modernizr.
+
+[Modernizr](http://modernizr.com) is a JavaScript library which adds classes to
+the `html` element based on the results of feature test and which ensures that
+all browsers can make use of HTML5 elements (as it includes the HTML5 Shiv).
+This allows you to target parts of your CSS and JavaScript based on the
+features supported by a browser.
+
+In general, in order to keep page load times to a minimum, it's best to call
+any JavaScript at the end of the page because if a script is slow to load
+from an external server it may cause the whole page to hang. That said, the
+Modernizr script *needs* to run *before* the browser begins rendering the page,
+so that browsers lacking support for some of the new HTML5 elements are able to
+handle them properly. Therefore the Modernizr script is the only JavaScript
+file synchronously loaded at the top of the document.
+
+
+## The content area
+
+The central part of the boilerplate template is pretty much empty. This is
+intentional, in order to make the boilerplate suitable for both web page and
+web app development.
+
+### Google Chrome Frame
+
+The main content area of the boilerplate includes a prompt to install Chrome
+Frame (which no longer requires administrative rights) for users of IE 6. If
+you intended to support IE 6, then you should remove the snippet of code.
+
+### Google CDN for jQuery
+
+The Google CDN version of the jQuery JavaScript library is referenced towards
+the bottom of the page using a protocol-independent path (read more about this
+in the [FAQ](faq.md). A local fallback of jQuery is included for rare instances
+when the CDN version might not be available, and to facilitate offline
+development.
+
+Regardless of which JavaScript library you choose to use, it is well worth the
+time and effort to look up and reference the Google CDN (Content Delivery
+Network) version. Your users may already have this version cached in their
+browsers, and Google's CDN is likely to deliver the asset faster than your
+server.
+
+### Google Analytics Tracking Code
+
+Finally, an optimized version of the latest Google Analytics tracking code is
+included. Google recommends that this script be placed at the top of the page.
+Factors to consider: if you place this script at the top of the page, you’ll be
+able to count users who don’t fully load the page, and you’ll incur the max
+number of simultaneous connections of the browser.
+
+Further information:
+
+* [Optimizing the asynchronous Google Analytics
+  snippet](http://mathiasbynens.be/notes/async-analytics-snippet).
+* [Tracking Site Activity - Google
+  Analytics](http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html).

data/site/html5bp-docs/js.md

@@ -0,0 +1,31 @@
+[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation
+table of contents](README.md)
+
+# The JavaScript
+
+Information about the default JavaScript included in the project.
+
+## main.js
+
+This file can be used to contain or reference your site/app JavaScript code.
+For larger projects, you can make use of a JavaScript module loader, like
+[Require.js](http://requirejs.org/), to load any other scripts you need to
+run.
+
+## plugins.js
+
+This file can be used to contain all your plugins, such as jQuery plugins and
+other 3rd party scripts.
+
+One approach is to put jQuery plugins inside of a `(function($){ ...
+})(jQuery);` closure to make sure they're in the jQuery namespace safety
+blanket. Read more about [jQuery plugin
+authoring](http://docs.jquery.com/Plugins/Authoring#Getting_Started)
+
+## vendor
+
+This directory can be used to contain all 3rd party library code.
+
+Minified versions of the latest jQuery and Modernizr libraries are included by
+default. You may wish to create your own [custom Modernizr
+build](http://www.modernizr.com/download/).

data/site/html5bp-docs/misc.md

@@ -0,0 +1,25 @@
+[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation table of contents](README.md)
+
+# Miscellaneous
+
+## .gitignore
+
+HTML5 Boilerplate includes a basic project-level `.gitignore`. This should
+primarily be used to avoid certain project-level files and directories from
+being kept under source control. Different development-environments will
+benefit from different collections of ignores.
+
+OS-specific and editor-specific files should be ignored using a "global
+ignore" that applies to all repositories on your system.
+
+For example, add the following to your `~/.gitconfig`, where the `.gitignore`
+in your HOME directory contains the files and directories you'd like to
+globally ignore:
+
+```gitignore
+[core]
+    excludesfile = ~/.gitignore
+```
+
+* More on global ignores: http://help.github.com/ignore-files/
+* Comprehensive set of ignores on GitHub: https://github.com/github/gitignore

data/site/html5bp-docs/usage.md

@@ -0,0 +1,109 @@
+[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation
+table of contents](README.md)
+
+# Usage
+
+Once you have cloned or downloaded HTML5 Boilerplate, creating a site or app
+usually involves the following:
+
+1. Set up the basic structure of the site.
+2. Add some content, style, and functionality.
+3. Run your site locally to see how it looks.
+4. (Optionally run a build script to automate the optimization of your site -
+   e.g. [ant build script](https://github.com/h5bp/ant-build-script) or [node
+   build script](https://github.com/h5bp/node-build-script)).
+5. Deploy your site.
+
+
+## Basic structure
+
+A basic HTML5 Boilerplate site initially looks something like this:
+
+```
+.
+├── css
+│   ├── main.css
+│   └── normalize.css
+├── doc
+├── img
+├── js
+│   ├── main.js
+│   ├── plugins.js
+│   └── vendor
+│       ├── jquery.min.js
+│       └── modernizr.min.js
+├── .htaccess
+├── 404.html
+├── index.html
+├── humans.txt
+├── robots.txt
+├── crossdomain.xml
+├── favicon.ico
+└── [apple-touch-icons]
+```
+
+What follows is a general overview of each major part and how to use them.
+
+### css
+
+This directory should contain all your project's CSS files. It includes some
+initial CSS to help get you started from a solid foundation. [About the
+CSS](css.md).
+
+### doc
+
+This directory contains all the HTML5 Boilerplate documentation. You can use it
+as the location and basis for your own project's documentation.
+
+### js
+
+This directory should contain all your project's JS files. Libraries, plugins,
+and custom code can all be included here. It includes some initial JS to help
+get you started. [About the JavaScript](js.md).
+
+### .htaccess
+
+The default web server config is for Apache. [About the .htaccess](htaccess.md).
+
+Host your site on a server other than Apache? You're likely to find the
+corresponding configuration file in our [server configs
+repo](https://github.com/h5bp/server-configs). If you cannot find a
+configuration file for your setup, please consider contributing one so that
+others can benefit too.
+
+### 404.html
+
+A helpful custom 404 to get you started.
+
+### index.html
+
+This is the default HTML skeleton that should form the basis of all pages on
+your site. If you are using a server-side templating framework, then you will
+need to integrate this starting HTML with your setup.
+
+Make sure that you update the URLs for the referenced CSS and JavaScript if you
+modify the directory structure at all.
+
+If you are using Google Analytics, make sure that you edit the corresponding
+snippet at the bottom to include your analytics ID.
+
+### humans.txt
+
+Edit this file to include the team that worked on your site/app, and the
+technology powering it.
+
+### robots.txt
+
+Edit this file to include any pages you need hidden from search engines.
+
+### crossdomain.xml
+
+A template for working with cross-domain requests. [About
+crossdomain.xml](crossdomain.md).
+
+### icons
+
+Replace the default `favicon.ico` and apple touch icons with your own. You
+might want to check out Hans Christian's handy [HTML5 Boilerplate Favicon and
+Apple Touch Icon
+PSD-Template](http://drublic.de/blog/html5-boilerplate-favicons-psd-template/).