1 files changed, 23 insertions, 31 deletions

diff --git a/doc/reference/items/language/rule.qdoc b/doc/reference/items/language/rule.qdoc
index 3a14c2fa6..62a32caf5 100644
--- a/doc/reference/items/language/rule.qdoc
+++ b/doc/reference/items/language/rule.qdoc
@@ -45,30 +45,28 @@
     The following rule takes text files and replaces Windows-style line endings with their
     Unix-style counterparts. We will look at it one piece at a time.
 
-    \code
-    Rule {
-        multiplex: false
-    \endcode
+    \quotefromfile ../examples/rule/rule.qbs
+
+    \skipto Rule
+    \printuntil multiplex: false
+
     A \e {multiplex rule} creates one transformer that takes all input artifacts with the
     matching input file tag and creates one or more output artifacts. We are setting the
     respective property to \c false here, indicating that we want to create one transformer
     per input file.
     \note This is actually the default, so the above assignment is not required.
-    \code
-        inputs: ["txt_input"]
-    \endcode
+
+    \printuntil inputs: ["txt_input"]
+
     Here we are specifying that our rule is interested in input files that have the tag
     \c "txt_input". Such files could be source files, in which case you would tag them
     using a \l{Group}. Or they could in turn get generated by a different rule,
     in which case that rule would assign the file tag.
     The files matching the tag will be available in the \l{prepare} script under the name
     \c inputs (see \l{inputs and outputs}{The inputs and outputs Variables}).
-    \code
-        Artifact {
-            filePath: input.fileName + ".out"
-            fileTags: ["txt_output"]
-        }
-    \endcode
+
+    \printuntil }
+
     Here we are specifying that for every input file, we want to create one output file
     whose name is the same as the input file, but with an additional extension. Because we are
     giving a relative path, \QBS will prepend that path by the product's build directory.
@@ -82,24 +80,8 @@
     \l Artifact items. The set of output artifacts will be available in the prepare script
     under the name \c outputs (see \l{inputs and outputs}{The inputs and outputs Variables}).
 
-    \code
-        prepare: {
-            var cmd = new JavaScriptCommand();
-            cmd.description = input.fileName + "->" + output.fileName;
-            cmd.highlight = "codegen";
-            cmd.sourceCode = function() {
-                var file = new TextFile(input.filePath);
-                var content = file.readAll();
-                file.close()
-                content = content.replace(/\r\n/g, "\n");
-                file = new TextFile(output.filePath, TextFile.WriteOnly);
-                file.write(content);
-                file.close();
-            }
-            return [cmd];
-        }
-    }
-    \endcode
+    \printuntil /^\s{4}\}/
+
     The prepare script shown above puts everything together by creating the command that does
     the actual transformation of the file contents, employing the help of the
     \l{TextFile Service}{TextFile} class.
@@ -184,6 +166,16 @@
             our executable.
     \endlist
 
+    \section1 A Complete Example
+
+    The following code snippet shows a single \l{Rule} within a \l{Product} and summarizes the
+    previous sections.
+
+    \note The product's type is set up to the \c "txt_output" file tag to tell \QBS that the
+    product depends on output artifacts produced by the custom rule. Otherwise the rule would not
+    be executed.
+
+    \quotefile ../examples/rule/rule.qbs
 */
 
 /*!