--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/farol/templates/common_edits.j2	Mon Oct 06 14:09:57 2014 +0200
@@ -0,0 +1,38 @@
+{#
+# Description:
+# Web Template used in Farol Design
+#
+# Authors:
+# Benoît Allard <benoit.allard@greenbone.net>
+#
+# Copyright:
+# Copyright (C) 2014 Greenbone Networks GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+-#}
+
+{% from "macros.j2" import textinput, examples %}
+
+{% macro edit_title_type(doctitle, doctype) %}
+{% call textinput("title", "Document Title", "", doctitle, required=True) %}
+<p><strong>Document Title</strong> is a definitive canonical name for the document, providing enough descriptive content to differentiate from other similar documents, ideally providing a unique “handle.” While this field is largely up to the document producer, ICASI has some recommendations:</p>
+<p>The title should be succinct and promptly give the reader an idea of what is to come. If the document producer also publishes a human-friendly document that goes hand-in-hand with a CVRF document, it is recommend that both documents use the same title. It is further recommended to include the manufacturer name with any product names mentioned in the title.</p>
+{{ examples(['Cisco IPv6 Crafted Packet Vulnerability', 'CERT Vulnerabilities in Kerberos 5 Implementation', 'Cisco Content Services Switch 11000 Series DNS Negative Cache of Information Denial-of-Service Vulnerability', 'Symantec Brightmail AntiSpam Static Database Password', 'HPSBUX02697 SSRT100591 rev.1 - HP-UX Running Java, Remote Unauthorized Access, Disclosure of Information, and Other Vulnerabilities', 'Microsoft Vulnerability in the Microsoft Data Access Components (MDAC) Function Could Allow Code Execution', 'Microsoft Vulnerability in Windows Explorer Could Allow Remote Code Execution' ]) }}
+{% endcall %}
+{% call textinput("type", "Document Type", "Security Advisory", doctype, required=True) %}
+<p><strong>Document Type</strong> is a short canonical name, chosen by the document producer, which will inform the end user as to the type of document.</p>
+{{ examples(['Vulnerability Report', 'Security Bulletin', 'Security Notice']) }}
+{% endcall %}
+{% endmacro %}

--- a/farol/templates/document/edit_title.j2	Mon Oct 06 11:44:01 2014 +0200
+++ b/farol/templates/document/edit_title.j2	Mon Oct 06 14:09:57 2014 +0200
@@ -24,13 +24,12 @@
 -#}
 
 {% extends "base.j2" %}
-{% from "macros.j2" import textinput %}
+{% from "common_edits.j2" import edit_title_type %}
 {% block title %}Edit the title{% endblock %}
 
 {% block content %}
 <form role="form" method="POST">
-{{ textinput("title", "Document Title", "", title, required=True) }}
-{{ textinput("type", "Document Type", "", _type, required=True) }}
+{{ edit_title_type(title, _type) }}
 <button class="btn btn-primary" type="submit">Update</button>
 <a class="btn btn-danger" href="{{ url_for('.view') }}">Cancel</a>
 </form>

--- a/farol/templates/macros.j2	Mon Oct 06 11:44:01 2014 +0200
+++ b/farol/templates/macros.j2	Mon Oct 06 14:09:57 2014 +0200
@@ -25,13 +25,22 @@
 
 {% macro textinput(name, label, placeholder="", value=None, required=False, type="text", extras={}, help='') %}
 <div class="form-group">
-  <label for="{{ name }}">{{ label }}:{% if required %}<span class="text-danger"> *</span>{% endif %}</label>
+  {% if caller %}
+    {% set content=caller () %}
+    {% call modal(name + "_modal", label) %}
+      {{ content }}
+    {% endcall %}
+  {% endif %}
+  <label for="{{ name }}">{{ label }}:
+    {% if required %}<span class="text-danger"> *</span>{% endif %}
+    {% if caller %}<a href="#{{ name }}_modal" data-toggle="modal">?</a>{% endif %}
+  </label>
   {% if type == "datetime" %}<div class="input-group">{% endif %}
   <input
      type="{{ type }}"
      {%- if type != 'file' %} class="form-control"{% endif %}
      id="{{ name }}" name="{{ name }}"
-     placeholder="{{ placeholder }}"
+     {%- if placeholder %} placeholder="{{ placeholder }}"{% endif %}
      {%- if value %} value="{{ value }}"{% endif %}
      {%- if required %} required{% endif %}
      {{- extras | xmlattr }}>
@@ -47,6 +56,26 @@
 </div>
 {% endmacro %}
 
+{% macro modal(id, title, size=None) %}
+<div class="modal fade" id="{{ id }}" tabindex="-1" role="dialog" aria-labelledby="{{ id }}_title" aria-hidden="true">
+  <div class="modal-dialog{{ ' modal-%s' % size if size}}">
+    <div class="modal-content">
+      <div class="modal-header">
+        <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
+        <h4 class="modal-title" id="{{ id }}_title">{{ title }}</h4>
+      </div>
+      <div class="modal-body">
+        {{ caller() }}
+      </div>{# We don't need a footer yet ...
+      <div class="modal-footer">
+        <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
+        <button type="button" class="btn btn-primary">Save changes</button>
+      </div>#}
+    </div>{# /.modal-content #}
+  </div>{# /.modal-dialog #}
+</div>{# /.modal #}
+{% endmacro %}
+
 {% macro textarea(name, label, placeholder="", value=None, rows=10, required=False) %}
 <div class="form-group">
   <label for="{{ name }}">{{ label }}:{% if required %}<span class="text-danger"> *</span>{% endif %}</label>
@@ -107,3 +136,25 @@
   </div>
 </div>
 {% endmacro %}
+
+{% macro examples(list) %}
+{% if False %}
+<dl>
+  <dt>Example{{ 's' if list | length > 1 }}:</dt>
+  {% for elem in list %}
+  <dd><samp>{{ elem }}</samp></dd>
+  {% endfor %}
+</dl>
+{% else %}
+<p><strong>Example{{ 's' if list | length > 1 }}:</strong></p>
+{% if list | length == 1 %}
+<samp>{{ list[0] }}</samp>
+{% else %}
+<ul>
+  {%- for elem in list %}
+    <li><samp>{{ elem }}</samp></li>
+  {%- endfor %}
+</ul>
+{% endif %}
+{% endif %}
+{% endmacro %}

--- a/farol/templates/new.j2	Mon Oct 06 11:44:01 2014 +0200
+++ b/farol/templates/new.j2	Mon Oct 06 14:09:57 2014 +0200
@@ -25,6 +25,7 @@
 
 {% extends "base.j2" %}
 {% from "macros.j2" import textinput, textarea, panel %}
+{% from "common_edits.j2" import edit_title_type %}
 
 {% set active='new' %}
 
@@ -158,8 +159,7 @@
     <div id="newDoc" class="panel-collapse collapse">
       <div class="panel-body">
         <form role="form" method="POST">
-          {{ textinput("title", "Document Title", required=True) }}
-          {{ textinput("type", "Document Type", "Security Advisory", required=True) }}
+          {{ edit_title_type() }}
           <button type="submit" class="btn btn-primary">Create</button>
         </form>
       </div>