Index: buildSrc/src/main/groovy/org/gradle/build/docs/UserGuideTransformTask.groovy
===================================================================
--- buildSrc/src/main/groovy/org/gradle/build/docs/UserGuideTransformTask.groovy	(revision 1571)
+++ buildSrc/src/main/groovy/org/gradle/build/docs/UserGuideTransformTask.groovy	(working copy)
@@ -24,6 +24,7 @@
     File snippetsDir
     boolean standalone
     FileCollection classpath;
+    SampleElementValidator validator;
 
     def UserGuideTransformTask(Project project, String name) {
         super(project, name);
@@ -134,14 +135,9 @@
             MarkupBuilder xml = new MarkupBuilder(writer)
             xml.samples {
                 doc.documentElement.depthFirst().findAll { it.name() == 'sample' }.each {Element element ->
+                	validator.validate(element)
                     String id = element.'@id'
-                    if (!id) {
-                        throw new RuntimeException("No id attribute specified for sample.")
-                    }
                     String srcDir = element.'@dir'
-                    if (!srcDir) {
-                        throw new RuntimeException("No dir attribute specified for sample '$id'.")
-                    }
 
                     // This class handles the responsibility of adding the location tips to the first child of first
                     // example defined in the sample.
@@ -149,21 +145,23 @@
                    
                     xml.sample(id: id, dir: srcDir)
 
+                    String title = element.'@title' 
+
+                    Element exampleElement = doc.createElement('example')
+                    Element titleElement = doc.createElement('title')
+               	   	titleElement.appendChild(doc.createTextNode(title))
+               	   	exampleElement.appendChild(titleElement);
+                    
                     element.children().each {Element child ->
                         if (child.name() == 'sourcefile') {
                             String file = child.'@file'
-                            if (!file) {
-                                throw new RuntimeException("No file attribute specified for source file in sample '$id'.")
-                            }
-
-                            Element exampleElement = doc.createElement('example')
-
-                            Element titleElement = doc.createElement('title')
-                            Element filenameElement = doc.createElement('filename')
-                            filenameElement.appendChild(doc.createTextNode(file))
-                            titleElement.appendChild(filenameElement)
-                            exampleElement.appendChild(titleElement)
-
+                           
+                            Element sourcefileTitle = doc.createElement("para")
+                    		Element commandElement = doc.createElement('filename')
+                        	commandElement.appendChild(doc.createTextNode(file))
+                        	sourcefileTitle.appendChild(commandElement)
+                        	exampleElement.appendChild(sourcefileTitle);
+                            
                             Element programListingElement = doc.createElement('programlisting')
                             File srcFile
                             String snippet = child.'@snippet'
@@ -176,24 +174,18 @@
                             exampleElement.appendChild(programListingElement)
 
                             locationHandler.processSampleLocation(exampleElement)
-                            element.parentNode.insertBefore(exampleElement, element)
                            
                         } else if (child.name() == 'output') {
                             String args = child.'@args'
-                            if (args == null) {
-                                throw new RuntimeException("No args attribute specified for output for sample '$id'.")
-                            }
-
+                           
                             xml.sample(id: id, dir: srcDir, args: args)
 
-                            Element exampleElement = doc.createElement('example')
-
-                            Element titleElement = doc.createElement('title')
-                            titleElement.appendChild(doc.createTextNode("Output of "))
+                            Element outputTitle = doc.createElement("para")
+                            outputTitle.appendChild(doc.createTextNode("Output of "))
                             Element commandElement = doc.createElement('userinput')
                             commandElement.appendChild(doc.createTextNode("gradle $args"))
-                            titleElement.appendChild(commandElement)
-                            exampleElement.appendChild(titleElement)
+                            outputTitle.appendChild(commandElement)
+                            exampleElement.appendChild(outputTitle)
 
                             Element screenElement = doc.createElement('screen')
                             File srcFile = new File(sourceFile.parentFile, "../../../src/samples/userguideOutput/${id}.out")
@@ -201,14 +193,13 @@
                             exampleElement.appendChild(screenElement)
 
                             locationHandler.processSampleLocation(exampleElement)
-                            element.parentNode.insertBefore(exampleElement, element)
                         } else if (child.name() == 'layout') {
-                            Element figureElement = doc.createElement('figure')
-                            Element titleElement = doc.createElement('title')
-                            figureElement.appendChild(titleElement)
-                            titleElement.appendChild(doc.createTextNode('Build layout'))
+                        	Element outputTitle = doc.createElement("para")
+                    		outputTitle.appendChild(doc.createTextNode("Build layout"))
+                    		exampleElement.appendChild(outputTitle)
+                    		
                             Element programListingElement = doc.createElement('programlisting')
-                            figureElement.appendChild(programListingElement)
+                            exampleElement.appendChild(programListingElement)
                             StringBuilder content = new StringBuilder()
                             content.append("${srcDir.tokenize('/').last()}/\n")
                             List stack = []
@@ -219,7 +210,7 @@
                                 }
                                 File file = new File(snippetsDir, "$srcDir/$fileName")
                                 if (!file.exists()) {
-                                    throw new RuntimeException("Sample file $file does not exist.")
+                                    throw new RuntimeException("Sample file $file does not exist for sample ${id}.")
                                 }
                                 List context = fileName.tokenize('/')
 
@@ -235,14 +226,10 @@
                             }
                             programListingElement.appendChild(doc.createTextNode(content.toString()))
                            
-                            locationHandler.processSampleLocation(figureElement)
-                            element.parentNode.insertBefore(figureElement, element)
-                           
-                        } else {
-                            throw new RuntimeException("Unrecognised sample type ${child.name()} found.")
+                            locationHandler.processSampleLocation(exampleElement)
                         }
                     }
-
+                    element.parentNode.insertBefore(exampleElement, element)
                     element.parentNode.removeChild(element)
                 }
             }
Index: src/docs/stylesheets/userGuideHtmlCommon.xsl
===================================================================
--- src/docs/stylesheets/userGuideHtmlCommon.xsl	(revision 1571)
+++ src/docs/stylesheets/userGuideHtmlCommon.xsl	(working copy)
@@ -22,7 +22,7 @@
     <xsl:param name="css.decoration">0</xsl:param>
 
     <xsl:param name="generate.toc">
-        book toc,title
+        book toc,title,example
     </xsl:param>
 
     <xsl:param name="formal.title.placement">
Index: src/docs/userguide/plugins.xml
===================================================================
--- src/docs/userguide/plugins.xml	(revision 1571)
+++ src/docs/userguide/plugins.xml	(working copy)
@@ -38,7 +38,7 @@
         </itemizedlist>
         <para>Let's check this out:
         </para>
-        <sample id="pluginIntro" dir="userguide/tutorial/pluginIntro">
+        <sample id="pluginIntro" dir="userguide/tutorial/pluginIntro" title="Using plugin">
             <sourcefile file="build.gradle"/>
             <output args="-q check"/>
         </sample>
@@ -77,7 +77,7 @@
             code). The default location for the output of those tasks is the directory <literal>build/classes</literal>.
             What if you want to change this? Let's try:
         </para>
-        <sample id="pluginConfig" dir="userguide/tutorial/pluginConfig">
+        <sample id="pluginConfig" dir="userguide/tutorial/pluginConfig" title="Configuring a plugin">
             <sourcefile file="build.gradle"/>
             <output args="-q check"/>
         </sample>
@@ -90,7 +90,7 @@
         <para>Gradles tasks are usually <emphasis>convention aware</emphasis>. A plugin can add a convention object to
             your build. It can also map certain values of this convention object to task properties.
         </para>
-        <sample id="pluginConvention" dir="userguide/tutorial/pluginConvention">
+        <sample id="pluginConvention" dir="userguide/tutorial/pluginConvention" title="Plugin convention object">
             <sourcefile file="build.gradle"/>
             <output args="-q check"/>
         </sample>
Index: src/docs/userguide/projectTaskApi.xml
===================================================================
--- src/docs/userguide/projectTaskApi.xml	(revision 1571)
+++ src/docs/userguide/projectTaskApi.xml	(working copy)
@@ -23,7 +23,7 @@
         <para>Let's try this out and try to access the <literal>name</literal> property of the
             <classname>Project</classname> object.
         </para>
-        <sample id="projectApi" dir="userguide/tutorial/projectApi">
+        <sample id="projectApi" dir="userguide/tutorial/projectApi" title="Accessing property of the Project object">
             <sourcefile file="build.gradle"/>
             <output args="-q check"/>
         </sample>
@@ -103,7 +103,7 @@
             </table>
 
             <para>Below is a sample build which demonstrates some of these properties.</para>
-            <sample id="projectCoreProperties" dir="userguide/tutorial/projectCoreProperties">
+            <sample id="projectCoreProperties" dir="userguide/tutorial/projectCoreProperties" title="Project properties">
                 <layout>
                     build.gradle
                     subProject
Index: src/docs/userguide/tasks.xml
===================================================================
--- src/docs/userguide/tasks.xml	(revision 1571)
+++ src/docs/userguide/tasks.xml	(working copy)
@@ -13,15 +13,15 @@
             There are a few variations on this style, which you may need to use in certain situations. For example,
             the keyword style does not work in expressions.
         </para>
-        <sample id="defineAsExpression" dir="userguide/tasks/defineAsExpression">
+        <sample id="defineAsExpression" dir="userguide/tasks/defineAsExpression" title="Defining tasks">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>You can also use strings for the task names:</para>
-        <sample id="defineUsingStringTaskNames" dir="userguide/tasks/defineUsingStringTaskNames">
+        <sample id="defineUsingStringTaskNames" dir="userguide/tasks/defineUsingStringTaskNames" title="Defining tasks - using strings">
             <sourcefile file="build.gradle"/>
         </sample>
-        <para>There is an alternate syntax for defining tasks, which you may prefer to use:</para>
-        <sample id="addToTaskContainer" dir="userguide/tasks/addToTaskContainer">
+        <para>There is an alternative syntax for defining tasks, which you may prefer to use:</para>
+        <sample id="addToTaskContainer" dir="userguide/tasks/addToTaskContainer" title="Defining tasks with alternative syntax">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Here we add tasks to the <literal>tasks</literal> collection. Have a look at
@@ -34,17 +34,17 @@
             or use them for dependencies. There are a number of ways you can do this. Firstly, each task is available as
             a property of the project, using the task name as the property name:
         </para>
-        <sample id="accessAsProperty" dir="userguide/tasks/accessAsProperty">
+        <sample id="accessAsProperty" dir="userguide/tasks/accessAsProperty" title="Accessing tasks as properties">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Tasks are also available through the <literal>tasks</literal> collection.</para>
-        <sample id="accessFromTaskContainer" dir="userguide/tasks/accessFromTaskContainer">
+        <sample id="accessFromTaskContainer" dir="userguide/tasks/accessFromTaskContainer" title="Accessing tasks via tasks collection">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>You can access tasks from any project using the task's path using the <literal>tasks.getByPath()</literal>
             method. You can call the <literal>getByPath()</literal> method with a task name, or a relative path, or an
             absolute path.</para>
-        <sample id="accessUsingPath" dir="userguide/tasks/accessUsingPath">
+        <sample id="accessUsingPath" dir="userguide/tasks/accessUsingPath" title="Accessing tasks by path">
             <sourcefile file="build.gradle"/>
             <output args="-q hello"/>
         </sample>
@@ -59,14 +59,14 @@
                 </para>
             </footnote>
         </para>
-        <sample id="declareTask" dir="userguide/tasks/configureUsingClosure">
+        <sample id="declareTask" dir="userguide/tasks/configureUsingClosure" title="Creating a copy task">
             <sourcefile file="build.gradle" snippet="declare-task"/>
         </sample>
         <para>This creates a copy task with no default behavior.
             The task can be configured using its API (see <apilink class="org.gradle.api.tasks.Copy"/>).
 			The following examples show several different ways to achieve the same configuration.
         </para>
-        <sample id="configureUsingVar" dir="userguide/tasks/configureUsingVar">
+        <sample id="configureUsingVar" dir="userguide/tasks/configureUsingVar" title="Configuring a task - various ways">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>This is similar to the way we would normally configure objects in Java. You have to repeat the context
@@ -75,7 +75,7 @@
         </para>
         <para>There is a more convenient way of doing this.
         </para>
-        <sample id="configureUsingLiterateStyle" dir="userguide/tasks/configureUsingLiterateStyle">
+        <sample id="configureUsingLiterateStyle" dir="userguide/tasks/configureUsingLiterateStyle" title="Configuring a task - fluent interface">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>You might know this approach from the Hibernates Criteria Query API or JMock. Of course the API of a task
@@ -86,7 +86,7 @@
         <para>But there is yet another way of configuring a task. It also preserves the context and it is arguably the
             most readable. It is usually our favorite.
         </para>
-        <sample id="configureUsingClosure" dir="userguide/tasks/configureUsingClosure">
+        <sample id="configureUsingClosure" dir="userguide/tasks/configureUsingClosure" title="Configuring a task - with closure">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>This works for <emphasis>any</emphasis> task. Line 3 of the example is just a shortcut for the
@@ -94,14 +94,14 @@
             <literal>getByName()</literal> method, this closure is applied to <emphasis>configure</emphasis> the task.
         </para>
         <para>There is a slightly different ways of doing this.</para>
-        <sample id="configureUsingConfigure" dir="userguide/tasks/configureUsingConfigure">
+        <sample id="configureUsingConfigure" dir="userguide/tasks/configureUsingConfigure" title="Configuring a task - with configure() method">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Every task has a <literal>configure()</literal> method, which you can pass a closure for configuring the task.
             Gradle uses this style for configuring objects in many places, not just for tasks.
         </para>
         <para>You can also use a configuration closure when you define a task.</para>
-        <sample id="defineAndConfigure" dir="userguide/tasks/defineAndConfigure">
+        <sample id="defineAndConfigure" dir="userguide/tasks/defineAndConfigure" title="Defining a task with closure">
             <sourcefile file="build.gradle" snippet="no-description"/>
         </sample>
     </section>
@@ -117,14 +117,14 @@
             to
             <literal>projectB:taskY</literal>:
         </para>
-        <sample id="addDependencyUsingPath" dir="userguide/tasks/addDependencyUsingPath">
+        <sample id="addDependencyUsingPath" dir="userguide/tasks/addDependencyUsingPath" title="Adding dependency on task from another project">
             <sourcefile file="build.gradle"/>
             <output args="-q taskX"/>
         </sample>
         <para>Instead of using a task name, you can define a dependency using a
             <classname>Task</classname> object, as shown in this example:
         </para>
-        <sample id="addDependencyUsingTask" dir="userguide/tasks/addDependencyUsingTask">
+        <sample id="addDependencyUsingTask" dir="userguide/tasks/addDependencyUsingTask" title="Adding dependency using task object">
             <sourcefile file="build.gradle"/>
             <output args="-q taskX"/>
         </sample>
@@ -134,7 +134,7 @@
             as dependencies of the task. The following example adds a dependency from <literal>taskX</literal>
             to all the tasks in the project whose name starts with <literal>lib</literal>:
         </para>
-        <sample id="addDependencyUsingClosure" dir="userguide/tasks/addDependencyUsingClosure">
+        <sample id="addDependencyUsingClosure" dir="userguide/tasks/addDependencyUsingClosure" title="Adding dependency using closure">
             <sourcefile file="build.gradle"/>
             <output args="-q taskX"/>
         </sample>
@@ -145,7 +145,7 @@
         <para>You can add a description to your task. This description is for example displayed when executing
             <code>gradle -t</code>.
         </para>
-        <sample id="describeTask" dir="userguide/tasks/defineAndConfigure">
+        <sample id="describeTask" dir="userguide/tasks/defineAndConfigure" title="Adding a description to a task">
             <sourcefile file="build.gradle"/>
         </sample>
     </section>
@@ -154,7 +154,7 @@
         <para>Sometimes you want to replace a task. For example if you want to exchange a task added by the Java Plugin
             with a custom task of a different type. You can achieve this with:
         </para>
-        <sample id="replaceTask" dir="userguide/tutorial/replaceTask">
+        <sample id="replaceTask" dir="userguide/tutorial/replaceTask" title="Overwriting a task">
             <sourcefile file="build.gradle"/>
             <output args="-q copy"/>
         </sample>
@@ -168,7 +168,7 @@
         <para>Sometimes you want to have a task which behavior depends on a large or infinite number value range
             of parameters. A very nice and expressive way to provide such tasks are task rules: 
         </para>
-        <sample id="taskRule" dir="userguide/tasks/addRules">
+        <sample id="taskRule" dir="userguide/tasks/addRules" title="Task rule">
             <sourcefile file="build.gradle" snippet="task-rule"/>
             <output args="-q pingServer1"/>
         </sample>
@@ -178,7 +178,7 @@
         <para>Rules not just work for calling tasks from the command line. You can also create dependsOn relations
             on rule based tasks:
         </para>
-        <sample id="taskRuleDependsOn" dir="userguide/tasks/addRules">
+        <sample id="taskRuleDependsOn" dir="userguide/tasks/addRules" title="Dependency on rule based tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q groupPing"/>
         </sample>
Index: src/docs/userguide/logging.xml
===================================================================
--- src/docs/userguide/logging.xml	(revision 1571)
+++ src/docs/userguide/logging.xml	(working copy)
@@ -116,7 +116,7 @@
             property to a build script, which is an instance of a slf4j logger. Here is the code of the logging
             integration test, which shows you how to use the logger, as well as working with standard out redirection.
         </para>
-        <sample id="logging" dir="logging/project1">
+        <sample id="logging" dir="logging/project1" title="Sending your own log message">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Strictly speaking, <emphasis>QUIET</emphasis> and <emphasis>LIFECYCLE</emphasis> are no log levels, but they are markers. But logically Gradle
Index: src/docs/userguide/artifactDependenciesTutorial.xml
===================================================================
--- src/docs/userguide/artifactDependenciesTutorial.xml	(revision 1571)
+++ src/docs/userguide/artifactDependenciesTutorial.xml	(working copy)
@@ -29,15 +29,15 @@
             with a name. You can use them to declare the external dependencies your project has, or to declare the
             artifacts which your project publishes.</para>
         <para>To define a configuration:</para>
-        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration">
+        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Definition of a configuration">
             <sourcefile file="build.gradle" snippet="define-configuration"/>
         </sample>
         <para>To access a configuration:</para>
-        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration">
+        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Accessing a configuration">
             <sourcefile file="build.gradle" snippet="lookup-configuration"/>
         </sample>
         <para>To configure a configuration:</para>
-        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration">
+        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Configuration of a configuration">
             <sourcefile file="build.gradle" snippet="configure-configuration"/>
         </sample>
     </section>
@@ -46,20 +46,20 @@
         <title>Repositories</title>
         <para>Artifacts are stored in <firstterm>repositories</firstterm>.</para>
         <para>To use maven central repository:</para>
-        <sample id="defineRepository" dir="userguide/artifacts/defineRepository">
+        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Usage of Maven central repository">
             <sourcefile file="build.gradle" snippet="maven-central"/>
         </sample>
         <para>To use a local directory:</para>
-        <sample id="defineRepository" dir="userguide/artifacts/defineRepository">
+        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Usage of a local directory">
             <sourcefile file="build.gradle" snippet="flat-dir"/>
         </sample>
         <para>You can also use any Ivy resolver. You can have multiple repositories.</para>
         <para>To access a repository:</para>
-        <sample id="defineRepository" dir="userguide/artifacts/defineRepository">
+        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Accessing a repository">
             <sourcefile file="build.gradle" snippet="lookup-resolver"/>
         </sample>
         <para>To configure a repository:</para>
-        <sample id="defineRepository" dir="userguide/artifacts/defineRepository">
+        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Configuration of a repository">
             <sourcefile file="build.gradle" snippet="configure-resolver"/>
         </sample>
     </section>
@@ -67,13 +67,13 @@
     <section>
         <title>External dependencies</title>
         <para>To define an external dependency, you add a dependency to a configuration:</para>
-        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies">
+        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies" title="Definition of an external dependency">
             <sourcefile file="build.gradle" snippet="define-dependency"/>
         </sample>
         <para><literal>group</literal> and <literal>version</literal> are optional</para>
         <para>TBD - configuring an external dependency</para>
         <para>To use the external dependencies of a configuration:</para>
-        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies">
+        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies"  title="Usage of external dependency of a configuration">
             <sourcefile file="build.gradle" snippet="use-configuration"/>
             <output args="-q listJars"/>
         </sample>
Index: src/docs/userguide/artifactMngmt.xml
===================================================================
--- src/docs/userguide/artifactMngmt.xml	(revision 1571)
+++ src/docs/userguide/artifactMngmt.xml	(working copy)
@@ -29,7 +29,7 @@
         <para>Like dependencies, artifacts are grouped by configurations. In fact, a configuration can contain
             both, artifacts and dependencies, at the same time. To assign an artifact to a configuration, you can write:
         </para>
-        <sample id="assignArtifact" dir="userguide/artifacts/uploading">
+        <sample id="assignArtifact" dir="userguide/artifacts/uploading" title="Assignment of an artifact to a configuration">
             <sourcefile file="build.gradle" snippet="assign-artifact"/>
         </sample>
         <para>What do you gain by assigning an artifact to a configuration? For each configuration (also for the custom
@@ -57,7 +57,7 @@
             are not even capable of uploading, there are just capable of reading from a repository. Here is an example how
             you can configure the upload task of a configuration:
         </para>
-        <sample id="uploading" dir="userguide/artifacts/uploading">
+        <sample id="uploading" dir="userguide/artifacts/uploading" title="Configuration of the upload task">
             <sourcefile file="build.gradle" snippet="uploading"/>
         </sample>
         <para>As you can see, you can either use a reference to an exisiting repository or create a new repository.
@@ -102,7 +102,7 @@
             <para>Let's assume your project produces just the default jar file. Now you want to deploy this jar file to
                 a remote Maven repository.
             </para>
-            <sample id="uploadFile" dir="userguide/artifacts/maven">
+            <sample id="uploadFile" dir="userguide/artifacts/maven" title="Upload of file to remote Maven repository">
                 <sourcefile file="build.gradle" snippet="upload-file"/>
             </sample>
             <para>That is all. Calling the
@@ -118,9 +118,9 @@
                     <para>It is planned for a future release to provide out-of-the-box support for this
                     </para>
                 </footnote>
-                For example to use the ssh protocoll you can do:
+                For example to use the ssh protocol you can do:
             </para>
-            <sample id="uploadWithSsh" dir="userguide/artifacts/maven">
+            <sample id="uploadWithSsh" dir="userguide/artifacts/maven" title="Upload of file via SSH">
                 <sourcefile file="build.gradle" snippet="upload-with-ssh"/>
             </sample>
             <para>There are many configuration options for the Maven deployer. The configuration is done via a Groovy builder.
@@ -258,7 +258,7 @@
                 <para>You might want the artifact deployed to the maven repository to have a different version or name than
                     the artifact generated by Gradle. To customize these you can do:
                 </para>
-                <sample id="customizePom" dir="userguide/artifacts/maven">
+                <sample id="customizePom" dir="userguide/artifacts/maven" title="Customization of pom">
                     <sourcefile file="build.gradle" snippet="customize-pom"/>
                 </sample>
                 <para>To learn about all the customizable attributes of a pom have a look here: <apilink class="org.gradle.api.artifacts.maven.MavenPom"/>.
@@ -267,7 +267,7 @@
                 <para>To customize the settings for the maven Installer (see <xref
                         linkend='sub:installing_to_the_local_repository'/>), you can do:
                 </para>
-                <sample id="customizeInstaller" dir="userguide/artifacts/maven">
+                <sample id="customizeInstaller" dir="userguide/artifacts/maven" title="Customization of Maven installer">
                     <sourcefile file="build.gradle" snippet="customize-installer"/>
                 </sample>
             </section>
@@ -279,7 +279,7 @@
                     you want to publish to a Maven repository. The MavenDeployer and the MavenInstaller
                     both provide an API for this:
                 </para>
-                <sample id="multiplePoms" dir="userguide/artifacts/maven">
+                <sample id="multiplePoms" dir="userguide/artifacts/maven" title="Generation of multiple poms">
                     <sourcefile file="build.gradle" snippet="multiple-poms"/>
                 </sample>
                 <para>You need to declare a filter for each artifact you want to publish. This filter defines a boolean expression for
@@ -299,7 +299,7 @@
                     <apilink class="org.gradle.api.artifacts.maven.Conf2ScopeMappingContainer"/>
                     to learn more. To access the mapping configuration you can say:
                 </para>
-                <sample id="mappings" dir="userguide/artifacts/maven">
+                <sample id="mappings" dir="userguide/artifacts/maven" title="Accessing a mapping configuration">
                     <sourcefile file="build.gradle" snippet="mappings"/>
                 </sample>
                 <para>Gradle exclude rules are converted to Maven excludes if possible. Such a conversion is possible if in
Index: src/docs/userguide/osgi.xml
===================================================================
--- src/docs/userguide/osgi.xml	(revision 1571)
+++ src/docs/userguide/osgi.xml	(working copy)
@@ -65,7 +65,7 @@
             information is used to specify version information for the <emphasis>Import-Package</emphasis>
             value. Beside the explicit properties of the <literal>OsgiManifest</literal> object you can add instructions.
         </para>
-        <sample id="osgi" dir="userguide/tutorial/osgi">
+        <sample id="osgi" dir="userguide/tutorial/osgi" title="Configuration of OSGi MANIFEST.MF file">
             <sourcefile file="build.gradle" snippet="configure-jar"/>
         </sample>
         <para>The first argument of the instruction call is the key of the property. The other arguments form the value.
Index: src/docs/userguide/buildscripts.xml
===================================================================
--- src/docs/userguide/buildscripts.xml	(revision 1571)
+++ src/docs/userguide/buildscripts.xml	(working copy)
@@ -12,7 +12,7 @@
         <para>In Gradle the most basic building block is the <firstterm>task</firstterm>. The tasks for your build are
             defined in the build script. To try this out, create the following build script named <filename>build.gradle</filename>.
         </para>
-        <sample id="hello" dir="userguide/tutorial/hello">
+        <sample id="hello" dir="userguide/tutorial/hello" title="The first build script">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>In a command-line shell, enter into the containing directory and execute the build script by running
@@ -26,7 +26,7 @@
                 options which affect Gradle's output.
             </para>
         </tip>
-        <sample id="hello" dir="userguide/tutorial/hello">
+        <sample id="hello" dir="userguide/tutorial/hello" title="Execution of a build script">
             <output args="-q hello"/>
         </sample>
         <para>What's going on here? This build file defines a single task, called <literal>hello</literal>, and
@@ -47,12 +47,12 @@
         <title>Build scripts are code</title>
         <para>Gradle's build scripts expose to you the full power of Groovy. As an appetizer, have a look at this:
         </para>
-        <sample id="upper" dir="userguide/tutorial/upper">
+        <sample id="upper" dir="userguide/tutorial/upper" title="Using Groovy in Gradle's tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q upper"/>
         </sample>
         <para>or</para>
-        <sample id="count" dir="userguide/tutorial/count">
+        <sample id="count" dir="userguide/tutorial/count" title="Using Groovy in Gradle's tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q count"/>
         </sample>
@@ -61,12 +61,12 @@
         <title>Task dependencies</title>
         <para>As you probably have guessed, you can declare dependencies between your tasks.
         </para>
-        <sample id="intro" dir="userguide/tutorial/intro">
+        <sample id="intro" dir="userguide/tutorial/intro" title="Declaration of dependencies between tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q intro"/>
         </sample>
         <para>To add a dependency, the corresponding task does not need to exist.</para>
-        <sample id="lazyDependsOn" dir="userguide/tutorial/lazyDependsOn">
+        <sample id="lazyDependsOn" dir="userguide/tutorial/lazyDependsOn" title="Lazy dependsOn - the other task does not exist (yet)">
             <sourcefile file="build.gradle"/>
             <output args="-q taskX"/>
         </sample>
@@ -81,7 +81,7 @@
         <para>The power of Groovy can be used for more than defining what a task does. For example, you can also use it
             to dynamically create tasks.
         </para>
-        <sample id="dynamic" dir="userguide/tutorial/dynamic">
+        <sample id="dynamic" dir="userguide/tutorial/dynamic" title="Dynamic creation of a task">
             <sourcefile file="build.gradle"/>
             <output args="-q task_1"/>
         </sample>
@@ -91,12 +91,12 @@
         <para>Once tasks are created they can be accessed via an <emphasis>API</emphasis>. This is different to Ant. For
             example you can create additional dependencies.
         </para>
-        <sample id="dynamicDepends" dir="userguide/tutorial/dynamicDepends">
+        <sample id="dynamicDepends" dir="userguide/tutorial/dynamicDepends" title="Accessing a task via API - adding a dependency">
             <sourcefile file="build.gradle"/>
             <output args="-q task_0"/>
         </sample>
         <para>Or you can add behavior to an existing task.</para>
-        <sample id="helloEnhanced" dir="userguide/tutorial/helloEnhanced">
+        <sample id="helloEnhanced" dir="userguide/tutorial/helloEnhanced" title="Accessing a task via API - adding behaviour">
             <sourcefile file="build.gradle"/>
             <output args="-q hello"/>
         </sample>
@@ -111,7 +111,7 @@
         <para>As you might have noticed in the previous examples, there is a convenient notation for accessing an
             <emphasis>existing</emphasis> task. Each task is available as a property of the build script:
         </para>
-        <sample id="helloWithShortCut" dir="userguide/tutorial/helloWithShortCut">
+        <sample id="helloWithShortCut" dir="userguide/tutorial/helloWithShortCut" title="Accessing task as a property of the build script">
             <sourcefile file="build.gradle"/>
             <output args="-q hello"/>
         </sample>
@@ -122,7 +122,7 @@
         <title>Dynamic task properties</title>
         <para>You can assign arbitrary <emphasis>new</emphasis> properties to any task.
         </para>
-        <sample id="dynamicProperties" dir="userguide/tutorial/dynamicProperties">
+        <sample id="dynamicProperties" dir="userguide/tutorial/dynamicProperties" title="Assigning properties to a task">
             <sourcefile file="build.gradle"/>
             <output args="-q showProps"/>
         </sample>
@@ -147,7 +147,7 @@
             tasks from Gradle is as convenient and more powerful than using Ant tasks from a
             <filename>build.xml</filename> file. Let's look at an example:
         </para>
-        <sample id="antChecksum" dir="userguide/tutorial/antChecksum">
+        <sample id="antChecksum" dir="userguide/tutorial/antChecksum" title="Using AntBuilder to execute ant.checksum target">
             <sourcefile file="build.gradle"/>
             <output args="-q checksum"/>
         </sample>
@@ -177,7 +177,7 @@
         <para>Gradle scales in how you can organize your build logic. The first level of organizing your build logic for
             the example above, is extracting a method.
         </para>
-        <sample id="antChecksumWithMethod" dir="userguide/tutorial/antChecksumWithMethod">
+        <sample id="antChecksumWithMethod" dir="userguide/tutorial/antChecksumWithMethod" title="Using methods to organize your build logic">
             <sourcefile file="build.gradle"/>
             <output args="-q checksum"/>
         </sample>
@@ -190,7 +190,7 @@
         <title>Default tasks</title>
         <para>Gradle allows you to define one or more default tasks for your build.
         </para>
-        <sample id="defaultTasks" dir="userguide/tutorial/defaultTasks">
+        <sample id="defaultTasks" dir="userguide/tutorial/defaultTasks" title="Defining a default tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q"/>
         </sample>
@@ -207,15 +207,13 @@
             if the release task is part of the tasks to be executed. Depending on this you can assign different values
             to some variables.
         </para>
-        <sample id="configByDagNoRelease" dir="userguide/tutorial/configByDag">
+        <para>In the following example, execution of <literal>distribution</literal> and <literal>release</literal> tasks results in different value of <literal>version</literal> variable.</para>
+        <sample id="configByDagNoRelease" dir="userguide/tutorial/configByDag" title="Different outcomes of build depending on chosen tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q distribution"/>
-        </sample>
-        <para>Now let's try running the <literal>release</literal> task:</para>
-        <sample id="configByDag" dir="userguide/tutorial/configByDag">
             <output args="-q release"/>
         </sample>
-        <para>The important thing is, that the fact that the release task has been choosen, has an effect
+        <para>The important thing is, that the fact that the release task has been chosen, has an effect
             <emphasis>before</emphasis> the release task gets executed. Nor has the release task to be the
             <emphasis>primary</emphasis> task (i.e. the task passed to the <command>gradle</command> command).
         </para>
Index: src/docs/userguide/potentialTraps.xml
===================================================================
--- src/docs/userguide/potentialTraps.xml	(revision 1571)
+++ src/docs/userguide/potentialTraps.xml	(working copy)
@@ -5,7 +5,7 @@
         <para>For Gradle users it is important to understand how Groovy deals with script variables. Groovy has two types
             of script variables. One with a local scope and one with a script wide scope.
         </para>
-        <sample id="scope" dir="userguide/tutorial">
+        <sample id="scope" dir="userguide/tutorial" title="Variables scope: local and script wide">
             <sourcefile file="scope.groovy"/>
             <output args=""/>
         </sample>
@@ -23,7 +23,7 @@
         <para>It is important to keep in mind that Gradle has a distinct configuration and execution phase (see 
             <xref linkend='build_lifecycle'/>).
         </para>
-        <sample id="mkdirTrap" dir="userguide/tutorial/mkdirTrap">
+        <sample id="mkdirTrap" dir="userguide/tutorial/mkdirTrap" title="Distinct configuration and execution phase">
             <sourcefile file="build.gradle"/>
             <output args="-q compile"/>
         </sample>
Index: src/docs/userguide/multiproject.xml
===================================================================
--- src/docs/userguide/multiproject.xml	(revision 1571)
+++ src/docs/userguide/multiproject.xml	(working copy)
@@ -13,7 +13,7 @@
             <para>We have the following project tree. This is a multi-project build with a root project
                 <literal>water</literal> and a subproject <literal>bluewhale</literal>.
             </para>
-            <sample id="multiprojectFirstExample" dir="userguide/multiproject/firstExample/water" includeLocation="true">
+            <sample id="multiprojectFirstExample" dir="userguide/multiproject/firstExample/water" includeLocation="true" title="Multi-project tree - water &amp; bluewhale projects">
                 <layout>
                     build.gradle
                     settings.gradle
@@ -21,12 +21,12 @@
                 </layout>
                 <sourcefile file="settings.gradle"/>
             </sample>
-            <para>And where is the build script for the bluewhale project? In Gradle build scripts are optional.
+            <para>And where is the build script for the <literal>bluewhale</literal> project? In Gradle build scripts are optional.
                 Obviously for a single project build, a project without a build script doesn't make much sense. For
-                multiproject builds the situation is different. Let's look at the build script for the water project and
+                multiproject builds the situation is different. Let's look at the build script for the <literal>water</literal> project and
                 execute it:
             </para>
-            <sample id="multiprojectFirstExample" dir="userguide/multiproject/firstExample/water">
+            <sample id="multiprojectFirstExample" dir="userguide/multiproject/firstExample/water" title="Build script of water (parent) project">
                 <sourcefile file="build.gradle"/>
                 <output args="-q hello"/>
             </sample>
@@ -36,11 +36,11 @@
                 call <firstterm>cross project configuration</firstterm>. Gradle implements this via
                 <firstterm>configuration injection</firstterm>.
             </para>
-            <para>We are not that happy with the build script of the water project. It is inconvenient to add the task
+            <para>We are not that happy with the build script of the <literal>water</literal>  project. It is inconvenient to add the task
                 explicitly for every project. We can do better. Let's first add another project called
                 <literal>krill</literal> to our multi-project build.
             </para>
-            <sample id="multiprojectAddKrill" dir="userguide/multiproject/addKrill/water" includeLocation="true">
+            <sample id="multiprojectAddKrill" dir="userguide/multiproject/addKrill/water" includeLocation="true" title="Multi-project tree - water, bluewhale  &amp; krill projects">
                 <layout>
                     build.gradle
                     settings.gradle
@@ -49,8 +49,8 @@
                 </layout>
                 <sourcefile file="settings.gradle"/>
             </sample>
-            <para>Now we rewrite the water build script and boil it down to a single line.</para>
-            <sample id="multiprojectAddKrill" dir="userguide/multiproject/addKrill/water">
+            <para>Now we rewrite the <literal>water</literal> build script and boil it down to a single line.</para>
+            <sample id="multiprojectAddKrill" dir="userguide/multiproject/addKrill/water" title="Water project build script">
                 <sourcefile file="build.gradle"/>
                 <output args="-q hello"/>
             </sample>
@@ -75,7 +75,7 @@
         </para>
         <section>
             <title>Defining common behavior</title>
-            <sample id="multiprojectUseSubprojects" dir="userguide/multiproject/useSubprojects/water">
+            <sample id="multiprojectUseSubprojects" dir="userguide/multiproject/useSubprojects/water" title="Defining common behaviour of all projects and subprojects">
                 <sourcefile file="build.gradle"/>
                 <output args="-q hello"/>
             </sample>
@@ -85,9 +85,9 @@
             <para>You can add specific behavior on top of the common behavior. Usually we put the project specific
                 behavior in the build script of the project where we want to apply this specific behavior. But as we
                 have already seen, we don't have to do it this way. We could add project specific behavior for the
-                bluewhale project like this:
+                <literal>bluewhale</literal> project like this:
             </para>
-            <sample id="multiprojectSubprojectsAddFromTop" dir="userguide/multiproject/subprojectsAddFromTop/water">
+            <sample id="multiprojectSubprojectsAddFromTop" dir="userguide/multiproject/subprojectsAddFromTop/water" title="Defining specific behaviour for particular project">
                 <sourcefile file="build.gradle"/>
                 <output args="-q hello"/>
             </sample>
@@ -95,7 +95,7 @@
                 project. Let's refactor and also add some project specific behavior to the <literal>krill</literal>
                 project.
             </para>
-            <sample id="multiprojectSpreadSpecifics" dir="userguide/multiproject/spreadSpecifics/water" includeLocation="true">
+            <sample id="multiprojectSpreadSpecifics" dir="userguide/multiproject/spreadSpecifics/water" includeLocation="true" title="Defining specific behaviour for project krill">
                 <layout>
                     build.gradle
                     settings.gradle
@@ -119,7 +119,7 @@
             </para>
             <section id='ssub:filtering_by_name'>
                 <title>Filtering by name</title>
-                <sample id="multiprojectAddTropical" dir="userguide/multiproject/addTropical/water" includeLocation="true">
+                <sample id="multiprojectAddTropical" dir="userguide/multiproject/addTropical/water" includeLocation="true" title="Adding custom behaviour to some projects (filtered by project name)">
                     <layout>
                         build.gradle
                         settings.gradle
@@ -141,7 +141,7 @@
                 <title>Filtering by properties</title>
                 <para>Using the project name for filtering is one option. Using dynamic project properties is another.
                 </para>
-                <sample id="multiprojectTropicalWithProperties" dir="userguide/multiproject/tropicalWithProperties/water" includeLocation="true">
+                <sample id="multiprojectTropicalWithProperties" dir="userguide/multiproject/tropicalWithProperties/water" includeLocation="true" title="Adding custom behaviour to some projects (filtered by project properties)">
                     <layout>
                         build.gradle
                         settings.gradle
@@ -174,7 +174,7 @@
             intuitive way. All the <literal>hello</literal> tasks of the different projects were executed. Let's switch
             to the <literal>bluewhale</literal> dir and see what happens if we execute Gradle from there.
         </para>
-        <sample id="multiprojectSubBuild" dir="userguide/multiproject/tropicalWithProperties/water/bluewhale">
+        <sample id="multiprojectSubBuild" dir="userguide/multiproject/tropicalWithProperties/water/bluewhale" title="Running build from subproject">
            <output args='-q hello'/>
         </sample>
         <para>The basic rule behind Gradle's behavior is simple. Gradle looks down the hierarchy, starting with the
@@ -188,15 +188,15 @@
             arguments and the current dir, Gradle filters the tasks which should be executed. Because of Gradle's
             cross project configuration <emphasis>every</emphasis> project has to be evaluated before <emphasis>any</emphasis>
             task gets executed. We will have a closer look at this in the next section. Let's now have our last marine
-            example. Let's add a task to <literal>bluewhale</literal> and<literal>krill</literal>.
+            example. Let's add a task to <literal>bluewhale</literal> and <literal>krill</literal>.
         </para>
-        <sample id="multiprojectPartialTasks" dir="userguide/multiproject/partialTasks/water">
+        <sample id="multiprojectPartialTasks" dir="userguide/multiproject/partialTasks/water" title="Evaluation and execution of projects">
             <sourcefile file="bluewhale/build.gradle"/>
             <sourcefile file="krill/build.gradle"/>
             <output args="-q distanceToIceberg"/>
         </sample>
         <para>Here the output without the <literal>-q</literal> option:</para>
-        <sample id="multiprojectPartialTasksNotQuiet" dir="userguide/multiproject/partialTasks/water">
+        <sample id="multiprojectPartialTasksNotQuiet" dir="userguide/multiproject/partialTasks/water" title="Evaluation and execution of projects">
             <output args="distanceToIceberg"/>
         </sample>
         <para>The build is executed from the <literal>water</literal> project. Neither <literal>water</literal> nor
@@ -211,7 +211,7 @@
             from there. All matching task names of the project hierarchy starting with the current dir are executed. But
             Gradle also offers to execute tasks by their absolute path (see also <xref linkend='sec:project_and_task_paths'/>):
         </para>
-        <sample id="multiprojectAbsoluteTaskPaths" dir="userguide/multiproject/tropicalWithProperties/water/tropicalFish">
+        <sample id="multiprojectAbsoluteTaskPaths" dir="userguide/multiproject/tropicalWithProperties/water/tropicalFish" title="Running tasks by their absolute path">
             <output args="-q :hello :krill:hello hello"/>
         </sample>
         <para>The build is executed from the <literal>tropicalFish</literal> project. We execute the <literal>hello</literal>
@@ -252,7 +252,7 @@
             <title>Execution dependencies</title>
             <section id='ssub:dependencies_and_execution_order'>
                 <title>Dependencies and execution order</title>
-                <sample id="multiprojectFirstMessages" dir="userguide/multiproject/dependencies/firstMessages/messages" includeLocation="true">
+                <sample id="multiprojectFirstMessages" dir="userguide/multiproject/dependencies/firstMessages/messages" includeLocation="true" title="Dependencies and execution order">
                     <layout>
                         settings.gradle
                         consumer
@@ -271,7 +271,7 @@
                     is executed before <literal>:producer:action</literal>. Let's try to solve this with a hack and
                     rename the producer project to <literal>aProducer</literal>.
                 </para>
-                <sample id="multiprojectMessagesHack" dir="userguide/multiproject/dependencies/messagesHack/messages">
+                <sample id="multiprojectMessagesHack" dir="userguide/multiproject/dependencies/messagesHack/messages" title="Dependencies and execution order">
                     <layout>
                         settings.gradle
                         aProducer
@@ -287,7 +287,7 @@
                 <para>Now we take the air out of this hack. We simply switch to the <literal>consumer</literal> dir and
                     execute the build.
                 </para>
-                <sample id="multiprojectMessagesHackBroken" dir="userguide/multiproject/dependencies/messagesHack/messages/consumer">
+                <sample id="multiprojectMessagesHackBroken" dir="userguide/multiproject/dependencies/messagesHack/messages/consumer" title="Dependencies and execution order">
                     <output args="-q action"/>
                 </sample>
                 <para>For Gradle the two
@@ -303,7 +303,7 @@
             </section>
             <section id='ssub:declaring_dependencies'>
                 <title>Declaring dependencies</title>
-                <sample id="multiprojectMessagesDependencies" dir="userguide/multiproject/dependencies/messagesWithDependencies/messages" includeLocation="true">
+                <sample id="multiprojectMessagesDependencies" dir="userguide/multiproject/dependencies/messagesWithDependencies/messages" includeLocation="true" title="Declaring dependencies">
                     <layout>
                         settings.gradle
                         consumer
@@ -317,7 +317,7 @@
                     <output args="-q action"/>
                 </sample>
                 <para>Running this from the <literal>consumer</literal> directory gives:</para>
-                <sample id="multiprojectMessagesDependenciesSubBuild" dir="userguide/multiproject/dependencies/messagesWithDependencies/messages/consumer">
+                <sample id="multiprojectMessagesDependenciesSubBuild" dir="userguide/multiproject/dependencies/messagesWithDependencies/messages/consumer" title="Declaring dependencies">
                     <output args="-q action"/>
                 </sample>
                 <para>We have now declared that the
@@ -338,7 +338,7 @@
                 <title>The nature of project dependencies</title>
                 <para>Let's change the naming of our tasks and execute the build.
                 </para>
-                <sample id="multiprojectMessagesDifferentTaskNames" dir="userguide/multiproject/dependencies/messagesDifferentTaskNames/messages">
+                <sample id="multiprojectMessagesDifferentTaskNames" dir="userguide/multiproject/dependencies/messagesDifferentTaskNames/messages" title="Project dependencies">
                     <sourcefile file="consumer/build.gradle"/>
                     <sourcefile file="producer/build.gradle"/>
                     <output args="-q consume"/>
@@ -346,14 +346,14 @@
                 <para>Oops. Why does this not work? The
                     <literal>dependsOn</literal>
                     command is created for projects with a common lifecycle. Provided you have two Java projects were
-                    one depends on the other. If you trigger a compile for for the dependent project you don't want that
+                    one depends on the other. If you trigger a compile for the dependent project you don't want that
                     <emphasis>all</emphasis>
                     tasks of the other project get executed. Therefore a
                     <literal>dependsOn</literal>
                     creates dependencies between tasks with equal names. To deal with the scenario above you would do
                     the following:
                 </para>
-                <sample id="multiprojectMessagesTaskDependencies" dir="userguide/multiproject/dependencies/messagesTaskDependencies/messages">
+                <sample id="multiprojectMessagesTaskDependencies" dir="userguide/multiproject/dependencies/messagesTaskDependencies/messages" title="Project dependencies">
                     <sourcefile file="consumer/build.gradle"/>
                     <sourcefile file="producer/build.gradle"/>
                     <output args="-q consume"/>
@@ -367,7 +367,7 @@
                 land. We add a property to the producer project and create now a configuration time dependency from
                 consumer on producer.
             </para>
-            <sample id="multiprojectMessagesConfigDependenciesBroken" dir="userguide/multiproject/dependencies/messagesConfigDependenciesBroken/messages">
+            <sample id="multiprojectMessagesConfigDependenciesBroken" dir="userguide/multiproject/dependencies/messagesConfigDependenciesBroken/messages" title="Configuration time dependencies">
                 <sourcefile file="consumer/build.gradle"/>
                 <sourcefile file="producer/build.gradle"/>
                 <output args="-q consume"/>
@@ -388,7 +388,7 @@
                 <literal>consumer</literal>
                 project. Gradle offers a solution for this.
             </para>
-            <sample id="multiprojectMessagesConfigDependencies" dir="userguide/multiproject/dependencies/messagesConfigDependencies/messages">
+            <sample id="multiprojectMessagesConfigDependencies" dir="userguide/multiproject/dependencies/messagesConfigDependencies/messages" title="Configuration time dependencies - evaluationDependsOn">
                 <sourcefile file="consumer/build.gradle"/>
                 <output args="-q consume"/>
             </sample>
@@ -402,7 +402,7 @@
                 <emphasis>this</emphasis>
                 case there would be an easier solution by reading the key property at execution time.
             </para>
-            <sample id="multiprojectMessagesConfigDependenciesAltSolution" dir="userguide/multiproject/dependencies/messagesConfigDependenciesAltSolution/messages">
+            <sample id="multiprojectMessagesConfigDependenciesAltSolution" dir="userguide/multiproject/dependencies/messagesConfigDependenciesAltSolution/messages" title="Configuration time dependencies">
                 <sourcefile file="consumer/build.gradle"/>
                 <output args="-q consume"/>
             </sample>
@@ -437,7 +437,7 @@
                 </footnote>
                 For the example we use only one build script and do <emphasis>cross project configuration</emphasis>.
             </para>
-            <sample id="webdist" dir="userguide/multiproject/dependencies/webDist" includeLocation="true">
+            <sample id="webdist" dir="userguide/multiproject/dependencies/webDist" includeLocation="true" title="Dependencies - real life example - crossproject configuration">
                 <layout>
                     settings.gradle
                     build.gradle
@@ -506,7 +506,7 @@
             multi-project builds. As already mentioned in <xref linkend='sub:project_dependencies'/>, Gradle
             offers project dependencies for this.
         </para>
-        <sample id="javadependencies" dir="userguide/multiproject/dependencies/java" includeLocation="true">
+        <sample id="javadependencies" dir="userguide/multiproject/dependencies/java" includeLocation="true" title="Project dependencies">
             <layout>
                 settings.gradle
                 build.gradle
@@ -536,7 +536,7 @@
                 </para>
             </footnote>
         </para>
-        <sample id="javadependencies" dir="userguide/multiproject/dependencies/java">
+        <sample id="javadependencies" dir="userguide/multiproject/dependencies/java" title="Project dependencies">
             <sourcefile file="settings.gradle"/>
             <sourcefile file="build.gradle"/>
         </sample>
@@ -561,7 +561,7 @@
         <para>If you come from Maven land you might be perfectly happy with this. If you come from Ivy land, you might
             expect some more fine grained control. Gradle offers this to you:
         </para>
-        <sample id="javaWithCustomConf" dir="userguide/multiproject/dependencies/javaWithCustomConf">
+        <sample id="javaWithCustomConf" dir="userguide/multiproject/dependencies/javaWithCustomConf" title="Fine grained control over dependencies">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>The Java plugin adds per default a jar to your project libraries which contains all the classes. In this
Index: src/docs/userguide/ant.xml
===================================================================
--- src/docs/userguide/ant.xml	(revision 1571)
+++ src/docs/userguide/ant.xml	(working copy)
@@ -28,22 +28,22 @@
         <title>Ant properties and references</title>
 
         <para>To set an Ant property</para>
-        <sample id="antProperties" dir="userguide/ant/properties">
+        <sample id="antProperties" dir="userguide/ant/properties" title="Setting an Ant property">
             <sourcefile file="build.gradle" snippet="set-property"/>
             <sourcefile file="build.xml" snippet="set-property"/>
         </sample>
         <para>To get an Ant property</para>
-        <sample id="antProperties" dir="userguide/ant/properties">
+        <sample id="antProperties" dir="userguide/ant/properties" title="Getting an Ant property">
             <sourcefile file="build.xml" snippet="get-property"/>
             <sourcefile file="build.gradle" snippet="get-property"/>
         </sample>
         <para>To set an Ant reference</para>
-        <sample id="antProperties" dir="userguide/ant/properties">
+        <sample id="antProperties" dir="userguide/ant/properties" title="Setting an Ant reference">
             <sourcefile file="build.gradle" snippet="set-reference"/>
             <sourcefile file="build.xml" snippet="set-reference"/>
         </sample>
         <para>To get an Ant reference</para>
-        <sample id="antProperties" dir="userguide/ant/properties">
+        <sample id="antProperties" dir="userguide/ant/properties" title="Getting an Ant reference">
             <sourcefile file="build.xml" snippet="get-reference"/>
             <sourcefile file="build.gradle" snippet="get-reference"/>
         </sample>
@@ -53,7 +53,7 @@
         <title>Importing an Ant build</title>
         <para>You can use the <firstterm>Ant Plugin</firstterm> to import an Ant build into your Gradle project.
         </para>
-        <sample id="antHello" dir="userguide/ant/hello">
+        <sample id="antHello" dir="userguide/ant/hello" title="Importing an Ant build">
             <sourcefile file="build.gradle"/>
             <sourcefile file="build.xml"/>
             <output args="hello"/>
@@ -61,17 +61,17 @@
         <para>Each Ant target is treated as a Gradle task. This means you can manipulate and execute the Ant targets in
             exactly the same way as Gradle tasks. For example, you can add a task which depends on an Ant target:
         </para>
-        <sample id="dependsOnAntTarget" dir="userguide/ant/dependsOnAntTarget">
+        <sample id="dependsOnAntTarget" dir="userguide/ant/dependsOnAntTarget" title="Task that depends on Ant target">
             <sourcefile file="build.gradle"/>
             <output args="intro"/>
         </sample>
         <para>Or, you can add behaviour to an Ant target:</para>
-        <sample id="addBehaviourToAntTarget" dir="userguide/ant/addBehaviourToAntTarget">
+        <sample id="addBehaviourToAntTarget" dir="userguide/ant/addBehaviourToAntTarget" title="Adding behaviour to an Ant target">
             <sourcefile file="build.gradle"/>
             <output args="hello"/>
         </sample>
-        <para>It is also possible for an Ant target to depend on a Gradle task</para>
-        <sample id="dependsOnTask" dir="userguide/ant/dependsOnTask">
+        <para>It is also possible for an Ant target to depend on a Gradle task:</para>
+        <sample id="dependsOnTask" dir="userguide/ant/dependsOnTask" title="Ant target that depends on Gradle task">
             <sourcefile file="build.gradle"/>
             <sourcefile file="build.xml"/>
             <output args="hello"/>
Index: src/docs/userguide/gradleWrapper.xml
===================================================================
--- src/docs/userguide/gradleWrapper.xml	(revision 1571)
+++ src/docs/userguide/gradleWrapper.xml	(working copy)
@@ -20,7 +20,7 @@
         </footnote>
         You can create such a task in your build script.
     </para>
-    <sample id="wrapperSimple" dir="userguide/wrapper">
+    <sample id="wrapperSimple" dir="userguide/wrapper" title="Wrapper task">
         <sourcefile file="build.gradle" snippet="wrapper-simple"/>
     </sample>
     <para>The build master usually explicitly executes this task. After such
@@ -49,7 +49,7 @@
             command.
         </para>
         <para>You can specify where the wrapper files should be stored (within your project directory):</para>
-        <sample id="wrapperCustomized" dir="userguide/wrapper">
+        <sample id="wrapperCustomized" dir="userguide/wrapper" title="Configuration of wrapper task">
             <sourcefile file="build.gradle"/>
         </sample>
         <screen><![CDATA[
Index: src/docs/userguide/javaPlugin.xml
===================================================================
--- src/docs/userguide/javaPlugin.xml	(revision 1571)
+++ src/docs/userguide/javaPlugin.xml	(working copy)
@@ -738,7 +738,7 @@
             you want. You can also add WAR, ZIP and TAR archives to your project. They are all added the same way, so
             let's look at how you add a ZIP file.
         </para>
-        <sample id="zip" dir="userguide/tutorial/zipProject">
+        <sample id="zip" dir="userguide/tutorial/zipProject" title="Creation of ZIP archive">
             <sourcefile file="build.gradle"/>
             <output args="-q init"/>
         </sample>
@@ -751,12 +751,12 @@
         <para>There are a number of properties which you can set on an archive task. You can, for example, change the
             name of the archive:
         </para>
-        <sample id="zipWithCustomName" dir="userguide/tutorial/zipWithCustomName">
+        <sample id="zipWithCustomName" dir="userguide/tutorial/zipWithCustomName" title="Configuration of archive task - custom archive name">
             <sourcefile file="build.gradle"/>
             <output args="-q init"/>
         </sample>
         <para>You can further customize the archive names:</para>
-        <sample id="zipWithArguments" dir="userguide/tutorial/zipWithArguments">
+        <sample id="zipWithArguments" dir="userguide/tutorial/zipWithArguments" title="Configuration of archive task - appendix &amp; classifier">
             <sourcefile file="build.gradle"/>
             <output args="-q init"/>
         </sample>
@@ -885,20 +885,20 @@
                 <xref linkend='filecontainer'/>). You can add as many file containers as you like. They behave pretty much
                 the same as the Ant resources with similar names.
             </para>
-            <sample id="archiveContent" dir="userguide/tutorial/archiveContent">
+            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - include &amp; exclude">
                 <sourcefile file="build.gradle" snippet="file-set"/>
             </sample>
             <para>You can add arbitrary files to an archive:
             </para>
-            <sample id="archiveContent" dir="userguide/tutorial/archiveContent">
+            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - arbitrary files">
                 <sourcefile file="build.gradle" snippet="files"/>
             </sample>
             <para>Other examples:
             </para>
-            <sample id="archiveContent" dir="userguide/tutorial/archiveContent">
+            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - zipFileSet">
                 <sourcefile file="build.gradle" snippet="zip-file-set"/>
             </sample>
-            <sample id="archiveContent" dir="userguide/tutorial/archiveContent">
+            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Creation of TAR archive">
                 <sourcefile file="build.gradle" snippet="tar-file-set"/>
             </sample>
             <para>There is also the option to add an arbitrary Ant expression describing an Ant resource.
@@ -956,7 +956,7 @@
                 With this <classname>GradleManifest</classname> object you can define the content of the
                 <filename>MANIFEST.MF</filename> file for all the jar or a war archives in your project.
             </para>
-            <sample id="manifest" dir="userguide/tutorial/manifest">
+            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF">
                 <sourcefile file="build.gradle" snippet="main-attributes"/>
             </sample>
             <para>You can also define sections of a manifest file.
@@ -964,7 +964,7 @@
             <para>If a particular archive needs unique entries in its manifest you have to create your own
                 <classname>GradleManifest</classname> instance for it.
             </para>
-            <sample id="manifest" dir="userguide/tutorial/manifest">
+            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF for a particular archive">
                 <sourcefile file="build.gradle" snippet="custom-manifest"/>
             </sample>
             <para>Passing the common manifest object to the constructor of <classname>GradleManifest</classname>
Index: src/docs/userguide/webTutorial.xml
===================================================================
--- src/docs/userguide/webTutorial.xml	(revision 1571)
+++ src/docs/userguide/webTutorial.xml	(working copy)
@@ -29,7 +29,7 @@
     <section>
         <title>Building a WAR file</title>
         <para>To build a WAR file, you apply the War plugin to your project:</para>
-        <sample id="webQuickstart" dir="webApplication/quickstart" includeLocation="true">
+        <sample id="webQuickstart" dir="webApplication/quickstart" includeLocation="true" title="War plugin">
             <sourcefile file="build.gradle" snippet="use-war-plugin"/>
         </sample>
         <para>This also applies the Java plugin to your project. Running <userinput>gradle libs</userinput> will compile,
@@ -45,7 +45,7 @@
     <section>
         <title>Running your web application</title>
         <para>To run your web application, you apply the Jetty plugin to your project:</para>
-        <sample id="webQuickstart" dir="webApplication/quickstart">
+        <sample id="webQuickstart" dir="webApplication/quickstart" title="Running web application with Jetty plugin">
             <sourcefile file="build.gradle" snippet="use-jetty-plugin"/>
         </sample>
         <para>This also applies the War plugin to your project. Running <userinput>gradle jettyRun</userinput> will
Index: src/docs/userguide/groovyPlugin.xml
===================================================================
--- src/docs/userguide/groovyPlugin.xml	(revision 1571)
+++ src/docs/userguide/groovyPlugin.xml	(working copy)
@@ -62,12 +62,12 @@
             assigned to the <literal>groovy</literal> dependency configuration. Here is an example using the public Maven
             repository:
         </para>
-        <sample id="quickstartGroovyDependency" dir="groovy/quickstart">
+        <sample id="quickstartGroovyDependency" dir="groovy/quickstart" title="Configuration of Groovy plugin">
             <sourcefile file="build.gradle" snippet="groovy-dependency"/>
         </sample>
         <para>And here is an example using the Groovy JARs checked into the <filename>lib</filename> directory of the source
             tree:</para>
-        <sample id="flatDirGroovyDependency" dir="userguide/tutorial/groovyWithFlatDir">
+        <sample id="flatDirGroovyDependency" dir="userguide/tutorial/groovyWithFlatDir" title="Configuration of Groovy plugin">
             <sourcefile file="build.gradle" snippet="groovy-dependency"/>
         </sample>
     </section>
Index: src/docs/userguide/javaTutorial.xml
===================================================================
--- src/docs/userguide/javaTutorial.xml	(revision 1571)
+++ src/docs/userguide/javaTutorial.xml	(working copy)
@@ -11,7 +11,7 @@
     <section>
         <title>A basic Java project</title>
         <para>Let's look at a simple example. To use the Java plugin, add the following to your build file:</para>
-        <sample id="javaQuickstart" dir="java/quickstart" includeLocation="true">
+        <sample id="javaQuickstart" dir="java/quickstart" includeLocation="true" title="Java plugin">
             <sourcefile file="build.gradle" snippet="use-plugin"/>
         </sample>
         <para>This is all you need to define a Java project. This will apply the Java plugin to your project, which adds
@@ -39,13 +39,13 @@
                 files, are located in a <firstterm>repository</firstterm>. A repository can be used for fetching the
                 dependencies of a project, or for publishing the artifacts of a project, or both. For this example,
                 we will use the public Maven repository:</para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Adding Maven repository">
                 <sourcefile file="build.gradle" snippet="repo"/>
             </sample>
 
             <para>Let's add some dependencies. Here, we will declare that our production classes have a compile-time
                 dependency on commons collections, and that our test classes have a compile-time dependency on junit:</para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Adding dependencies">
                 <sourcefile file="build.gradle" snippet="dependencies"/>
             </sample>
             <para>You can find out more in <xref linkend="dependency_management"/>.</para>
@@ -58,7 +58,7 @@
                 look at this for our sample. Here we will specify the version number for our Java project, along
                 with the Java version our source is written in. We also add some attributes to the JAR manifest.
             </para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Customization of MANIFEST.MF">
                 <sourcefile file="build.gradle" snippet="customisation"/>
             </sample>
             <tip>
@@ -71,7 +71,7 @@
                 dependencies of a task, or replace a task entirely. In our sample, we will configure the
                 <literal>test</literal> task, which is of type<apilink class="org.gradle.api.tasks.testing.Test"/>, to
                 add a system property when the tests are executed: </para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Adding system property">
                 <sourcefile file="build.gradle" snippet="task-customisation"/>
             </sample>
         </section>
@@ -83,7 +83,7 @@
                 sample, we will publish to a local directory. You can also publish to a remote location, or multiple
                 location.
             </para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Publishing the JAR file">
                 <sourcefile file="build.gradle" snippet="upload"/>
             </sample>
             <para>To publish the JAR file, run <userinput>gradle uploadArchives</userinput>.</para>
@@ -100,7 +100,7 @@
         <section>
             <title>Summary</title>
             <para>Here's the complete build file for our sample:</para>
-            <sample id="javaQuickstart" dir="java/quickstart">
+            <sample id="javaQuickstart" dir="java/quickstart" title="Java example - complete build file">
                 <sourcefile file="build.gradle"/>
             </sample>
         </section>
@@ -110,7 +110,7 @@
         <title>Multi-project Java build</title>
         <para>Now let's look at a typical multi-project build. Below is the layout for the project:
         </para>
-        <sample id="javaMultiProject" dir="java/multiproject" includeLocation="true">
+        <sample id="javaMultiProject" dir="java/multiproject" includeLocation="true" title="Multi-project build - hierarchical layout">
             <layout>
                 api
                 services
@@ -131,7 +131,7 @@
                 build. It must be called <filename>settings.gradle</filename>. For this example, we are using a simple
                 hierarchical layout. Here is the corresponding settings file:
             </para>
-            <sample id="javaMultiProject" dir="java/multiproject">
+            <sample id="javaMultiProject" dir="java/multiproject" title="Multi-project build - settings.gradle file">
                 <sourcefile file="settings.gradle" snippet="include-projects"/>
             </sample>
             <para>You can find out more about the settings file in <xref linkend="multi_project_builds"/>.</para>
@@ -146,7 +146,7 @@
                 this instance - and injects the specified configuration. This way we can easily define the manifest
                 content for all archives, and some common dependencies:
             </para>
-            <sample id="javaMultiProject" dir="java/multiproject">
+            <sample id="javaMultiProject" dir="java/multiproject" title="Multi-project build - common configuration">
                 <sourcefile file="build.gradle"/>
             </sample>
 
@@ -163,7 +163,7 @@
                 on the JAR produced by the <literal>shared</literal> project. Due to this dependency, Gradle will
                 ensure that project <literal>shared</literal> always gets built before project <literal>api</literal>.
             </para>
-            <sample id="javaMultiProject" dir="java/multiproject">
+            <sample id="javaMultiProject" dir="java/multiproject" title="Multi-project build - dependencies between projects">
                 <sourcefile file="api/build.gradle" snippet="dependencies"/>
             </sample>
             See <xref linkend="disable_dependency_projects"/> for how to disable this functionality.
@@ -174,7 +174,7 @@
             <para>
                 We also add a distribution, that gets shipped to the client:
             </para>
-            <sample id="javaMultiProject" dir="java/multiproject">
+            <sample id="javaMultiProject" dir="java/multiproject" title="Multi-project build - distribution file">
                 <sourcefile file="api/build.gradle" snippet="dists"/>
             </sample>
         </section>
Index: src/docs/userguide/warPlugin.xml
===================================================================
--- src/docs/userguide/warPlugin.xml	(revision 1571)
+++ src/docs/userguide/warPlugin.xml	(working copy)
@@ -95,14 +95,14 @@
         <title>Customizing</title>
         <para>Here is an example with the most important customization options:
         </para>
-        <sample id="webproject" dir="webApplication/customised">
+        <sample id="webproject" dir="webApplication/customised" title="Customization of war plugin">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Of course one can configure the different file-sets with a closure to define excludes and includes.
         </para>
         <para>If you want to enable the generation of the default jar archive additional to the war archive just type:
         </para>
-        <sample id="customisedWebApplication" dir="webApplication/customised">
+        <sample id="customisedWebApplication" dir="webApplication/customised" title="Generation of JAR archive in addition to WAR archive">
             <sourcefile file="build.gradle" snippet="enable-jar"/>
         </sample>
     </section>
Index: src/docs/userguide/groovyTutorial.xml
===================================================================
--- src/docs/userguide/groovyTutorial.xml	(revision 1571)
+++ src/docs/userguide/groovyTutorial.xml	(working copy)
@@ -26,7 +26,7 @@
         <title>A basic Groovy project</title>
 
         <para>Let's look at an example. To use the Groovy plugin, add the following to your build file:</para>
-        <sample id="groovyQuickstart" dir="groovy/quickstart" includeLocation="true">
+        <sample id="groovyQuickstart" dir="groovy/quickstart" includeLocation="true" title="Groovy plugin">
             <sourcefile file="build.gradle" snippet="use-plugin"/>
         </sample>
         <para>This will also apply the Java plugin to the project, if it has not already been applied. The Groovy plugin
@@ -40,11 +40,11 @@
             The <literal>compile</literal> configuration inherits this dependency, so the groovy libraries will
             be included in classpath when compiling Groovy and Java source.  For our sample, we will use Groovy 1.6.0
             from the public Maven repository:</para>
-        <sample id="groovyQuickstart" dir="groovy/quickstart">
+        <sample id="groovyQuickstart" dir="groovy/quickstart" title="Dependency on Groovy 1.6.0">
             <sourcefile file="build.gradle" snippet="groovy-dependency"/>
         </sample>
-        <para>Here is our completed build file:</para>
-        <sample id="groovyQuickstart" dir="groovy/quickstart">
+        <para>Here is our complete build file:</para>
+        <sample id="groovyQuickstart" dir="groovy/quickstart" title="Groovy example - complete build file">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>Running <userinput>gradle libs</userinput> will compile, test and JAR your project.</para>
@@ -54,7 +54,7 @@
         <title>Summary</title>
         <para>This chapter describes a very simple Groovy project. Usually, a real project will require more than this.
             Because a Groovy project <emphasis>is</emphasis> a Java project, whatever you can do with a Java project,
-            you can also do with a Groovy project.  You can find out more about the Groovy Plugin in <xref linkend="groovy_plugin"/>.
+            you can also do with a Groovy project.
         </para>
         <para>
             You can find out more about the Groovy plugin in <xref linkend="groovy_plugin"/>, and you can find more
Index: src/docs/userguide/commandLineTutorial.xml
===================================================================
--- src/docs/userguide/commandLineTutorial.xml	(revision 1571)
+++ src/docs/userguide/commandLineTutorial.xml	(working copy)
@@ -16,7 +16,7 @@
 <chapter id="tutorial_gradle_command_line">
     <title>Using the Gradle Command-Line</title>
     <para>This chapter introduces the basics of the Gradle command-line. You run a build using the
-        <command>gradle</command> command, which you have already seen this in action in previous chapters.</para>
+        <command>gradle</command> command, which you have already seen in action in previous chapters.</para>
     <section>
         <title>Executing multiple tasks</title>
         <para>You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example,
@@ -24,14 +24,12 @@
             <literal>test</literal> tasks. Gradle will execute the tasks in the order that they are listed on the
             command-line, and will also execute the dependencies for each task. Each task is executed once only,
             regardless of why it is included in the build: whether it was specified on the command-line, or it a
-            dependency of another task, or both. Let's look at an example:</para>
-        <sample id="multipleTasksFromCommandLine" dir="userguide/tutorial/multipleTasksFromCommandLine">
+            dependency of another task, or both. Let's look at an example.</para>
+            <para>Below three tasks are defined. Both <literal>libs</literal> and <literal>test</literal> depend on <literal>compile</literal>
+            task. Execution of <userinput>gradle -q libs test</userinput> command for this build script results in <literal>compile</literal>
+            task being executed only once.</para> 
+        <sample id="multipleTasksFromCommandLine" dir="userguide/tutorial/multipleTasksFromCommandLine" title="Executing multiple tasks">
             <sourcefile file="build.gradle"/>
-        </sample>
-        <para>Below is the result of executing <userinput>gradle -q libs test</userinput> for this build script. Notice that
-            the <literal>compile</literal> task is executed once, even though it is a dependency of both
-            <literal>libs</literal> and <literal>test</literal>.</para>
-        <sample id="multipleTasksFromCommandLine" dir="userguide/tutorial/multipleTasksFromCommandLine">
             <output args="-q libs test"/>
         </sample>
         <para>Because each task is executed once only, executing <userinput>gradle libs libs</userinput> is exactly the same
Index: src/docs/userguide/depMngmt.xml
===================================================================
--- src/docs/userguide/depMngmt.xml	(revision 1571)
+++ src/docs/userguide/depMngmt.xml	(working copy)
@@ -153,7 +153,7 @@
             <para>Module dependencies are the most common dependencies. They correspond to a dependency in an external
                 repository.
             </para>
-            <sample id="moduleDependencies" dir="userguide/artifacts/externalDependencies">
+            <sample id="moduleDependencies" dir="userguide/artifacts/externalDependencies" title="Module dependencies">
                 <sourcefile file="build.gradle" snippet="module-dependencies"/>
             </sample>
             <para>Gradle provides different notations for module dependencies. There is a string notation and
@@ -182,7 +182,7 @@
                     </footnote>
                     And sometimes you want to download a zip from a repository, that does not have module descriptors.
                     Gradle provides an <emphasis>artifact only</emphasis> notation for those use cases - simply prefix the extension that you want to be downloaded with <literal>'@'</literal> sign:
-                    <sample id="artifactOnly" dir="userguide/artifacts/externalDependencies">
+                    <sample id="artifactOnly" dir="userguide/artifacts/externalDependencies" title="Artifact only notation">
                         <sourcefile file="build.gradle" snippet="artifact-only"/>
                     </sample>
                     An artifact only notation creates a module dependency which downloads only the artifact file with
@@ -199,7 +199,7 @@
                     </footnote>
                     Gradle supports this. To retrieve classified dependencies from a maven repository you can write:
                 </para>
-                <sample id="classifier" dir="userguide/artifacts/excludesAndClassifiers">
+                <sample id="classifier" dir="userguide/artifacts/excludesAndClassifiers" title="Dependency with classifier">
                         <sourcefile file="build.gradle" snippet="classifier"/>
                 </sample>
                 <para>As you can see in the example, classifiers can be used together with setting
@@ -213,7 +213,7 @@
                 dependencies directly in your build script. They are a replacement for a module descriptor XML file in
                 an external repository.
             </para>
-            <sample id="client-modules" dir="userguide/artifacts/externalDependencies">
+            <sample id="client-modules" dir="userguide/artifacts/externalDependencies" title="Client module dependencies - transitive dependencies">
                 <sourcefile file="build.gradle" snippet="client-modules"/>
             </sample>
             <para>This declares a dependency of your project on Groovy. Groovy itself has dependencies. But Gradle does
@@ -236,7 +236,7 @@
             <para>Gradle distinguishes between external dependencies and dependencies on projects which are part of the
                 same multi-project build. For the latter you can declare <emphasis>Project Dependencies</emphasis>.
             </para>
-            <sample id="project-dependencies" dir="java/multiproject/api">
+            <sample id="project-dependencies" dir="java/multiproject/api" title="Project dependencies">
                 <sourcefile file="build.gradle" snippet="project-dependencies"/>
             </sample>
             <para>For more information see the javadoc: <apilink class="org.gradle.api.artifacts.ProjectDependency"/>
@@ -248,7 +248,7 @@
             <title>Excluding transitive dependencies</title>
             <para>You can exclude a <emphasis>transitive</emphasis> dependency either by configuration or by dependency:
             </para>
-            <sample id="exclude-dependencies" dir="userguide/artifacts/excludesAndClassifiers">
+            <sample id="exclude-dependencies" dir="userguide/artifacts/excludesAndClassifiers" title="Excluding transitive dependencies">
                 <sourcefile file="build.gradle" snippet="exclude-dependencies"/>
             </sample>
             <para>If you define
@@ -270,12 +270,12 @@
                 group, name and version. If you work with filesystem repositories you might only need the name or the name
                 and the version.
             </para>
-            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies">
+            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies" title="Optional attributes of dependencies">
                 <sourcefile file="build.gradle" snippet="dependencies-with-empty-attributes"/>
             </sample>
             <para id="para:notation_collections">You can also assign collections or arrays of dependency notations to a configuration:
             </para>
-            <sample id="listGrouping" dir="userguide/artifacts/externalDependencies">
+            <sample id="listGrouping" dir="userguide/artifacts/externalDependencies" title="Collections and arrays of dependencies">
                 <sourcefile file="build.gradle" snippet="list-grouping"/>
             </sample>
         </section>
@@ -286,11 +286,11 @@
             from a Maven repository, the default configuration is the only available one anyway. If you work with Ivy repositories and
             want to declare a non-default configuration for your dependency you have to use the map notation and declare:
             </para>
-            <sample id="dependencyConfigurations" dir="userguide/artifacts/externalDependencies">
+            <sample id="dependencyConfigurations" dir="userguide/artifacts/externalDependencies" title="Dependency configurations">
                 <sourcefile file="build.gradle" snippet="dependency-configurations"/>
             </sample>
             <para>To do the same for project dependencies you need to declare:</para>
-            <sample id="dependencyConfigurationsProjects" dir="/java/multiproject/services/webservice">
+            <sample id="dependencyConfigurationsProjects" dir="/java/multiproject/services/webservice"  title="Dependency configurations for project">
                 <sourcefile file="build.gradle" snippet="dependency-configurations"/>
             </sample>
         </section>
@@ -362,14 +362,14 @@
             <title>Working with dependencies</title>
             <para>To get the library files of the dependencies of a configuration you can do:
             </para>
-            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies">
+            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies" title="Working with dependencies">
                 <sourcefile file="build.gradle" snippet="dependencies-with-empty-attributes"/>
             </sample>
             <para>Sometimes you want the library files of a subset of the configuration dependencies (e.g. of a single dependency).
                 Gradle does not provide such a functionality in the current release (expect it to be available in the next release).
                 What you can do is to use a copy of a configuration. 
             </para>
-            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies">
+            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies" title="Working with dependencies">
                 <sourcefile file="build.gradle" snippet="configuration-copy"/>
             </sample>
             <para>Now you can resolve this copied configuration. You must be aware that the resolve of the copied configuration is often
@@ -384,7 +384,7 @@
             </para>
             <para>You can use the configuration to access the declared dependencies or a subset of those:
             </para>
-            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies">
+            <sample id="dependenciesWithEmptyAttributes" dir="userguide/artifacts/externalDependencies" title="Accessing declared dependencies">
                 <sourcefile file="build.gradle" snippet="configuration-get-dependencies"/>
             </sample>
             <para><code>dependencies</code> returns only the dependencies belonging explicitly to the configuration.
@@ -409,7 +409,7 @@
             <para>To add the central Maven2 repository (<ulink url='http://repo1.maven.org/maven2'/>) simply
                 type:
             </para>
-            <sample id="mavenCentral" dir="userguide/artifacts/defineRepository">
+            <sample id="mavenCentral" dir="userguide/artifacts/defineRepository" title="Adding central Maven repository">
                 <sourcefile file="build.gradle" snippet="maven-central"/>
             </sample>
             <para>Now Gradle looks for your dependencies in this repository.
@@ -417,7 +417,7 @@
             <para>Quite often certain jars are not in the official Maven repository for licensing reasons (e.g. JTA),
                 but its poms are.
             </para>
-            <sample id="mavenCentralJarRepo" dir="userguide/artifacts/defineRepository">
+            <sample id="mavenCentralJarRepo" dir="userguide/artifacts/defineRepository" title="Adding many Maven repositories">
                 <sourcefile file="build.gradle" snippet="maven-central-jar-repo"/>
             </sample>
             <para>Gradle looks first in the central Maven repository for the pom and the jar. If the jar can't be
@@ -425,13 +425,13 @@
             </para>
             <para>For adding a custom Maven repository you can say:
             </para>
-            <sample id="mavenLikeRepo" dir="userguide/artifacts/defineRepository">
+            <sample id="mavenLikeRepo" dir="userguide/artifacts/defineRepository" title="Adding custom Maven repository">
                 <sourcefile file="build.gradle" snippet="maven-like-repo"/>
             </sample>
             <para>To declare additional repositories to look for jars (like above in the example
                 for the central Maven repository), you can say:
             </para>
-            <sample id="mavenLikeRepoWithJarRepo" dir="userguide/artifacts/defineRepository">
+            <sample id="mavenLikeRepoWithJarRepo" dir="userguide/artifacts/defineRepository" title="Adding additional Maven repositories for JAR files">
                 <sourcefile file="build.gradle" snippet="maven-like-repo-with-jar-repo"/>
             </sample>
             <para>The first URL is used to look for poms and jars. The subsequent URLs are used to look for jars.
@@ -441,7 +441,7 @@
             <title>Flat directory resolver</title>
             <para>If you want to use a (flat) filesytem directory as a repository, simply type:
             </para>
-            <sample id="flatDirMulti" dir="userguide/artifacts/defineRepository">
+            <sample id="flatDirMulti" dir="userguide/artifacts/defineRepository" title="Flat repository resolver">
                 <sourcefile file="build.gradle" snippet="flat-dir-multi"/>
             </sample>
             <para>This adds repositories which look into one or more directories for finding dependencies. If you only
@@ -508,7 +508,7 @@
 ]]></programlisting>
             <para>To add any kind of repository (you can pretty easy write your own ones) you can do:
             </para>
-            <sample id="fileSystemResolver" dir="userguide/artifacts/excludesAndClassifiers">
+            <sample id="fileSystemResolver" dir="userguide/artifacts/excludesAndClassifiers" title="Definition of a custom repository">
                 <sourcefile file="build.gradle" snippet="file-system-resolver"/>
             </sample>
             <para>An overview of which Resolvers are offered by Ivy and thus also by Gradle can be found
Index: src/docs/userguide/thisAndThat.xml
===================================================================
--- src/docs/userguide/thisAndThat.xml	(revision 1571)
+++ src/docs/userguide/thisAndThat.xml	(working copy)
@@ -5,12 +5,12 @@
         <para>Gradle offers multiple ways to skip the execution of a task.
         </para>
         <para>You can set system property named <literal>skip.<emphasis>taskname</emphasis></literal> or pass such property as a parameter to the <command>gradle</command> command using <option>-D</option> option (see <xref linkend='sec:gradle_properties_and_system_properties' />).</para>
-        <sample id="autoskip" dir="userguide/tutorial/autoskip">
+        <sample id="autoskip" dir="userguide/tutorial/autoskip" title="Skipping tasks using default property name">
             <sourcefile file="build.gradle"/>
             <output args="-Dskip.autoskip autoskip"/>
         </sample>
         <para>You can also choose another another property that can be used to skip a task.</para>
-        <sample id="skipProperties" dir="userguide/tutorial/skipProperties">
+        <sample id="skipProperties" dir="userguide/tutorial/skipProperties" title="Skipping tasks using custom property">
             <sourcefile file="build.gradle"/>
             <output args="-DmySkipProperty skipMe"/>
         </sample>
@@ -26,7 +26,7 @@
         <para>By default tasks that depends on skipped task get executed. If you want to skip them, you have to declare this explicitly via
             the skip properties.
         </para>
-        <sample id="autoskipDepends" dir="userguide/tutorial/autoskipDepends">
+        <sample id="autoskipDepends" dir="userguide/tutorial/autoskipDepends" title="Skipping depending tasks">
             <sourcefile file="build.gradle"/>
             <output args="-Dskip.autoskip depends"/>
         </sample>
@@ -38,7 +38,7 @@
             the further execution of this action as well as the execution of
             any following action of this task is skipped. The build continues with executing the next task.
         </para>
-        <sample id="stopExecutionException" dir="userguide/tutorial/stopExecutionException">
+        <sample id="stopExecutionException" dir="userguide/tutorial/stopExecutionException" title="Skipping tasks with StopExecutionException">
             <sourcefile file="build.gradle"/>
             <output args="-q myTask"/>
         </sample>
@@ -57,7 +57,7 @@
             flag which defaults to <literal>true</literal>. Setting it to <literal>false</literal> prevents the execution of any of the
             task's actions.
         </para>
-        <sample id="disableTask" dir="userguide/tutorial/disableTask">
+        <sample id="disableTask" dir="userguide/tutorial/disableTask" title="Enabling and disabling tasks">
             <sourcefile file="build.gradle"/>
             <output args="disableMe"/>
         </sample>
@@ -77,7 +77,7 @@
             tasks, if any, of each project, and the description and dependencies of each task. Below is an example of
             this report:
         </para>
-        <sample id="taskListReport" dir="userguide/tutorial/projectReports">
+        <sample id="taskListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about tasks">
             <output args="-q --tasks"/>
         </sample>
         <para id="para:commandline_dependency_report">Running <userinput>gradle --dependencies</userinput>
@@ -85,14 +85,14 @@
             configurations of each project. For each configuration, the direct and transitive dependencies of that
             configuration are shown. Below is an example of this report:
         </para>
-        <sample id="dependencyListReport" dir="userguide/tutorial/projectReports">
+        <sample id="dependencyListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about dependencies">
             <output args="-q --dependencies"/>
         </sample>
         <para>Running
             <userinput>gradle --properties</userinput>
             gives you a list of the properties of each project in the build.
         </para>
-        <!--<sample id="propertyListReport" dir="userguide/tutorial/projectReports">-->
+        <!--<sample id="propertyListReport" dir="userguide/tutorial/projectReports" title="Information about properties">-->
             <!--<output args="-q - -properties"/>-->
         <!--</sample>-->
         <para>Finally, you can use the <literal>project-reports</literal> plugin to add a number of reporting tasks to
@@ -109,12 +109,12 @@
             <emphasis>dependsOn</emphasis>
             relationship):
         </para>
-        <sample id="makeDirectory" dir="userguide/tutorial/makeDirectory">
+        <sample id="makeDirectory" dir="userguide/tutorial/makeDirectory" title="Directory creation with mkdir">
             <sourcefile file="build.gradle"/>
             <output args="-q compile"/>
         </sample>
         <para>But Gradle offers you also <emphasis>Directory Tasks</emphasis> to deal with this.</para>
-        <sample id="directoryTask" dir="userguide/tutorial/directoryTask">
+        <sample id="directoryTask" dir="userguide/tutorial/directoryTask" title="Directory creation with Directory tasks">
             <sourcefile file="build.gradle"/>
             <output args="-q otherResources"/>
         </sample>
@@ -176,7 +176,7 @@
             <literal>systemProp.</literal>
             the property and its value are added to the system properties (without the prefix).
         </para>
-        <sample id="properties" dir="userguide/tutorial/properties">
+        <sample id="properties" dir="userguide/tutorial/properties" title="Setting propertis with settings.gradle file">
             <sourcefile file="gradle.properties"/>
             <sourcefile file="build.gradle"/>
             <output args="-q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps"/>
@@ -204,7 +204,8 @@
             this:
         </para>
         <example>
-            <title><filename>gradle.properties</filename></title>
+            <title>Accessing the web via a proxy</title>
+            <para><filename>gradle.properties</filename></para>
             <programlisting><![CDATA[
 systemProp.http.proxyHost=http://www.somehost.org
 systemProp.http.proxyPort=8080
@@ -242,7 +243,7 @@
         <title>Configuring arbitrary objects</title>
         <para>You can configure arbitrary objects in the following very readable way.
         </para>
-        <sample id="configureObject" dir="userguide/tutorial/configureObject">
+        <sample id="configureObject" dir="userguide/tutorial/configureObject" title="Configuring arbitrary objects">
             <sourcefile file="build.gradle"/>
             <output args="-q configure"/>
         </sample>
Index: src/docs/userguide/organizeBuildLogic.xml
===================================================================
--- src/docs/userguide/organizeBuildLogic.xml	(revision 1571)
+++ src/docs/userguide/organizeBuildLogic.xml	(working copy)
@@ -33,7 +33,7 @@
             <literal>settings.gradle</literal>
             file.
         </para>
-        <sample id="settingsBuildLogic" dir="userguide/organizeBuildLogic">
+        <sample id="settingsBuildLogic" dir="userguide/organizeBuildLogic" title="Configuring external dependencies in settings.gradle file">
             <sourcefile file="settings.gradle"/>
         </sample>
         <para>You can pass any of the dependencies described in
@@ -62,7 +62,7 @@
                 </para>
             </footnote>
         </para>
-        <sample id="buildLogic" dir="userguide/organizeBuildLogic">
+        <sample id="buildLogic" dir="userguide/organizeBuildLogic" title="Ant optional dependencies">
             <sourcefile file="build.gradle"/>
         </sample>
         <para>This is also nice example for the usage of client modules. The pom.xml in maven central for the
Index: src/docs/userguide/buildLifecycle.xml
===================================================================
--- src/docs/userguide/buildLifecycle.xml	(revision 1571)
+++ src/docs/userguide/buildLifecycle.xml	(working copy)
@@ -60,7 +60,7 @@
                     linkend='organizing_build_logic'/>). Let's first do some introspection with a single project
             build:
         </para>
-        <sample id="buildlifecycle" dir="userguide/buildlifecycle/basic">
+        <sample id="buildlifecycle" dir="userguide/buildlifecycle/basic" title="Single project build">
             <sourcefile file="settings.gradle"/>
             <sourcefile file="build.gradle"/>
             <output args="test"/>
@@ -94,7 +94,7 @@
             </para>
             <section>
                 <title>Hierarchical layouts</title>
-                <sample id="standardLayouts" dir="userguide/multiproject/standardLayouts">
+                <sample id="standardLayouts" dir="userguide/multiproject/standardLayouts" title="Hierarchical layout">
                     <sourcefile file="settings.gradle" snippet="hierarchical-layout"/>
                 </sample>
                 <para>The <literal>include</literal> method takes as an argument a relative virtual path to the root
@@ -106,7 +106,7 @@
             </section>
             <section>
                 <title>Flat layouts</title>
-                <sample id="standardLayouts" dir="userguide/multiproject/standardLayouts">
+                <sample id="standardLayouts" dir="userguide/multiproject/standardLayouts" title="Flat layout">
                     <sourcefile file="settings.gradle" snippet="flat-layout"/>
                 </sample>
                 <para>The <literal>includeFlat</literal> method takes directory names as an argument. Those directories
@@ -120,12 +120,12 @@
             <para>The multi-project tree created in the settings file is made up of so called <firstterm>project descriptors</firstterm>.
                 You can modify these descriptors in the settings file at any time. To access a descriptor you can do:
             </para>
-            <sample id="customLayout" dir="userguide/multiproject/customLayout">
+            <sample id="customLayout" dir="userguide/multiproject/customLayout" title="Modification of elements of the project tree">
                 <sourcefile file="settings.gradle" snippet="lookup-project"/>
             </sample>
             <para>Using this descriptor you can change the name, project directory and build file of a project.
             </para>
-            <sample id="customLayout" dir="userguide/multiproject/customLayout">
+            <sample id="customLayout" dir="userguide/multiproject/customLayout" title="Modification of elements of the project tree">
                 <sourcefile file="settings.gradle" snippet="change-project"/>
             </sample>
             <para>Have a look at <apilink class="org.gradle.api.initialization.ProjectDescriptor"/> for more details.</para>
@@ -222,7 +222,7 @@
             <para>Below is an example which adds a <literal>test</literal> task to each project with the
                 <literal>hasTests</literal> property set to true.
             </para>
-            <sample id="projectEvaluateEvents" dir="userguide/buildlifecycle/projectEvaluateEvents">
+            <sample id="projectEvaluateEvents" dir="userguide/buildlifecycle/projectEvaluateEvents" title="Adding of test task to each project which has certain property set">
                 <sourcefile file="build.gradle" snippet="after-evaluate"/>
                 <sourcefile file="projectA.gradle"/>
                 <output args="-q test"/>
@@ -233,7 +233,7 @@
                 some custom logging of project evaluation. Notice that the <literal>afterProject</literal> notification
                 is received regardless of whether the project evaluates successfully or fails with an exception.
             </para>
-            <sample id="buildProjectEvaluateEvents" dir="userguide/buildlifecycle/buildProjectEvaluateEvents">
+            <sample id="buildProjectEvaluateEvents" dir="userguide/buildlifecycle/buildProjectEvaluateEvents" title="Notifications">
                 <sourcefile file="build.gradle" snippet="evaluate-events"/>
                 <output args="-q test"/>
             </sample>
@@ -247,7 +247,7 @@
             <para>You can receive a notification immediately after a task is added to a project. This can be used
                 to set some default values or add behaviour before the task is made available in the build file.</para>
             <para>The following example sets the <literal>srcDir</literal> property of each task as it is created.</para>
-            <sample id="taskCreationEvents" dir="userguide/buildlifecycle/taskCreationEvents">
+            <sample id="taskCreationEvents" dir="userguide/buildlifecycle/taskCreationEvents" title="Setting of certain property to all tasks">
                 <sourcefile file="build.gradle"/>
                 <output args="-q a"/>
             </sample>
@@ -271,7 +271,7 @@
             <para>The following example logs the start and end of each task execution. Notice that the
                 <literal>afterTask</literal> notification is received regardless of whether the task completes
                 successfully or fails with an exception.</para>
-            <sample id="taskExecutionEvents" dir="userguide/buildlifecycle/taskExecutionEvents">
+            <sample id="taskExecutionEvents" dir="userguide/buildlifecycle/taskExecutionEvents" title="Logging of start and end of each task execution">
                 <sourcefile file="build.gradle"/>
                 <output args="-q broken"/>
             </sample>
Index: build.gradle
===================================================================
--- build.gradle	(revision 1571)
+++ build.gradle	(working copy)
@@ -14,6 +14,7 @@
 import org.apache.ivy.plugins.resolver.*
 import org.gradle.build.docs.UserGuideTransformTask
 import org.gradle.build.docs.ExtractSnippetsTask
+import org.gradle.build.docs.SampleElementValidator
 
 /**
  * For building Gradle you usually don't need to specify any properties. Only certain functionality of the Gradle requires
@@ -417,6 +418,7 @@
     destFile = new File(docbookSrc, 'userguide.xml')
     snippetsDir = project.snippetsDir
     classpath = configurations.userGuideTask
+    validator = new SampleElementValidator()
 }
 userguideSrc.doFirst {
     userguideSrc.javadocUrl = "http://www.gradle.org/${javadocRemoteDir}"
