[OpenLayers-Commits] r11476 - trunk/doc/library

[commits-20090109 at openlayers.org]

Author: crschmidt
Date: 2011-02-25 02:22:48 -0800 (Fri, 25 Feb 2011)
New Revision: 11476

Modified:
   trunk/doc/library/deploying.rst
Log:
Extending the docs to document how to build smaller CSS and closure
compiler.


Modified: trunk/doc/library/deploying.rst
===================================================================
--- trunk/doc/library/deploying.rst	2011-02-25 10:17:14 UTC (rev 11475)
+++ trunk/doc/library/deploying.rst	2011-02-25 10:22:48 UTC (rev 11476)
@@ -1,5 +1,5 @@
-Deploying
-=========
+Deploying (Shipping OpenLayers in your Application)
+===================================================
 
 OpenLayers comes with pre-configured examples out of the box: simply download
 a release of OpenLayers, and you get a full set of easy to use examples.
@@ -55,7 +55,7 @@
 
 In Windows, from the Start Menu, select Run. Copy the path to build.py from the address bar of the Explorer Window into the text box and then add the name of the configuration file (or blank for the default):
 
- C:\Downloads\OpenLayers-2.6\build\build.py lite
+ C:\\Downloads\\OpenLayers-2.6\\build\\build.py lite
 
 Custom Build Profiles
 +++++++++++++++++++++
@@ -82,19 +82,7 @@
 Profiles are simple to create. You can start by copying library.cfg or lite.cfg
 to something else, e.g. myversion.cfg in the build directory.
 
-The start of any build profile must include the same [first] section used in
-the lite.cfg file::
-
-  [first]
-  OpenLayers/SingleFile.js
-  OpenLayers.js
-  OpenLayers/BaseTypes.js
-  OpenLayers/BaseTypes/Class.js
-  OpenLayers/Util.js
-
-These files are required for the OpenLayers build to function.
-
-Once you have included these files, you should add more files to the 
+To build a profile, you should add files needed for your application to the 
 '[include]' section of the file. The files listed here should be the list of
 files containing any class you use in your application. You can typically find
 these classes by looking through your code for any cases where 'new
@@ -117,7 +105,7 @@
 This will create a much smaller OpenLayers version, suitable for limited
 applications.
 
-Almost all applications can benefit from a custom build profile. OpenLayers
+All applications can benefit from a custom build profile. OpenLayers
 supports many different layer types, but most applications will only use one
 or two, and many applications do not need the full support of many of the
 features in OpenLayers. In order to limit your download time and library
@@ -146,3 +134,89 @@
 As described above, when deploying these files with a single file OpenLayers
 build, they should all live in the same directory: this allows OpenLayers
 to properly find and include them.
+
+Minimizing Build Size
++++++++++++++++++++++
+
+In order to minimize the size of the files delivered to the client, there are
+two important factors: minimizing the size of all downloads (via whitespace
+removal, for example) and delivering compressed data to clients which
+support it.
+
+There are three types of data that OpenLayers uses, and each has a different
+means of compression.
+
+ * Control Images
+
+   Control images are generally PNG images. These images should be compressed
+   with png compression tools like pngcrush to create the minimal png images.
+   The images provided with OpenLayers (both for CSS-styled and non-CSS 
+   styled controls) have had this applied to them, so these images are 
+   already minimized.
+
+ * CSS
+
+   csstidy_ is a library which removes whitespace from CSS stylesheets. 
+   By using csstidy, you can reduce the size of OpenLayers stylesheets
+   by approximately 30%. 
+
+   Releases of OpenLayers beyond 2.10 include CSS tidy stylesheets in
+   the theme directory with .tidy. in the name. To take advantage of 
+   these stylesheets, you should create your map with a null theme,
+   and include the stylesheet directly in the page.
+
+   ::
+        
+        <link rel="stylesheet" href="../theme/default/style.tidy.css" type="text/css" />
+        <script>
+            new OpenLayers.Map("map", {
+                theme: null
+            });    
+        </script>
+
+ * Javascript
+   
+   The singlefile build tools have support for a number of tools which can
+   remove whitespace from Javascript, including jsmin (from Douglas Crockford)
+   and the Closure Compiler (from Google).
+
+   When running the build tool, you can specify using the closure compiler
+   by using the '-c closure' option to the build.py tool. Closure's compiler
+   with the default optimizations gives approximately a 20% savings over
+   jsmin's compression.
+
+   The options available for compression are:
+   
+    * closure
+
+      This requires you to have a closure-compiler.jar in your
+      tools directory. You can do this by fetching the compiler
+      from:
+   
+        http://closure-compiler.googlecode.com/files/compiler-latest.zip
+   
+      Then unzipping that file, and placing compiler.jar into tools
+      and renaming it closure-compiler.jar.
+   
+    * closure_ws
+
+      This uses the closure compiler webservice. This will only work
+      for files source Javascript files which are under 1MB. (Note that
+      the default OpenLayers full build is not under 1MB.)
+   
+    * jsmin
+
+      jsmin is the default compiler, and uses the Python-based
+      jsmin script to compress the Javascript. 
+   
+    * minimize
+
+      This is a simple whitespace removing Python script, designed
+      to fill in when other tools are unavailable.
+   
+    * none
+
+      None will leave the Javascript uncompressed.
+
+
+.. _csstidy: http://csstidy.sourceforge.net/