From ddbab364390462255d69669f5b5f4d36349fb04e Mon Sep 17 00:00:00 2001
From: Arthur Barrett <abarrett@edx.org>
Date: Wed, 6 Mar 2013 14:33:04 -0500
Subject: [PATCH] Added instructions/documentation to the studio template for
 content authors.

---
 .../xmodule/xmodule/css/annotatable/display.scss  | 12 ++++++++++++
 .../xmodule/templates/annotatable/default.yaml    | 15 ++++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/common/lib/xmodule/xmodule/css/annotatable/display.scss b/common/lib/xmodule/xmodule/css/annotatable/display.scss
index e3316c0c4a..308b379ec1 100644
--- a/common/lib/xmodule/xmodule/css/annotatable/display.scss
+++ b/common/lib/xmodule/xmodule/css/annotatable/display.scss
@@ -29,6 +29,18 @@ $body-font-size: em(14);
     padding-top: .5em;
     @include clearfix;
   }
+
+  ul.instructions-template {
+    list-style: disc;
+    margin-left: 4em;
+    b { font-weight: bold; }
+    i { font-style: italic; }
+    code { 
+      display: inline;
+      white-space: pre; 
+      font-family: Courier New, monospace;
+    }
+  }
 }
 
 .annotatable-toggle {
diff --git a/common/lib/xmodule/xmodule/templates/annotatable/default.yaml b/common/lib/xmodule/xmodule/templates/annotatable/default.yaml
index 27de411412..cc95cca46d 100644
--- a/common/lib/xmodule/xmodule/templates/annotatable/default.yaml
+++ b/common/lib/xmodule/xmodule/templates/annotatable/default.yaml
@@ -3,9 +3,18 @@ metadata:
     display_name: 'Annotation'
 data: |
     <annotatable>
-        <instructions><p>Add instructions for the exercise here.</p></instructions>
+        <instructions>
+            <p>Enter your (optional) instructions for the exercise in HTML format.</p>
+            <p>Annotations are specified by by an <code>&lt;annotation&gt;</code> tag which may may have the following attributes:</p>
+            <ul class="instructions-template">
+                <li><code>title</code> (optional). Title of the annotation. Defaults to <i>Commentary</i> if omitted.</li>
+                <li><code>body</code> (<b>required</b>). Text of the annotation.</li>
+                <li><code>problem</code> (optional). Numeric index of the problem associated with this annotation. This is a zero-based index, so the first problem on the page would have <code>problem="0"</code>.</li>
+                <li><code>highlight</code> (optional). Possible values: yellow, red, orange, green, blue, or purple. Defaults to yellow if this attribute is omitted.</li>
+            </ul>
+        </instructions>
         <p>Add your HTML with annotation spans here.</p>
-        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. <annotation title="My title (optional)" body="My comment (required)" highlight="yellow" problem="0 (numeric index of the problem, zero-based)">Ut sodales laoreet est, egestas gravida felis egestas nec.</annotation> Aenean at volutpat erat. Cras commodo viverra nibh in aliquam.</p> 
-        <p>Nulla facilisi. <annotation body="simple annotation" problem="1">Pellentesque id vestibulum libero.</annotation> Suspendisse potenti. Morbi scelerisque nisi vitae felis dictum mattis. Nam sit amet magna elit. Nullam volutpat cursus est, sit amet sagittis odio vulputate et. Curabitur euismod, orci in vulputate imperdiet, augue lorem tempor purus, id aliquet augue turpis a est. Aenean a sagittis libero. Praesent fringilla pretium magna, non condimentum risus elementum nec. Pellentesque faucibus elementum pharetra. Pellentesque vitae metus eros.</p>
+        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. <annotation title="My title" body="My comment" highlight="yellow" problem="0">Ut sodales laoreet est, egestas gravida felis egestas nec.</annotation> Aenean at volutpat erat. Cras commodo viverra nibh in aliquam.</p> 
+        <p>Nulla facilisi. <annotation body="Basic annotation example." problem="1">Pellentesque id vestibulum libero.</annotation> Suspendisse potenti. Morbi scelerisque nisi vitae felis dictum mattis. Nam sit amet magna elit. Nullam volutpat cursus est, sit amet sagittis odio vulputate et. Curabitur euismod, orci in vulputate imperdiet, augue lorem tempor purus, id aliquet augue turpis a est. Aenean a sagittis libero. Praesent fringilla pretium magna, non condimentum risus elementum nec. Pellentesque faucibus elementum pharetra. Pellentesque vitae metus eros.</p>
     </annotatable>
 children: []