Doc cleanup

README.md

@@ -2,9 +2,11 @@
 
 RequireJS loads plain JavaScript files as well as more defined modules. It is optimized for in-browser use, but it can be used in other JavaScript environments, like Rhino. It implements the [CommonJS Transport/C proposal](http://wiki.commonjs.org/wiki/Modules/Transport/C) API.
 
-RequireJS uses plain script tags to load modules/files, so it should allow for easy debugging. It can be used simply to load existing JavaScript files, so you can add it to your existing project without having to re-write your JavaScript files.
+RequireJS uses plain script tags to load modules/files, so it should allow for easy debugging. It can be used [simply to load existing JavaScript files](docs/api.md#jsfiles), so you can add it to your existing project without having to re-write your JavaScript files.
 
-If the JavaScript file defines a JavaScript module via require.def(), then there are other benefits RequireJS can offer: better CommonJS support, loading multiple versions of a module in the same page, and better optimizations via the optimization tool. RequireJS also allows for module modifiers and has a plugin system that supports features like i18n string bundles and text file dependencies.
+RequireJS includes [an optimization tool](docs/optimization.md) you can run as part of your packaging steps for deploying your code. The optimization tool can combine and minify your JavaScript files to allow for better performance.
+
+If the JavaScript file defines a JavaScript module via [require.def()](docs/api.md#define), then there are other benefits RequireJS can offer: [better CommonJS support](http://wiki.commonjs.org/wiki/Modules/Transport/C) and [loading multiple versions](docs/api.md#multiversion) of a module in a page. RequireJS also allows for [module modifiers](docs/api.md#modifiers) and has a plugin system that supports features like [i18n string bundles](docs/api.md#i18n) and [text file dependencies](docs/api.md#text).
 
 RequireJS does not have any dependencies on a JavaScript framework. It is tri-licensed -- BSD, MIT, and GPL.
 
@@ -18,6 +20,7 @@ Latest Release: 0.8.0
     * [Using it with jQuery](docs/jquery.md)
 * [Download](docs/download.md)
 * [API](docs/api.md)
+* [Optimization](docs/optimization.md)
 * [Why](docs/why.md)
 * [Requirements](docs/requirements.md)
 * [History](docs/history.md)

build/example.build.js

@@ -94,9 +94,19 @@ require(
         //full to find the require calls/dependencies, but the code is executed
         //in the Rhino JavaScript environment. Set this value to false
         //if the code does not follow the strict require pattern of wrapping all
-        //code in a require callback.
-        execModules: true
+        //code in a require callback. If you are using jQuery, you should set
+        //this value explicitly to false.
+        execModules: true,
 
+        //For build profiles that contain more than one require() call for build
+        //layers, normally the first call's require() configuration options are used
+        //for subsequent layers. However, if you pass a configuration object to
+        //a later require call, you can pass the config object with an override
+        //property to just override some config values for just that require()
+        //call's build layer, and subsequent build layers will not get those
+        //overrided values. The override's value is just an object that can
+        //contain any of the other build options in this file.
+        override: null
 /*
         TODO:
         - way to optimize CSS? default to true

dist/dist-site.js

@@ -63,7 +63,7 @@ for (i = 0; (mdFile = files[i]); i++) {
     fileContents = fileContents.replace(/\$\{title\}/, h1);
 
     //Change any .md references to .html references
-    fileContents = fileContents.replace(/href="([^"]+)\.md"/g, 'href="$1.html"');
+    fileContents = fileContents.replace(/href="([^"]+)\.md/g, 'href="$1.html');
 
     //Adjust the path the main.css
     path = htmlFile.replace(/\/[^\/]+$/, "").replace(/^\.\/dist-site\//, "");

dist/pre.html

@@ -29,6 +29,7 @@
     <li><a class="local" href="download.html">Download</a></li>
     <li><a class="local" href="api.html">API</a></li>
     <li><a class="local" href="why.html">Why</a></li>
+    <li><a class="local" href="optimization.html">Optimization</a></li>
     <li><a class="local" href="requirements.html">Requirements</a></li>
     <li><a class="local" href="history.html">History</a></li>
     <li><a href="http://groups.google.com/group/requirejs">Get Help</a></li>

docs/api.md

@@ -1,7 +1,25 @@
 # RequireJS API
 
-
-# Usage
+* [Usage](#usage)
+    * [Loading JavaScript Files](#jsfiles)
+    * [Defining a Module](#define)
+        * [Other Module Notes](#modulenotes)
+        * [Circular Dependencies](#circular)
+    * [Define an I18N Bundle](#i18n)
+    * [Define a Text File Dependency](#text)
+* [Mechanics](#mechanics)
+* [Configuration Options](#config)
+* [Page Load Event Support](#pageload)
+* [Advanced Usage](#advanced)
+    * [Multiversion Support](#multiversion)
+    * [Loading Code After Page Load](#afterload)
+    * [require.pause()/require.resume() for Build Layers](#pauseresume)
+    * [Module Modifiers](#modifiers)
+        * [Modifier Registration](#modregister)
+        * [Modifier Definition](#moddef)
+    * [Rhino Support](#rhino)
+
+# <a name="usage">Usage</a>
 
 There are 4 basic ways to use require.js:
 
@@ -10,7 +28,7 @@ There are 4 basic ways to use require.js:
 3. Define an internationalization (i18n) bundle.
 4. Specify a text file dependency.
 
-## Loading JavaScript Files
+## <a name="jsfiles">Loading JavaScript Files</a>
 
 If you just want to load some JavaScript files, do the following inside the HEAD tag in an HTML document:
 
@@ -35,7 +53,7 @@ Files that end in ".js" are assumed to just be plain JS files that do not use re
 
 See the **Configuration Options** section for information on changing the lookup paths used for dependencies.
 
-## Defining a Module
+## <a name="define">Defining a Module</a>
 
 If the module does not have any dependencies, then just specify the name of the module as the first argument to require.def() and and the second argument is just an object literal that defines the module's properties. For example:
 
@@ -92,11 +110,11 @@ If the modules do not have to return objects. Any valid return value from a func
         }
     );
 
-### Other Module Notes
+### <a name="modulenotes">Other Module Notes</a>
 
 Only one module should be defined per JavaScript file, given the nature of the module name-to-path lookup algorithm.
 
-### Circular Dependencies
+### <a name="circular">Circular Dependencies</a>
 
 If you define a circular dependency (A needs B and B needs A), then in this case when B's module function is called, it will get an undefined value for A. B can fetch A later after modules have been defined by using the require() method (be sure to specify require as a dependency so the right context is used to look up A):
 
@@ -113,7 +131,7 @@ If you define a circular dependency (A needs B and B needs A), then in this case
 
 Normally you should not need to use require() to fetch a module, but instead rely on the module being passed in to the function as an argument. Circular dependencies are rare, and usually a sign that you might want to rethink the design. However, sometimes they are needed, and in that case, use require() as specified above.
 
-## Define an I18N Bundle
+## <a name="i18n">Define an I18N Bundle</a>
 
 Once your web app gets to a certain size and popularity, localizing the strings in the interface and providing other locale-specific information becomes more useful. However, it can be cumbersome to work out a scheme that scales well for supporting multiple locales.
 
@@ -195,7 +213,7 @@ Then the value for red in "root" will be used. This works for all locale pieces.
 * my/nls/fr/colors.js
 * my/nls/colors.js
 
-## Specify a Text File Dependency
+## <a name="text">Specify a Text File Dependency</a>
 
 It is nice to build HTML using regular HTML tags, instead of building up DOM structures in script. However, there is no good way to embed HTML in a JavaScript file. The best that can be done is using a string of HTML, but that can be hard to manage, particularly for multi-line HTML.
 
@@ -226,7 +244,7 @@ The text files are loaded via asynchronous XMLHttpRequest (XHR) calls, so you ca
 
 However, the build system for require.js will inline any text! references with the actual text file contents into the modules, so after a build, the modules that have text! dependencies can be used from other domains.
 
-# Mechanics
+# <a name="mechanics">Mechanics</a>
 
 require.js loads each dependency as a script tag, using head.appendChild(). In the near future, there may be an optimization or a configuration option to allow using document.write() to write out the script tag (with an src= attribute) if the page has not loaded yet.
 
@@ -236,7 +254,7 @@ Using require.js in a server-side JavaScript enviroment that has synchronous loa
 
 In the future, this code may be pulled into the require/ directory as an optional module that you can load in your env to get the right load behavior based on the host environment.
 
-# Configuration Options
+# <a name="config">Configuration Options</a>
 
 When using require() in the top-level HTML page (or top-level script file that does not define a module), a configuration object can be passed as the first option:
 
@@ -300,7 +318,7 @@ If no baseUrl is passed in, the path to require.js is used as the baseUrl path.
 
 **ready**: An function to pass to require.ready(). Useful when require is defined as a config object before require.js is loaded, and you want to specify a require.ready callback to set as soon as require() is defined.
 
-# Page Load Event Support
+# <a name="pageload">Page Load Event Support</a>
 
 require.js also has a method for notifying your code when the page has loaded. require.js uses the DOMContentLoaded event for browsers that support it, or window onload for browsers that do not.
 
@@ -320,7 +338,7 @@ To use it in conjunction with module loading:
         }
     );
 
-# Advanced Usage
+# <a name="advanced">Advanced Usage</a>
 
 Some advanced features:
 
@@ -330,7 +348,7 @@ Some advanced features:
 * Module Modifiers
 * Rhino support
 
-## Multiversion Support
+## <a name="multiversion">Multiversion Support</a>
 
 As mentioned in **Configuration Options**, multiple versions of a module can be loaded in a page by using different "context" configuration options. Here is an example that loads two different versions of the alpha and beta modules (this example is taken from one of the test files):
 
@@ -375,11 +393,11 @@ As mentioned in **Configuration Options**, multiple versions of a module can be
     );
     </script>
 
-## Loading Code After Page Load
+## <a name="afterload">Loading Code After Page Load</a>
 
 The example above in the **Multiversion Support** section shows how code can later be loaded by nested require() calls. Note that "require" is specified as a dependency for the module. This allows the require method that is passed to the function callback to use the right context to load the modules correctly for multiversion support.
 
-## require.pause()/require.resume() for build layers/bundles
+## <a name="pauseresume">require.pause()/require.resume() for Build Layers</a>
 
 If you want to include many modules that use require.def() in one script, and those modules may depend on each other, then use require.pause() before the set of require calls to prevent require.js from tracing dependencies on each require call. When all the require calls have finished in the file, call require.resume() to have the dependencies properly traced.
 
@@ -409,7 +427,7 @@ Example:
 
 If require.pause() and require.resume() were not used, then the require.def() call to define "alpha" would have tried to load "beta" via another network/file IO call.
 
-## Module Modifiers
+## <a name="modifiers">Module Modifiers</a>
 
 There are some cases where you want to be able to modify the behavior of a module. A common case is setting up a base module but modifying it only if some specific information or state is available.
 
@@ -427,7 +445,7 @@ require.modify() is used for modifiers, and require.modify() can be called in tw
 * Modifier registration.
 * Modifier definition.
 
-### Modifier Registration
+### <a name="modregister">Modifier Registration</a>
 
 If you want to tell require.js that there is a modifier, but not actually load the modifier or the target yet, then just register the modifiers with require.js:
 
@@ -441,7 +459,7 @@ This call tells require.js to load the "my/modifier1" and "my/modifier2" modules
 
 You are not required to register modifiers with require.js. Only do it if you want to avoid loading the target modules and defining the modifiers right away. Otherwise, you can use Modifier Definition.
 
-### Modifier Definition
+### <a name="moddef">Modifier Definition</a>
 
 A modifier definition looks like a normal require.def() module definition, but:
 
@@ -463,7 +481,7 @@ For the example given above in Modifier Registration, where "my/target1" is the
         }
     );
 
-## Rhino Support
+## <a name="rhino">Rhino Support</a>
 
 RequireJS can be used in Rhino, just be sure to load require.js and require/rhino.js before doing any require calls:
 

docs/download.md

@@ -4,25 +4,18 @@
 
 ### 0.8.0
 
-#### require.js
-
-All you need to start using require.js. Does not include i18n, text plugins or rhino support
-Download: [Minified](release/0.8.0/minified/require.js) | [With Comments](release/0.8.0/comments/require.js)
-
-#### require.js with plugins
+* Renamed from RunJS to RequireJS
+* Adds better support for existing JS files
 
-require.js with the i18n and text plugins included.
-Download: [Minified](release/0.8.0/minified/allplugins-require.js) | [With Comments](release/0.8.0/comments/allplugins-require.js)
+#### require.js [Minified](release/0.8.0/minified/require.js) | [With Comments](release/0.8.0/comments/require.js)
 
-### Optimization Tool / Full Source
+All you need to start using require.js. Does not include i18n, text plugins or rhino support. 
 
-A zip file that is the optimization tool for RequireJS. It also includes the full source for require.js and its plugins.
+#### require.js with plugins [Minified](release/0.8.0/minified/allplugins-require.js) | [With Comments](release/0.8.0/comments/allplugins-require.js)
 
-Use this download if you want to use RequireJS in Rhino.
+require.js with the i18n and text plugins included. 
 
-[Download](release/0.8.0/requirejs-0.8.0.zip)
-
-#### jQuery 1.4.1 with require()
+#### jQuery 1.4.2 with require() [Minified](release/0.8.0/minified/require-jquery-1.4.2.js) | [With Comments](release/0.8.0/comments/require-jquery-1.4.2.js)
 
 A build of jQuery with integrated require() support. Just includes the basic RequireJS, does not have the following features:
 
@@ -31,33 +24,32 @@ A build of jQuery with integrated require() support. Just includes the basic Req
 * page load support (it is assumed you will use jQuery's methods)
 * require.modify() support
 
-[Download: Minified](release/0.8.0/minified/require-jquery-1.4.2.js) | [With Comments](release/0.8.0/comments/require-jquery-1.4.2.js)
-
-#### Sample jQuery 1.4.1 project with require()
+#### jQuery 1.4.2 with require() and plugins [Minified](release/0.8.0/minified/require.js) | [With Comments](release/0.8.0/comments/require.js)
 
-A zip file containing a build of jQuery with integrated require() support, with an sample project included to show how it can be used when using jQuery. Does not include these features in RequireJS:
+A build of jQuery with integrated require() support and the i18n and text plugins. Does not include these other RequireJS features:
 
-* i18n, text plugins
 * multiversion support
 * page load support (it is assumed you will use jQuery's methods)
 * require.modify() support
 
-[Download](release/0.8.0/jquery-require-sample.zip)
+<hr>
 
-#### jQuery 1.4.1 with require() and plugins
+#### Sample jQuery 1.4.2 project with require() [Download](release/0.8.0/jquery-require-sample.zip)
 
-A build of jQuery with integrated require() support and the i18n and text plugins. Does not include these other RequireJS features:
+A zip file containing a build of jQuery with integrated require() support, with an sample project included to show how it can be used when using jQuery. Does not include these features in RequireJS:
 
+* i18n, text plugins
 * multiversion support
 * page load support (it is assumed you will use jQuery's methods)
 * require.modify() support
 
-Download: [Minified](release/0.8.0/minified/require.js) | [With Comments](release/0.8.0/comments/require.js)
+<hr>
+
+#### Optimization Tool / Full Source [Download](release/0.8.0/requirejs-0.8.0.zip)
 
-#### Release Notes
+A zip file that is the optimization tool for RequireJS. It also includes the full source for require.js and its plugins.
 
-* Renamed from RunJS to RequireJS
-* Adds better support for existing JS files
+Use this download if you want to use RequireJS in Rhino.
 
 <hr>
 <hr>