From 0dee5602cacb46e1120bc2339464c89bea34ddaa Mon Sep 17 00:00:00 2001
From: Marko Gronroos <magi@vaadin.com>
Date: Thu, 11 Feb 2016 19:48:45 +0200
Subject: Fixed critically broken comment blocks, broken emphasis and escaping,
 and some other formatting, and moved book preface, chapter structure, and
 index to the docs repository.

Change-Id: If9299da4415f3181d59b8384e5ac96f940bd5229
---
 documentation/advanced/advanced-security.asciidoc  |  13 +-
 documentation/advanced/advanced-spring.asciidoc    |  42 ++--
 documentation/advanced/advanced-windows.asciidoc   |  12 +-
 .../application/application-environment.asciidoc   |  26 +-
 .../application/application-errors.asciidoc        |  17 +-
 documentation/book-preface.asciidoc                | 271 ---------------------
 documentation/book.asc                             | 100 --------
 .../clientside/clientside-compiling.asciidoc       |   9 +-
 .../clientsideapp/clientsideapp-overview.asciidoc  |  22 +-
 .../components/components-calendar.asciidoc        |  38 ++-
 .../components/components-features.asciidoc        |  36 ++-
 .../components/components-selection.asciidoc       |   6 +-
 documentation/index.asciidoc                       |   1 -
 .../jpacontainer/chapter-jpacontainer.asciidoc     |   2 -
 .../jpacontainer-fieldfactory.asciidoc             |  21 +-
 documentation/layout/chapter-layout.asciidoc       |  16 +-
 documentation/layout/layout-csslayout.asciidoc     |  18 +-
 documentation/portal/portal-deployment.asciidoc    |  59 ++---
 documentation/themes/themes-creating.asciidoc      |  24 +-
 documentation/themes/themes-css.asciidoc           |  53 ++--
 20 files changed, 158 insertions(+), 628 deletions(-)
 delete mode 100644 documentation/book-preface.asciidoc
 delete mode 100644 documentation/book.asc
 delete mode 100644 documentation/index.asciidoc

diff --git a/documentation/advanced/advanced-security.asciidoc b/documentation/advanced/advanced-security.asciidoc
index d3b0a5249c..e04a3bc067 100644
--- a/documentation/advanced/advanced-security.asciidoc
+++ b/documentation/advanced/advanced-security.asciidoc
@@ -20,11 +20,10 @@ attack] by injecting offensive JavaScript code in such components. See other
 sources for more information about cross-site scripting.
 
 Offensive code can easily be injected with [literal]#++<script>++# markup or in
-tag attributes as events, such as
-[parameter]#onLoad#.////
-TODO Consider an example, Alice, Bob,
-etc.
-////
+tag attributes as events, such as [parameter]#onLoad#.
+
+// TODO Consider an example, Alice, Bob, etc.
+
 Cross-site scripting vulnerabilities are browser dependent, depending on the
 situations in which different browsers execute scripting markup.
 
@@ -50,7 +49,3 @@ and is not sanitized. As the entire purpose of the [classname]#RichTextArea#
 component is to allow input of formatted text, you can not just remove all HTML
 tags. Also many attributes, such as [parameter]#style#, should pass through the
 sanitization.
-
-
-
-
diff --git a/documentation/advanced/advanced-spring.asciidoc b/documentation/advanced/advanced-spring.asciidoc
index 7f83b864fd..21b079076c 100644
--- a/documentation/advanced/advanced-spring.asciidoc
+++ b/documentation/advanced/advanced-spring.asciidoc
@@ -209,7 +209,7 @@ The Ivy dependency is as follows:
 [subs="normal"]
 ----
     &lt;dependency org="com.vaadin" name="vaadin-spring"
-                rev="[replaceable]#latest.release#"/&gt;
+                rev="[replaceable]##latest.release##"/&gt;
 ----
 The Maven dependency is as follows:
 
@@ -218,17 +218,17 @@ The Maven dependency is as follows:
     &lt;dependency&gt;
         &lt;groupId&gt;com.vaadin&lt;/groupId&gt;
         &lt;artifactId&gt;vaadin-spring&lt;/artifactId&gt;
-        &lt;version&gt;[replaceable]#LATEST#&lt;/version&gt;
+        &lt;version&gt;[replaceable]##LATEST##&lt;/version&gt;
     &lt;/dependency&gt;
 ----
 
-[[advanced.spring.peparing]]
+[[advanced.spring.preparing]]
 == Preparing Application for Spring
 
 A Vaadin application that uses Spring must have a file named
 [filename]#applicationContext.xml# in the [filename]#WEB-INF# directory.
 
-[subs="normal"]
+[subs="verbatim,replacements,quotes"]
 ----
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;beans xmlns="http://www.springframework.org/schema/beans"
@@ -240,12 +240,10 @@ A Vaadin application that uses Spring must have a file named
     http://www.springframework.org/schema/context
     http://www.springframework.org/schema/context/spring-context-4.1.xsd"&gt;
 
-  //Configuration object
-
+  &lt;!-- Configuration object --&gt;
   &lt;bean class="[replaceable]#com.example.myapp.MySpringUI.MyConfiguration#" /&gt;
 
-  //Location for automatically scanned beans
-
+  &lt;!-- Location for automatically scanned beans --&gt;
   &lt;context:component-scan
       base-package="[replaceable]#com.example.myapp.domain#" /&gt;
 &lt;/beans&gt;
@@ -395,7 +393,7 @@ navigator.
 public class MySpringUI extends UI {
     @Autowired
     SpringViewProvider viewProvider;
-    
+
     @Override
     protected void init(VaadinRequest request) {
         Navigator navigator = new Navigator(this, this);
@@ -498,25 +496,23 @@ If the list contains [parameter]#UI.class#, the view is available to all UIs.
 @SpringView(name="myview", uis={UI.class})
 ----
 
-
 In the following, we have a login view that accesses a session-scoped user
 object. Here, we use a constant to define the view name, so that we can use the
 constant when navigating to it.
 
-
 [source, java]
 ----
 @SpringView(name=LoginView.NAME)
 public class LoginView extends CustomComponent
                        implements View {
     public final static String NAME = "";
-    
+
     // Here we inject to the constructor and actually do
     // not store the injected object to use it later
     @Autowired
     public LoginView(User user) {
         VerticalLayout layout = new VerticalLayout();
-        
+
         // An input field for editing injected data
         BeanItem<User> item = new BeanItem<User>(user);
         TextField username = new TextField("User name",
@@ -528,10 +524,10 @@ public class LoginView extends CustomComponent
         layout.addComponent(new Button("Login", e ->
             getUI().getNavigator().
                 navigateTo(MainView.VIEWNAME)));
-        
+
         setCompositionRoot(layout);
     }
-    
+
     @Override
     public void enter(ViewChangeEvent event) {}
 }
@@ -539,13 +535,11 @@ public class LoginView extends CustomComponent
 
 You could now navigate to the view from any other view in the UI with:
 
-
 [source, java]
 ----
 getUI().getNavigator().navigateTo(LoginView.VIEWNAME);
 ----
 
-
 endif::web[]
 
 [[advanced.spring.accesscontrol]]
@@ -664,7 +658,6 @@ default servlet as follows, and map the other servlets to other URL paths:
 ----
 &lt;web-app&gt;
   ...
-
   &lt;servlet&gt;
     &lt;servlet-name&gt;Default&lt;/servlet-name&gt;
     &lt;servlet-class&gt;
@@ -674,23 +667,18 @@ default servlet as follows, and map the other servlets to other URL paths:
 
   &lt;servlet-mapping&gt;
     &lt;servlet-name&gt;Default&lt;/servlet-name&gt;
-    &lt;url-pattern&gt;[replaceable]#/myspringuis/*#&lt;/url-pattern&gt;
+    &lt;url-pattern&gt;[replaceable]##/myspringuis/*##&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;
 
   &lt;servlet-mapping&gt;
     &lt;servlet-name&gt;Default&lt;/servlet-name&gt;
-    &lt;url-pattern&gt;/VAADIN/*&lt;/url-pattern&gt;
+    &lt;url-pattern&gt;/VAADIN/+++*+++&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;
 &lt;/web-app&gt;
 ----
-With such a setting, paths to Spring UIs would have base path
-[filename]#/myapp/myspringuis#, to which the (optional) UI path would be
-appended. The [filename]#/VAADIN/*# only needs to be mapped to the servlet if
-there are no other Vaadin servlets.
-
 
+With such a setting, paths to Spring UIs would have base path [filename]#/myapp/myspringuis#, to which the (optional) UI path would be appended.
+The [filename]#/VAADIN/*# only needs to be mapped to the servlet if there are no other Vaadin servlets.
 
 (((range="endofrange", startref="term.advanced.spring.springlong")))
 (((range="endofrange", startref="term.advanced.spring.spring")))
-
-
diff --git a/documentation/advanced/advanced-windows.asciidoc b/documentation/advanced/advanced-windows.asciidoc
index 741812ffd2..5bd77f7c80 100644
--- a/documentation/advanced/advanced-windows.asciidoc
+++ b/documentation/advanced/advanced-windows.asciidoc
@@ -35,7 +35,9 @@ a UI">>.
 
 Because of the special nature of AJAX applications, use of multiple windows uses
 require some
-caveats.////
+caveats.
+
+////
 TODO Re-enable We will go through them later in &lt;xref
 linkend="advanced.windows.caveats"/&gt;.
 ////
@@ -71,7 +73,7 @@ public static class MyPopupUI extends UI {
     @Override
     protected void init(VaadinRequest request) {
         getPage().setTitle("Popup Window");
-        
+
         // Have some content for it
         VerticalLayout content = new VerticalLayout();
         Label label =
@@ -99,7 +101,7 @@ You can configure the features of the popup window with
 window features, as defined in the HTML specification.
 
 status=[parameter]#0|1#:: Whether the status bar at the bottom of the window should be enabled.
-[parameter]##:: 
+[parameter]##::
 scrollbars:: Enables scrollbars in the window if the document area is bigger than the view area of the window.
 resizable:: Allows the user to resize the browser window (no effect for tabs).
 menubar:: Enables the browser menu bar.
@@ -174,7 +176,3 @@ public class MyPopup extends UI {
     }
 }
 ----
-
-
-
-
diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc
index 5a2bf7ecbf..8907222a24 100644
--- a/documentation/application/application-environment.asciidoc
+++ b/documentation/application/application-environment.asciidoc
@@ -120,37 +120,37 @@ Servlet 2.4 application. You simply specify the UI class with the
 [parameter]#UI# parameter for the [classname]#com.vaadin.server.VaadinServlet#.
 The servlet is then mapped to a URL path in a standard way for Java Servlets.
 
-[subs="normal"]
+[subs="verbatim,replacements,quotes"]
 ----
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;web-app
   id="WebApp_ID" version="2.4"
-  xmlns="http://java.sun.com/xml/ns/j2ee" 
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+  xmlns="http://java.sun.com/xml/ns/j2ee"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
      http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"&gt;
 
   &lt;servlet&gt;
-    &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+    &lt;servlet-name&gt;[replaceable]##myservlet##&lt;/servlet-name&gt;
     &lt;servlet-class&gt;
-        com.vaadin.server.VaadinServlet
+        [replaceable]##com.vaadin.server.VaadinServlet##
     &lt;/servlet-class&gt;
 
     &lt;init-param&gt;
       &lt;param-name&gt;UI&lt;/param-name&gt;
-      &lt;param-value&gt;**com.ex.myprj.MyUI**&lt;/param-value&gt;
+      &lt;param-value&gt;[replaceable]##com.ex.myprj.MyUI##&lt;/param-value&gt;
     &lt;/init-param&gt;
 
     &lt;!-- If not using the default widget set--&gt;
     &lt;init-param&gt;
       &lt;param-name&gt;widgetset&lt;/param-name&gt;
-      &lt;param-value&gt;**com.ex.myprj.MyWidgetSet**&lt;/param-value&gt;
+      &lt;param-value&gt;[replaceable]##com.ex.myprj.MyWidgetSet##&lt;/param-value&gt;
     &lt;/init-param&gt;
   &lt;/servlet&gt;
 
   &lt;servlet-mapping&gt;
-    &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
-    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+    &lt;servlet-name&gt;[replaceable]##myservlet##&lt;/servlet-name&gt;
+    &lt;url-pattern&gt;[replaceable]##/*##&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;
 &lt;/web-app&gt;
 ----
@@ -170,8 +170,8 @@ such as Servlet 3.0, you should use:
 ----
 &lt;web-app
   id="WebApp_ID" version="**3.0**"
-  xmlns="http://java.sun.com/xml/ns/j2ee" 
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+  xmlns="http://java.sun.com/xml/ns/j2ee"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="**http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd**"&gt;
 ----
 Servlet 3.0 support is useful for at least server push.
@@ -496,7 +496,3 @@ You can also access other [classname]#HttpSession# and
 [classname]#PortletSession# session properties through the interface, such as
 set and read session attributes that are shared by all servlets belonging to a
 particular servlet or portlet session.
-
-
-
-
diff --git a/documentation/application/application-errors.asciidoc b/documentation/application/application-errors.asciidoc
index 22f962a07c..f1406191bb 100644
--- a/documentation/application/application-errors.asciidoc
+++ b/documentation/application/application-errors.asciidoc
@@ -29,7 +29,7 @@ The result is shown in <<figure.application.errors.error-indicator>>.
 
 [[figure.application.errors.error-indicator]]
 .Error Indicator Active
-image::img/errorindicator-example2.png[]
+image::img/errorindicator-example2.png[scaledwidth=40%]
 
 [[application.errors.reconnect]]
 == Connection Fault
@@ -101,7 +101,7 @@ as follows:
 ----
 getService().setSystemMessagesProvider(
     new SystemMessagesProvider() {
-    @Override 
+    @Override
     public SystemMessages getSystemMessages(
         SystemMessagesInfo systemMessagesInfo) {
         CustomizedSystemMessages messages =
@@ -124,7 +124,7 @@ endif::web[]
 
 ifdef::web[]
 [[application.errors.unchecked-exceptions]]
-== Handling Uncaught Exceptions 
+== Handling Uncaught Exceptions
 
 Handling events can result in exceptions either in the application logic or in
 the framework itself, but some of them may not be caught properly by the
@@ -150,7 +150,7 @@ behavior of the default handler.
 
 [source, java]
 ----
-// Here's some code that produces an uncaught exception 
+// Here's some code that produces an uncaught exception
 final VerticalLayout layout = new VerticalLayout();
 final Button button = new Button("Click Me!",
     new Button.ClickListener() {
@@ -170,13 +170,13 @@ UI.getCurrent().setErrorHandler(new DefaultErrorHandler() {
              t = t.getCause())
             if (t.getCause() == null) // We're at final cause
                 cause += t.getClass().getName() + "<br/>";
-        
+
         // Display the error message in a custom fashion
         layout.addComponent(new Label(cause, ContentMode.HTML));
-           
+
         // Do the default error handling (optional)
         doDefault(event);
-    } 
+    }
 });
 ----
 
@@ -191,6 +191,3 @@ thrown. See the source code of the implementation for more details. You can call
 error. If the error is not associated with a component, it returns null.
 
 endif::web[]
-
-
-
diff --git a/documentation/book-preface.asciidoc b/documentation/book-preface.asciidoc
deleted file mode 100644
index 7803a9b502..0000000000
--- a/documentation/book-preface.asciidoc
+++ /dev/null
@@ -1,271 +0,0 @@
-[[preface]]
-[preface]
-[]
-== Preface
-
-This book provides an overview of the Vaadin Framework and covers the most
-important topics that you might encounter while developing applications with it.
-A more detailed documentation of the individual classes, interfaces, and methods
-is given in the Vaadin API Reference.
-
-This edition mostly covers Vaadin Framework 7.5 released in 2015, as well as the
-latest versions of Vaadin Pro Tools. In addition to updates in the core
-framework, the Volume 1 includes a new chapter about the new Vaadin Designer
-plugin for Eclipse. New add-ons, namely Vaadin Spreadsheet, Vaadin CDI, and
-Vaadin Spring, which were released earlier this year, are documented in Volume
-2.
-
-Writing this manual is an ongoing work and it is rarely completely up-to-date
-with the quick-evolving product. Some features may not be included in this book
-yet. For the most current version, please see the on-line edition available at
-http://vaadin.com/book. You can also find PDF and EPUB versions of the book
-there. You may find the other versions more easily searchable than the printed
-book. The index in the book is incomplete and will be expanded later. The web
-edition also has some additional technical content, such as some example code
-and additional sections that you may need when actually doing development. The
-purpose of the slightly abridged print edition is more to be an introductionary
-textbook to Vaadin, and still fit in your pocket.
-
-Also, many Vaadin 7 features are showcased as mini-tutorials, which are
-available in the Vaadin Wiki at https://vaadin.com/wiki/-/wiki/Main/Vaadin+7.
-
-= Who is This Book For?
-
-This book is intended for software developers who use, or are considering to
-use, Vaadin to develop web applications.
-
-The book assumes that you have some experience with programming in Java, but if
-not, it is at least as easy to begin learning Java with Vaadin as with any other
-UI framework. No knowledge of AJAX is needed as it is well hidden from the
-developer.
-
-You may have used some desktop-oriented user interface frameworks for Java, such
-as AWT, Swing, or SWT, or a library such as Qt for C++. Such knowledge is useful
-for understanding the scope of Vaadin, the event-driven programming model, and
-other common concepts of UI frameworks, but not necessary.
-
-If you do not have a web graphics designer at hand, knowing the basics of HTML
-and CSS can help so that you can develop presentation themes for your
-application. A brief introduction to CSS is provided. Knowledge of Google Web
-Toolkit (GWT) may be useful if you develop or integrate new client-side
-components.
-
-
-= Organization of This Book
-
-The Book of Vaadin gives an introduction to what Vaadin is and how you use it to
-develop web applications.
-
-Volume 1
-
-<<dummy/../../../framework/introduction/introduction-overview.asciidoc#intro.overview,"Introduction">>:: The chapter gives an introduction to the application architecture supported by
-Vaadin, the core design ideas behind the framework, and some historical
-background.
-
-<<dummy/../../../framework/getting-started/getting-started-overview.asciidoc#getting-started.overview,"Getting Started with Vaadin">>:: This chapter gives practical instructions for installing Vaadin and the
-reference toolchain, including the Vaadin Plugin for Eclipse, how to run and
-debug the demos, and how to create your own application project in the Eclipse
-IDE.
-
-<<dummy/../../../framework/architecture/architecture-overview.asciidoc#architecture.overview,"Architecture">>:: This chapter gives an introduction to the architecture of Vaadin and its major
-technologies, including AJAX, Google Web Toolkit, and event-driven programming.
-
-<<dummy/../../../framework/application/application-overview.asciidoc#application.overview,"Writing a Server-Side Web Application">>:: This chapter gives all the practical knowledge required for creating
-applications with Vaadin, such as window management, application lifecycle,
-deployment in a servlet container, and handling events, errors, and resources.
-
-<<dummy/../../../framework/components/components-overview.asciidoc#components.overview,"User Interface Components">>:: This chapter gives the basic usage documentation for all the (non-layout) user
-interface components in Vaadin and their most significant features. The
-component sections include examples for using each component, as well as for
-styling with CSS/Sass.
-
-<<dummy/../../../framework/layout/layout-overview.asciidoc#layout.overview,"Managing Layout">>:: This chapter describes the layout components, which are used for managing the
-layout of the user interface, just like in any desktop application frameworks.
-
-<<dummy/../../../designer/designer-overview.asciidoc#designer.overview,"Vaadin Designer">>:: This chapter gives instructions for using Vaadin Designer, a visual tool for the
-Eclipse IDE for creating composite designs, such as for UIs, views, or other
-composites.
-
-
-
-Volume 2:
-
-<<dummy/../../../framework/themes/themes-overview.asciidoc#themes.overview,"Themes">>:: This chapter gives an introduction to Cascading Style Sheets (CSS) and Sass and
-explains how you can use them to build custom visual themes for your
-application.
-
-<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding Components to Data">>:: This chapter gives an overview of the built-in data model of Vaadin, consisting
-of properties, items, and containers.
-
-<<dummy/../../../framework/sqlcontainer/sqlcontainer-overview.asciidoc#sqlcontainer.overview,"Vaadin SQLContainer">>:: This chapter gives documentation for the SQLContainer, which allows binding
-Vaadin components to SQL queries.
-
-<<dummy/../../../framework/advanced/advanced-overview.asciidoc#advanced.overview,"Advanced Web Application Topics">>:: This chapter provides many special topics that are commonly needed in
-applications, such as opening new browser windows, embedding applications in
-regular web pages, low-level management of resources, shortcut keys, debugging,
-etc.
-
-<<dummy/../../../framework/portal/portal-overview.asciidoc#portal.overview,"Portal Integration">>:: This chapter describes the development of Vaadin applications as portlets which
-you can deploy to any portal supporting Java Portlet API 2.0 (JSR-286). The
-chapter also describes the special support for Liferay and the Control Panel,
-IPC, and WSRP add-ons.
-
-<<dummy/../../../framework/clientside/clientside-overview.asciidoc#clientside.overview,"Client-Side Vaadin Development">>:: This chapter gives an introduction to creating and developing client-side
-applications and widgets, including installation, compilation, and debugging.
-
-<<dummy/../../../framework/clientsideapp/clientsideapp-overview.asciidoc#clientsideapp.overview,"Client-Side Applications">>:: This chapter describes how to develop client-side applications and how to
-integrate them with a back-end service.
-
-<<dummy/../../../framework/clientsidewidgets/clientsidewidgets-overview.asciidoc#clientsidewidgets.overview,"Client-Side Widgets">>:: This chapter describes the built-in widgets (client-side components) available
-for client-side development. The built-in widgets include Google Web Toolkit
-widgets as well as Vaadin widgets.
-
-<<dummy/../../../framework/gwt/gwt-overview.asciidoc#gwt.overview,"Integrating with the Server-Side">>:: This chapter describes how to integrate client-side widgets with their
-server-side counterparts for the purpose of creating new server-side components.
-The chapter also covers integrating JavaScript components.
-
-
-
-<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">>:: This chapter gives instructions for downloading and installing add-on components
-from the Vaadin Directory.
-
-<<dummy/../../../charts/charts-overview.asciidoc#charts.overview,"Vaadin Charts">>:: This chapter documents the use of the Vaadin Charts add-on component for
-interactive charting with many diagram types. The add-on includes the Chart and
-Timeline components.
-
-<<dummy/../../../framework/jpacontainer/jpacontainer-overview.asciidoc#jpacontainer.overview,"Vaadin JPAContainer">>:: This chapter gives documentation of the JPAContainer add-on, which allows
-binding Vaadin components directly to relational and other databases using Java
-Persistence API (JPA).
-
-<<dummy/../../../mobile/mobile-overview.asciidoc#mobile.overview,"Mobile Applications with TouchKit">>:: This chapter gives examples and reference documentation for using the Vaadin
-TouchKit add-on for developing mobile applications.
-
-<<dummy/../../../spreadsheet/spreadsheet-overview.asciidoc#spreadsheet.overview,"Vaadin Spreadsheet">>:: This chapter gives documentation of the Vaadin Spreadsheet add-on, which
-provides a Microsoft Excel compatible spreadsheet component.
-
-<<dummy/../../../testbench/testbench-overview.asciidoc#testbench.overview,"Vaadin TestBench">>:: This chapter gives the complete documentation of using the Vaadin TestBench tool
-for recording and executing user interface regression tests of Vaadin
-applications.
-
-
-
-
-= Supplementary Material
-
-The Vaadin websites offer plenty of material that can help you understand what
-Vaadin is, what you can do with it, and how you can do it.
-
-Demo Applications:: The most important demo application for Vaadin is the Sampler, which
-demonstrates the use of all basic components and features. You can run it
-on-line at http://demo.vaadin.com/ or download it as a WAR from the
-link:http://vaadin.com/download/[Vaadin download page].
-
-+
-Most of the code examples in this book and many others can be found online at
-http://demo.vaadin.com/book-examples-vaadin7/book/.
-
-Cheat Sheet:: The two-page cheat sheet illustrates the basic relationship hierarchy of the
-user interface and data binding classes and interfaces. You can download it at
-http://vaadin.com/book.
-
-Refcard:: The six-page DZone Refcard gives an overview to application development with
-Vaadin. It includes a diagram of the user interface and data binding classes and
-interfaces. You can find more information about it at
-https://vaadin.com/refcard.
-
-Address Book Tutorial:: The Address Book is a sample application accompanied with a tutorial that gives
-detailed step-by-step instructions for creating a real-life web application with
-Vaadin. You can find the tutorial from the product website.
-
-Developer's Website:: Vaadin Developer's Site at http://dev.vaadin.com/ provides various online
-resources, such as the ticket system, a development wiki, source repositories,
-activity timeline, development milestones, and so on.
-
-+
-The wiki provides instructions for developers, especially for those who wish to
-check-out and compile Vaadin itself from the source repository. The technical
-articles deal with integration of Vaadin applications with various systems, such
-as JSP, Maven, Spring, Hibernate, and portals. The wiki also provides answers to
-Frequently Asked Questions.
-
-Online Documentation:: You can read this book online at http://vaadin.com/book. Lots of additional
-material, including technical HOWTOs, answers to Frequently Asked Questions and
-other documentation is also available on link:http://dev.vaadin.com/[Vaadin
-web-site].
-
-
-
-
-= Support
-
-Stuck with a problem? No need to lose your hair over it, the Vaadin Framework
-developer community and the Vaadin company offer support to all of your needs.
-
-Community Support Forum:: You can find the user and developer community forum at http://vaadin.com/forum.
-Please use the forum to discuss any problems you might encounter, wishes for
-features, and so on. The answer to your problems may already lie in the forum
-archives, so searching the discussions is always the best way to begin.
-
-Report Bugs:: If you have found a possible bug in Vaadin, the demo applications, or the
-documentation, please report it by filing a ticket at the Vaadin developer's
-site at http://dev.vaadin.com/. You may want to check the existing tickets
-before filing a new one. You can make a ticket to make a request for a new
-feature as well, or to suggest modifications to an existing feature.
-
-Commercial Support:: Vaadin offers full commercial support and training services for the Vaadin
-Framework and related products. Read more about the commercial products at
-http://vaadin.com/pro for details.
-
-
-
-
-= About the Author
-
-Marko Grönroos is a professional writer and software developer working at Vaadin
-Ltd in Turku, Finland. He has been involved in web application development since
-1994 and has worked on several application development frameworks in C, C++, and
-Java. He has been active in many open source software projects and holds an
-M.Sc. degree in Computer Science from the University of Turku.
-
-
-= Acknowledgements
-
-Much of the book is the result of close work within the development team at
-Vaadin Ltd. Joonas Lehtinen, CEO of Vaadin Ltd, wrote the first outline of the
-book, which became the basis for the first two chapters. Since then, Marko
-Grönroos has become the primary author and editor. The development team has
-contributed several passages, answered numerous technical questions, reviewed
-the manual, and made many corrections.
-
-The contributors are (in rough chronological order):
-
-[options="compact"]
-* Joonas Lehtinen
-* Jani Laakso
-* Marko Grönroos
-* Jouni Koivuviita
-* Matti Tahvonen
-* Artur Signell
-* Marc Englund
-* Henri Sara
-* Jonatan Kronqvist
-* Mikael Grankvist (TestBench)
-* Teppo Kurki (SQLContainer)
-* Tomi Virtanen (Calendar)
-* Risto Yrjänä (Calendar)
-* John Ahlroos (Timeline)
-* Petter Holmström (JPAContainer)
-* Leif Åstrand
-* Guillermo Alvarez (Charts)
-
-
-= About Vaadin Ltd
-
-Vaadin Ltd is a Finnish software company specializing in the design and
-development of Rich Internet Applications. The company offers planning,
-implementation, and support services for the software projects of its customers,
-as well as sub-contract software development. Vaadin Framework, previously known
-as IT Mill Toolkit, is the flagship open source product of the company, for
-which it provides commercial development and support services.
-
-
diff --git a/documentation/book.asc b/documentation/book.asc
deleted file mode 100644
index c68ff8e048..0000000000
--- a/documentation/book.asc
+++ /dev/null
@@ -1,100 +0,0 @@
-//======================================================================
-//Copyright 2000-2012 Vaadin Ltd
-//All Rights Reserved
-//This work is licensed under a Creative Commons Attribution-NoDerivs
-//License (CC-BY-ND) Version 3.0. Full license text is available at:
-//http://creativecommons.org/licenses/by-nd/3.0/legalcode
-//======================================================================
-//The Doctype definition must be exactly same for book-pocket.pdf
-:experimental: true
-:source-highlighter: coderay
-Book of VaadinVaadin 7 Edition - 6th Revision
-        
-    MarkoGrönroos
-                Tracy
-                Translator
-            Translation
-        This book can be downloaded for free at
-        http://vaadin.com/book
-    
-        Vaadin Ltd
-    Vaadin Ltd
-            Ruukinkatu 2-4
-            20540
-            Turku
-            Finland
-        2012-02-29Vaadin Framework
-        
-        Vaadin Framework
-        7.4
-    Vaadin 7 Edition - 6th Revision
-        Bookwell Oy
-        
-            Juva
-            Finland
-        
-    2000-2015Vaadin Ltd
-        All rights reserved. This work is licensed under the Creative Commons CC-BY-ND
-            License Version 2.0.
-    
-            Vaadin is an AJAX web application development framework that enables
-            developers to build high-quality user interfaces with Java, both on the
-            server- and client-side. It provides a set of libraries of ready-to-use user
-            interface components and a clean framework for creating your own
-            components. The focus is on ease-of-use, re-usability, extensibility, and
-            meeting the requirements of large enterprise applications.
-        
-        
-            
-        
-    
-include::book-preface.asciidoc[]
-
-include::introduction/chapter-introduction.asciidoc[]
-
-include::getting-started/chapter-getting-started.asciidoc[]
-
-include::architecture/chapter-architecture.asciidoc[]
-
-include::application/chapter-application.asciidoc[]
-
-include::components/chapter-components.asciidoc[]
-
-include::layout/chapter-layout.asciidoc[]
-
-include::designer/chapter-designer.asciidoc[]
-
-include::themes/chapter-themes.asciidoc[]
-
-include::datamodel/chapter-datamodel.asciidoc[]
-
-include::sqlcontainer/chapter-sqlcontainer.asciidoc[]
-
-include::advanced/chapter-advanced.asciidoc[]
-
-include::portal/chapter-portal.asciidoc[]
-
-include::clientside/chapter-clientside.asciidoc[]
-
-include::clientsideapp/chapter-clientsideapp.asciidoc[]
-
-include::clientsidewidgets/chapter-clientsidewidgets.asciidoc[]
-
-include::gwt/chapter-gwt.asciidoc[]
-
-include::addons/chapter-addons.asciidoc[]
-
-include::charts/chapter-charts.asciidoc[]
-
-include::jpacontainer/chapter-jpacontainer.asciidoc[]
-
-include::mobile/chapter-mobile.asciidoc[]
-
-include::spreadsheet/chapter-spreadsheet.asciidoc[]
-
-include::testbench/chapter-testbench.asciidoc[]
-
-
-include::index.asciidoc[]////
-Keep this comment at the end of the file Local variables: mode: xml sgml-omittag:nil sgml-shorttag:nil sgml-namecase-general:nil sgml-general-insert-case:lower sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:4 sgml-indent-data:t sgml-parent-document:nil sgml-exposed-tags:nil sgml-local-catalogs:("/etc/sgml/catalog" "/usr/share/xemacs21/xemacs-packages/etc/psgml-dtds/CATALOG") sgml-local-ecat-files:("ECAT" "~/sgml/ECAT" "/usr/share/sgml/ECAT" "/usr/local/share/sgml/ECAT" "/usr/local/lib/sgml/ECAT") End:
-////
diff --git a/documentation/clientside/clientside-compiling.asciidoc b/documentation/clientside/clientside-compiling.asciidoc
index 18afb2c6ac..962ff76a6f 100644
--- a/documentation/clientside/clientside-compiling.asciidoc
+++ b/documentation/clientside/clientside-compiling.asciidoc
@@ -16,9 +16,9 @@ compiler.
 As most Vaadin add-ons include widgets, widget set compilation is usually needed
 when using add-ons. In that case, the widget sets from different add-ons are
 compiled into a __project widget set__, as described in
-<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using
-Vaadin
-Add-ons">>.////
+<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">>.
+
+////
 TODO Provide a link to a proper add-on compilation section when one is
 available.
 ////
@@ -76,6 +76,3 @@ follows:
 ----
 [prompt]#$# [command]#mvn# [parameter]#vaadin:compile#
 ----
-
-
-
diff --git a/documentation/clientsideapp/clientsideapp-overview.asciidoc b/documentation/clientsideapp/clientsideapp-overview.asciidoc
index 550a1b90f5..aa20571d8d 100644
--- a/documentation/clientsideapp/clientsideapp-overview.asciidoc
+++ b/documentation/clientsideapp/clientsideapp-overview.asciidoc
@@ -64,13 +64,10 @@ can be loaded to any web page, as described in
 <<dummy/../../../framework/clientsideapp/clientsideapp-loading#clientsideapp.loading,"Loading
 a Client-Side Application">>.
 
+// TODO What is this? What's an "UI Binder"?
 The client-side user interface can be built declaratively using the included
-__UI
-Binder__////
-, as described in &lt;xref
-linkend="clientsideapp.uibinder"/&gt;
-////
-.
+__UI Binder__.
+// , as described in <<clientsideapp.uibinder>>.
 
 The servlet for processing RPC calls from the client-side can be generated
 automatically using the included compiler.
@@ -79,12 +76,9 @@ Even with regular server-side Vaadin applications, it may be useful to provide
 an off-line mode if the connection is closed. An off-line mode can persist data
 in a local store in the browser, thereby avoiding the need for server-side
 storage, and transmit the data to the server when the connection is again
-available. Such a pattern is commonly used with Vaadin
-TouchKit.////
-Use of a client-side application to provide an off-line mode is described in
-&lt;xref
-linkend="clientsideapp.offline"/&gt;.
-////
-
-
+available. Such a pattern is commonly used with Vaadin TouchKit.
 
+////
+TODO It may be necessary to have such a section at some point.
+Use of a client-side application to provide an off-line mode is described in <<clientsideapp.offline>>.
+////
diff --git a/documentation/components/components-calendar.asciidoc b/documentation/components/components-calendar.asciidoc
index 0fde873763..e682be2bb2 100644
--- a/documentation/components/components-calendar.asciidoc
+++ b/documentation/components/components-calendar.asciidoc
@@ -210,7 +210,7 @@ Calendar calendar = new Calendar("Bound Calendar");
 
 // Use a container of built-in BasicEvents
 final BeanItemContainer<BasicEvent> container =
-    new BeanItemContainer<BasicEvent>(BasicEvent.class);        
+    new BeanItemContainer<BasicEvent>(BasicEvent.class);
 
 // Create a meeting in the container
 container.addBean(new BasicEvent("The Event", "Single Event",
@@ -308,7 +308,7 @@ ContainerEventProvider cep =
 
 // Set the container as the data source
 calendar.setEventProvider(cep);
-        
+
 // Now we can add events to the database through the calendar
 BasicEvent event = new BasicEvent("The Event", "Single Event",
     new GregorianCalendar(2012,1,15,12,00).getTime(),
@@ -414,7 +414,7 @@ public class BasicEvent
             EventChangeListener listener) {
         ...
     }
-    
+
     public void removeListener(EventChangeListener listener) {
         ...
     }
@@ -660,10 +660,10 @@ private Calendar createDDCalendar() {
   Calendar calendar = new Calendar();
   calendar.setDropHandler(new DropHandler() {
     public void drop(DragAndDropEvent event) {
-      CalendarTargetDetails details = 
+      CalendarTargetDetails details =
               (CalendarTargetDetails) event.getTargetDetails();
-      
-      TableTransferable transferable = 
+
+      TableTransferable transferable =
               (TableTransferable) event.getTransferable();
 
       createEvent(details, transferable);
@@ -877,15 +877,12 @@ endif::web[]
 
 Vaadin Calendar has only limited built-in navigation support. The weekly view
 has navigation buttons in the top left and top right
-corners.////
-TODO See the figure
-4.
-////
+corners.
+// TODO See the figure 4.
 
 You can handle backward and forward navigation with a
 [interfacename]#BackwardListener# and [interfacename]#ForwardListener#.
 
-
 [source, java]
 ----
 cal.setHandler(new BasicBackwardHandler() {
@@ -894,7 +891,7 @@ cal.setHandler(new BasicBackwardHandler() {
 
       java.util.Calendar calendar = event.getComponent()
                                     .getInternalCalendar();
-      if (isThisYear(calendar, end) 
+      if (isThisYear(calendar, end)
            && isThisYear(calendar, start)) {
         super.setDates(event, start, end);
       }
@@ -923,7 +920,7 @@ the week view clicking on a day switches to the day view.
 calendar.setHandler(new BasicDateClickHandler() {
     public void dateClick(DateClickEvent event) {
       Calendar cal = event.getComponent();
-      
+
       // Check if the current range is already one day long
       long currentCalDateRange = cal.getEndDate().getTime() -
                                  cal.getStartDate().getTime();
@@ -977,7 +974,7 @@ cal.setHandler(new BasicWeekClickHandler() {
                           Date start, Date end) {
         java.util.Calendar calendar = event.getComponent()
                                   .getInternalCalendar();
-        if (isThisMonth(calendar, start) 
+        if (isThisMonth(calendar, start)
             && isThisMonth(calendar,  end)) {
             super.setDates(event, start, end);
         }
@@ -1039,7 +1036,7 @@ cal.setHandler(new BasicEventMoveHandler() {
     javaCalendar = event.getComponent().getInternalCalendar();
     super.eventMove(event);
   }
-  
+
   protected void setDates(CalendarEventEditor event,
                           Date start, Date end) {
     if (isThisMonth(javaCalendar, start)
@@ -1082,7 +1079,7 @@ public static class MyEventProvider
     events.add(BasicEvent);
   }
 
-  public List<CalendarEvent> getEvents(Date startDate, 
+  public List<CalendarEvent> getEvents(Date startDate,
                                        Date endDate) {
     return events;
   }
@@ -1129,9 +1126,9 @@ cal.setHandler(new RangeSelectHandler() {
     final Window w = new Window(null, layout);
     ...
 
-    // Wrap the calendar event to a BeanItem 
+    // Wrap the calendar event to a BeanItem
     // and pass it to the form
-    final BeanItem<CalendarEvent> item = 
+    final BeanItem<CalendarEvent> item =
                          new BeanItem<CalendarEvent>(myEvent);
 
     final Form form = new Form();
@@ -1181,7 +1178,7 @@ resize will just be corrected by the server.
 cal.setHandler(new BasicEventResizeHandler() {
   private static final long twelveHoursInMs = 12*60*60*1000;
 
-  protected void setDates(CalendarEventEditor event, 
+  protected void setDates(CalendarEventEditor event,
                           Date start, Date end) {
     long eventLength = end.getTime() - start.getTime();
     if (eventLength <= twelveHoursInMs) {
@@ -1192,6 +1189,3 @@ cal.setHandler(new BasicEventResizeHandler() {
 ----
 
 endif::web[]
-
-
-
diff --git a/documentation/components/components-features.asciidoc b/documentation/components/components-features.asciidoc
index 9374b93bc1..fd4e748c05 100644
--- a/documentation/components/components-features.asciidoc
+++ b/documentation/components/components-features.asciidoc
@@ -168,7 +168,7 @@ Components are always enabled by default. You can disable a component with
 Button enabled = new Button("Enabled");
 enabled.setEnabled(true); // The default
 layout.addComponent(enabled);
-        
+
 Button disabled = new Button("Disabled");
 disabled.setEnabled(false);
 layout.addComponent(disabled);
@@ -242,7 +242,7 @@ image is provided as a resource, perhaps most typically a
 TextField name = new TextField("Name");
 name.setIcon(new ThemeResource("icons/user.png"));
 layout.addComponent(name);
-        
+
 // Component with an icon from another theme ('runo')
 Button ok = new Button("OK");
 ok.setIcon(new ThemeResource("../runo/icons/16/ok.png"));
@@ -297,11 +297,11 @@ You can set the locale of a component (or the application) with
 ----
 // Component for which the locale is meaningful
 InlineDateField date = new InlineDateField("Datum");
-        
+
 // German language specified with ISO 639-1 language
-// code and ISO 3166-1 alpha-2 country code. 
+// code and ISO 3166-1 alpha-2 country code.
 date.setLocale(new Locale("de", "DE"));
-        
+
 date.setResolution(Resolution.DAY);
 layout.addComponent(date);
 ----
@@ -357,7 +357,7 @@ get the localized resource right when the component is created.
 ResourceBundle bundle =
     ResourceBundle.getBundle(MyAppCaptions.class.getName(),
         UI.getCurrent().getLocale());
-        
+
 // Get a localized resource from the bundle
 Button cancel =
     new Button(bundle.getString(MyAppCaptions.CancelKey));
@@ -381,10 +381,10 @@ in Java.
 // The locale in which we want to have the language
 // selection list
 Locale displayLocale = Locale.ENGLISH;
-        
+
 // All known locales
 final Locale[] locales = Locale.getAvailableLocales();
-        
+
 // Allow selecting a language. We are in a constructor of a
 // CustomComponent, so preselecting the current
 // language of the application can not be done before
@@ -401,7 +401,7 @@ for (int i=0; i<locales.length; i++) {
     select.addItem(locales[i]);
     select.setItemCaption(locales[i],
                           locales[i].getDisplayName(displayLocale));
-    
+
     // Automatically select the current locale
     if (locales[i].equals(getLocale()))
         select.setValue(locales[i]);
@@ -417,7 +417,7 @@ final InlineDateField date =
     new InlineDateField("Calendar in the selected language");
 date.setResolution(Resolution.DAY);
 layout.addComponent(date);
-        
+
 // Handle language selection
 select.addValueChangeListener(new Property.ValueChangeListener() {
     public void valueChange(ValueChangeEvent event) {
@@ -457,7 +457,7 @@ TextField readwrite = new TextField("Read-Write");
 readwrite.setValue("You can change this");
 readwrite.setReadOnly(false); // The default
 layout.addComponent(readwrite);
-        
+
 TextField readonly = new TextField("Read-Only");
 readonly.setValue("You can't touch this!");
 readonly.setReadOnly(true);
@@ -497,10 +497,11 @@ read-only component can accept some other variable changes from the client-side
 and some of such changes could be acceptable, such as change in the scroll bar
 position of a [classname]#Table#. Custom widgets should check the read-only
 state for variables bound to business
-data.////
-TODO: Note this also in the Advanced: Security section and possibly also in the
-GWT
-chapter.
+data.
+
+////
+TODO: Note this also in the Advanced: Security section.
+Possibly also in the GWT chapter.
 ////
 
 === CSS Style Rules
@@ -750,8 +751,3 @@ For example, the following would make a text field blue when it has focus.
     background: lightblue;
 }
 ----
-
-
-
-
-
diff --git a/documentation/components/components-selection.asciidoc b/documentation/components/components-selection.asciidoc
index 5ad422555d..4bf7528b9f 100644
--- a/documentation/components/components-selection.asciidoc
+++ b/documentation/components/components-selection.asciidoc
@@ -323,10 +323,8 @@ kbd:[Enter]. You need to enable the mode with [methodname]#setNewItemsAllowed(tr
 Setting the component also in immediate mode may be necessary, as otherwise the
 item would not be added immediately when the user interacts with the component,
 but after some other component causes a server
-request.////
-TODO This could be a
-bug
-////
+request.
+// TODO This could be a bug
 
 
 [source, java]
diff --git a/documentation/index.asciidoc b/documentation/index.asciidoc
deleted file mode 100644
index 2dff09694e..0000000000
--- a/documentation/index.asciidoc
+++ /dev/null
@@ -1 +0,0 @@
-== Index
\ No newline at end of file
diff --git a/documentation/jpacontainer/chapter-jpacontainer.asciidoc b/documentation/jpacontainer/chapter-jpacontainer.asciidoc
index 7ce01221d9..f653116791 100644
--- a/documentation/jpacontainer/chapter-jpacontainer.asciidoc
+++ b/documentation/jpacontainer/chapter-jpacontainer.asciidoc
@@ -3,10 +3,8 @@
 
 ((("JPAContainer", id="term.jpacontainer", range="startofrange")))
 
-
 This chapter describes the use of the Vaadin JPAContainer add-on.
 
-
 include::jpacontainer-overview.asciidoc[leveloffset=+2]
 
 include::jpacontainer-installation.asciidoc[leveloffset=+2]
diff --git a/documentation/jpacontainer/jpacontainer-fieldfactory.asciidoc b/documentation/jpacontainer/jpacontainer-fieldfactory.asciidoc
index f8b6eebac3..dd014d746e 100644
--- a/documentation/jpacontainer/jpacontainer-fieldfactory.asciidoc
+++ b/documentation/jpacontainer/jpacontainer-fieldfactory.asciidoc
@@ -26,20 +26,13 @@ The generated defaults are as follows:
 
 |===============
 
-
-
-The field factory is recusive, so that you can edit a complex object tree with
-one form.
+The field factory is recursive, so that you can edit a complex object tree with one form.
 
 [[jpacontainer.fieldfactory.configuring]]
 == Configuring the Field Factory
 
-The [classname]#FieldFactory# is highly configurable with various configuration
-settings and by
-extending.////
-You need to make the configuration
-before
-////
+The [classname]#FieldFactory# is highly configurable with various configuration settings and by extending.
+// You need to make the configuration before ...
 
 The [methodname]#setMultiSelectType()# and [methodname]#setSingleSelectType()#
 allow you to specify a selection component that is used instead of the default
@@ -93,7 +86,7 @@ countrySelect.addValueChangeListener(new ValueChangeListener(){
         // Get the item to edit in the form
         Item countryItem =
             countries.getItem(event.getProperty().getValue());
-        
+
         // Use a JPAContainer field factory
         //  - no configuration is needed here
         final FieldFactory fieldFactory = new FieldFactory();
@@ -102,7 +95,7 @@ countrySelect.addValueChangeListener(new ValueChangeListener(){
         // Edit the item in the form
         countryForm.setItemDataSource(countryItem);
         countryForm.setEnabled(true);
-        
+
         // Handle saves on the form
         final Button save = new Button("Save");
         countryForm.getFooter().removeAllComponents();
@@ -156,7 +149,3 @@ automatically. As shown in the example in
 <<figure.jpacontainer.fieldfactory.using>>, the factory creates a
 [classname]#MasterDetailEditor# for all properties with a
 [literal]#++@OneToMany++# or an [literal]#++@ElementCollection++# annotation.
-
-
-
-
diff --git a/documentation/layout/chapter-layout.asciidoc b/documentation/layout/chapter-layout.asciidoc
index 176a29a4fa..4c49bba944 100644
--- a/documentation/layout/chapter-layout.asciidoc
+++ b/documentation/layout/chapter-layout.asciidoc
@@ -1,6 +1,11 @@
 [[layout]]
 == Managing Layout
 
+////
+TODO The intro text below is now completely hidden, as this text is
+not visible in web edition and all the text is web-conditional.
+////
+
 ifdef::web[]
 Ever since the ancient xeroxians invented graphical user interfaces, programmers
 have wanted to make GUI programming ever easier for themselves. Solutions
@@ -43,16 +48,17 @@ presentations, such as books and most web pages. Real applications, however,
 need to have more control. They need to be able to change the state of user
 interface components and even their layout on the run. This creates a need to
 separate the presentation from content on exactly the right
-level.////
+level.
+
+////
 Vaadin provides a solution for this, using themes and CSS, but let us first look
-at what Java did for UI
-programming.
+at what Java did for UI programming.
 ////
+
 ////
 Changing the layout steps right on the feet of the graphics designers, so we
 have a conflict. We will discuss this conflict later, but let us first look at
-what Java did for UI
-programming.
+what Java did for UI programming.
 ////
 endif::web[]
 
diff --git a/documentation/layout/layout-csslayout.asciidoc b/documentation/layout/layout-csslayout.asciidoc
index 5600978e06..10c4740705 100644
--- a/documentation/layout/layout-csslayout.asciidoc
+++ b/documentation/layout/layout-csslayout.asciidoc
@@ -29,7 +29,7 @@ component:
 [source, java]
 ----
 CssLayout layout = new CssLayout();
-        
+
 // Component with a layout-managed caption and icon
 TextField tf = new TextField("A TextField");
 tf.setIcon(new ThemeResource("icons/user.png"));
@@ -39,7 +39,7 @@ layout.addComponent(tf);
 Label label = new Label("A Label");
 label.setWidth(Sizeable.SIZE_UNDEFINED, 0);
 layout.addComponent(label);
-        
+
 layout.addComponent(new Button("A Button"));
 ----
 
@@ -120,19 +120,14 @@ logic behind the other layout components is there to give nice default behaviour
 and to handle the differences in different browsers. Some browsers, no need to
 say which, are notoriously incompatible with the CSS standards, so they require
 a lot of custom CSS. You may need to make use of the browser-specific style
-classes in the root element of the
-application.////
-TODO: described in &lt;xref
-linkend="advanced.browserinfo"/&gt;
-////
+classes in the root element of the application.
+// TODO: ... described in <<advanced.browserinfo>>
 Some features in the other layouts are not even solvable in pure CSS, at least
 in all browsers.
 
-
 [[layout.csslayout.css]]
 == Styling with CSS
 
-
 [source, css]
 ----
 .v-csslayout {}
@@ -148,7 +143,6 @@ enabled. The components are contained in an element with
 For example, we could style the basic [classname]#CssLayout# example shown
 earlier as follows:
 
-
 [source, css]
 ----
 /* Have the caption right of the text box, bottom-aligned */
@@ -178,7 +172,3 @@ at the same level as the actual component elements. This may cause problems with
 wrapping in [literal]#++inline-block++# mode, as wrapping can occur between the
 caption and its corresponding component element just as well as between
 components. Such use case is therefore not feasible.
-
-
-
-
diff --git a/documentation/portal/portal-deployment.asciidoc b/documentation/portal/portal-deployment.asciidoc
index dc3cf49e00..7350fb0536 100644
--- a/documentation/portal/portal-deployment.asciidoc
+++ b/documentation/portal/portal-deployment.asciidoc
@@ -20,7 +20,6 @@ changes to the UI itself, but only the following:
 [options="compact"]
 * Application packaged as a WAR
 
-[options="compact"]
 ** [filename]#WEB-INF/portlet.xml# descriptor
 
 ** [filename]#WEB-INF/liferay-portlet.xml# descriptor for Liferay
@@ -29,23 +28,17 @@ changes to the UI itself, but only the following:
 
 ** [filename]#WEB-INF/liferay-plugin-package.properties# for Liferay
 
-
 * Widget set installed to portal (optional)
 * Themes installed to portal (optional)
 * Vaadin libraries installed to portal (optional)
 * Portal configuration settings (optional)
 
 The Vaadin Plugin for Eclipse creates these files for you, when you create a
-portlet project as described in
-<<dummy/../../../framework/portal/portal-eclipse#portal.eclipse,"Creating a
-Generic Portlet in Eclipse">>.
-
-Installing the widget set and themes to the portal is required for running two
-or more Vaadin portlets simultaneously in a single portal page. As this
-situation occurs quite easily, we recommend installing them in any case.
-Instructions for Liferay are given in
-<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing
-Vaadin Portlets for Liferay">> and the procedure is similar for other portals.
+portlet project as described in <<portal-eclipse#portal.eclipse,"Creating a Generic Portlet in Eclipse">>.
+
+Installing the widget set and themes to the portal is required for running two or more Vaadin portlets simultaneously in a single portal page.
+As this situation occurs quite easily, we recommend installing them in any case.
+Instructions for Liferay are given in <<portal-liferay#portal.liferay,"Developing Vaadin Portlets for Liferay">> and the procedure is similar for other portals.
 
 In addition to the Vaadin libraries, you will need to have the
 [filename]#portlet.jar# in your project classpath. However, notice that you must
@@ -59,13 +52,11 @@ javax.portlet.Portlet++#".
 [[portal.deployment.descriptor]]
 == Portlet Deployment Descriptor
 
-The portlet WAR must include a portlet descriptor located at
-[filename]#WEB-INF/portlet.xml#. A portlet definition includes the portlet name,
-mapping to a servlet, modes supported by the portlet, and other configuration.
-Below is an example of a simple portlet definition in [filename]#portlet.xml#
-descriptor.
+The portlet WAR must include a portlet descriptor located at [filename]#WEB-INF/portlet.xml#.
+A portlet definition includes the portlet name, mapping to a servlet, modes supported by the portlet, and other configuration.
+Below is an example of a simple portlet definition in [filename]#portlet.xml# descriptor.
 
-[subs="normal"]
+[subs="verbatim,replacements,quotes"]
 ----
 &lt;?xml version="1.0" encoding="UTF-8" standalone="no"?&gt;
 &lt;portlet-app
@@ -77,8 +68,8 @@ descriptor.
      http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"&gt;
 
   &lt;portlet&gt;
-    &lt;portlet-name&gt;**Portlet Example portlet**&lt;/portlet-name&gt;
-    &lt;display-name&gt;**Vaadin Portlet Example**&lt;/display-name&gt;
+    &lt;portlet-name&gt;[replaceable]##Portlet Example portlet##&lt;/portlet-name&gt;
+    &lt;display-name&gt;[replaceable]##Vaadin Portlet Example##&lt;/display-name&gt;
 
     &lt;!-- Map portlet to a servlet. --&gt;
     &lt;portlet-class&gt;
@@ -88,7 +79,7 @@ descriptor.
       &lt;name&gt;UI&lt;/name&gt;
 
       &lt;!-- The application class with package name. --&gt;
-      &lt;value&gt;**com.example.myportlet.MyportletUI**&lt;/value&gt;
+      &lt;value&gt;[replaceable]##com.example.myportlet.MyportletUI##&lt;/value&gt;
     &lt;/init-param&gt;
 
     &lt;!-- Supported portlet modes and content types. --&gt;
@@ -101,23 +92,21 @@ descriptor.
 
     &lt;!-- Not always required but Liferay requires these. --&gt;
     &lt;portlet-info&gt;
-      &lt;title&gt;**Vaadin Portlet Example**&lt;/title&gt;
-      &lt;short-title&gt;**Portlet Example**&lt;/short-title&gt;
+      &lt;title&gt;[replaceable]##Vaadin Portlet Example##&lt;/title&gt;
+      &lt;short-title&gt;[replaceable]##Portlet Example##&lt;/short-title&gt;
     &lt;/portlet-info&gt;
   &lt;/portlet&gt;
 &lt;/portlet-app&gt;
 ----
-Listing supported portlet modes in [filename]#portlet.xml# enables the
-corresponding portlet controls in the portal user interface that allow changing
-the mode, as described later.
 
+The mode definitions enable the corresponding portlet controls in the portal.
+The portlet controls allow changing the mode of the portlet, as described later.
 
 [[portal.deployment.liferay]]
 == Liferay Portlet Descriptor
 
 ((("Liferay", "portlet descriptor", id="term.portal.liferay.descriptor.liferay-portlet.liferay", range="startofrange")))
 
-
 Liferay requires a special [filename]#liferay-portlet.xml# descriptor file that
 defines Liferay-specific parameters. Especially, Vaadin portlets must be defined
 as " __instanceable__", but not " __ajaxable__".
@@ -135,7 +124,7 @@ Below is an example descriptor for the earlier portlet example:
     &lt;portlet&gt;
         &lt;!-- Matches definition in portlet.xml.          --&gt;
         &lt;!-- Note: Must not be the same as servlet name. --&gt;
-        &lt;portlet-name&gt;**Portlet Example portlet**&lt;/portlet-name&gt;
+        &lt;portlet-name&gt;[replaceable]##Portlet Example portlet##&lt;/portlet-name&gt;
 
         &lt;instanceable&gt;true&lt;/instanceable&gt;
         &lt;ajaxable&gt;false&lt;/ajaxable&gt;
@@ -181,7 +170,7 @@ Vaadin portlets under the "Vaadin" category, as shown in
 
 [[figure.portal.liferay.descriptor.display]]
 .Portlet Categories in Add Application Window
-image::img/liferay-display-hi.png[]
+image::img/liferay-display-hi.png[width=60%]
 
 See Liferay documentation for further details on how to configure the categories
 in the [filename]#liferay-display.xml# deployment descriptor.
@@ -203,16 +192,16 @@ settings for the portlet, most importantly the Vaadin JAR to be used.
 
 [subs="normal"]
 ----
-name=**Portlet Example portlet**
-short-description=**myportlet**
-module-group-id=**Vaadin**
+name=[replaceable]##Portlet Example portlet##
+short-description=[replaceable]##myportlet##
+module-group-id=[replaceable]##Vaadin##
 module-incremental-version=1
 #change-log=
 #page-uri=
 #author=
 license=Proprietary
 portal-dependency-jars=\
-    **vaadin.jar**
+    [replaceable]##vaadin.jar##
 ----
 [parameter]#name#:: The plugin name must match the portlet name.
 
@@ -299,7 +288,3 @@ installation directory. The deployment depends on the application server under
 which Liferay runs; for example, if you use Liferay bundled with Tomcat, you
 will find the extracted package in the [filename]#webapps# directory under the
 Tomcat installation directory included in Liferay.
-
-
-
-
diff --git a/documentation/themes/themes-creating.asciidoc b/documentation/themes/themes-creating.asciidoc
index dcd2c5034a..e856c2b41e 100644
--- a/documentation/themes/themes-creating.asciidoc
+++ b/documentation/themes/themes-creating.asciidoc
@@ -10,8 +10,7 @@ layout: page
 Custom themes are placed in the [filename]#VAADIN/themes# folder of the web
 application, in an Eclipse project under the [filename]#WebContent# folder or
 [filename]#src/main/webapp# in Maven projects, as was illustrated in
-<<dummy/../../../framework/themes/themes-overview#figure.themes.theme-contents,"Contents
-of a Theme">>. This location is fixed. You need to have a theme folder for each
+<<themes-overview#figure.themes.theme-contents,"Contents of a Theme">>. This location is fixed. You need to have a theme folder for each
 theme you use in your application, although applications rarely need more than a
 single theme.
 
@@ -21,8 +20,7 @@ single theme.
 You can use Sass themes in Vaadin in two ways, either by compiling them to CSS
 by yourself or by letting the Vaadin servlet compile them for you on-the-fly
 when the theme CSS is requested by the browser, as described in
-<<dummy/../../../framework/themes/themes-compiling#themes.compiling,"Compiling
-Sass Themes">>.
+<<themes-compiling#themes.compiling,"Compiling Sass Themes">>.
 
 To define a Sass theme with the name mytheme, you must place a file with name
 [filename]#styles.scss# in the theme folder [filename]#VAADIN/themes/mytheme#.
@@ -152,13 +150,11 @@ returns only the custom stylenames, not the built-in stylenames for the
 component.
 
 Please see the section on each component for a description of its styles. Most
-of the stylenames are determined in the client-side widget of each component.
+of the style names are determined in the client-side widget of each component.
 The easiest way to find out the styles of the elements is to use a HTML
-inspector such as
-FireBug.////
-TODO reference to a Firebug section when
-available
-////
+inspector such as FireBug.
+
+//TODO add reference to a Firebug section when available
 
 Some client-side components or component styles can be shared by different
 server-side components. For example, [literal]#++v-textfield++# style is used
@@ -194,10 +190,10 @@ style names for specific components.
 public class MyUI extends UI {
     @Override
     protected void init(VaadinRequest request) {
-        ...      
+        ...
         Panel panel = new Panel("Regular Panel in the Runo Theme");
         panel.addComponent(new Button("Regular Runo Button"));
-        
+
         // A button with the "small" style
         Button smallButton = new Button("Small Runo Button");
         smallButton.addStyleName(Runo.BUTTON_SMALL);
@@ -277,7 +273,3 @@ add-ons contain a theme for the components they provide.
 The add-on themes need to be included in the project theme. Vaadin Plugin for
 Eclipse and Maven automatically include them in the [filename]#addons.scss# file
 in the project theme folder. It should be included by the project theme.
-
-
-
-
diff --git a/documentation/themes/themes-css.asciidoc b/documentation/themes/themes-css.asciidoc
index 45229303dc..d7ba87c700 100644
--- a/documentation/themes/themes-css.asciidoc
+++ b/documentation/themes/themes-css.asciidoc
@@ -9,7 +9,6 @@ layout: page
 
 ((("CSS", "introduction", id="term.themes.css", range="startofrange")))
 
-
 Cascading Style Sheets or CSS is the basic technique to separate the appearance
 of a web page from the content represented in HTML. In this section, we give an
 introduction to CSS and look how they are relevant to software development with
@@ -58,8 +57,8 @@ even though they use somewhat different elements to draw the user interface.
 The HTML elements that will be styled later by matching CSS rules are emphasized
 above.
 
-The [literal]#++<link>++# element in the HTML header defines the used CSS
-stylesheet. The definition is automatically generated by Vaadin in the HTML page
+The [elementname]#link# element in the HTML header defines the CSS stylesheet.
+The definition is automatically generated by Vaadin in the HTML page
 that loads the UI of the application. A stylesheet can also be embedded in the
 HTML document itself, as is done when optimizing their loading in Vaadin
 TouchKit, for example.
@@ -77,25 +76,23 @@ value, separated with a colon. A property statement ends with a semicolon.
 Let us look at an example that matches certain elements in the simple HTML
 document given in the previous section:
 
-
 [source, css]
 ----
-p, td { 
+p, td {
   color: blue;
 }
 
-td { 
+td {
   background: yellow;
   font-weight: bold;
 }
 ----
 
 The [literal]#++p++# and [literal]#++td++# are element type selectors that match
-with [literal]#++<p>++# and [literal]#++<td>++# elements in HTML, respectively.
+with [elementname]#p# and [elementname]#td# elements in HTML, respectively.
 The first rule matches with both elements, while the second matches only with
-[literal]#++<td>++# elements. Let us assume that you have saved the above style
-sheet with the name [filename]#mystylesheet.css# and consider the following HTML
-file located in the same folder.
+[elementname]#td# elements.
+Let us assume that you have saved the above style sheet with the name [filename]#mystylesheet.css# and consider the following HTML file located in the same folder.
 
 [[figure.themes.basic.1]]
 .Simple Styling by Element Type
@@ -108,7 +105,6 @@ CSS has __inheritance__ where contained elements inherit the properties of their
 parent elements. For example, let us change the above example and define it
 instead as follows:
 
-
 [source, css]
 ----
 table {
@@ -117,27 +113,25 @@ table {
 }
 ----
 
-All elements contained in the [literal]#++<table>++# element would have the same
-properties. For example, the text in the contained [literal]#++<td>++# elements
-would be in blue color.
+All elements contained in the [elementname]#table# element would have the same properties.
+For example, the text in the contained [elementname]#td# elements would be in blue color.
 
 
 [[themes.css.basics.element-types]]
 === HTML Element Types
 
 HTML has a number of element types, each of which accepts a specific set of
-properties. The [literal]#++<div>++# elements are generic elements that can be
+properties. The [elementname]#div# elements are generic elements that can be
 used to create almost any layout and formatting that can be created with a
-specific HTML element type. Vaadin uses [literal]#++<div>++# elements
+specific HTML element type. Vaadin uses [elementname]#div# elements
 extensively to draw the UI, especially in layout components.
 
-((("Google Web Toolkit",
-"themeing")))
+((("Google Web Toolkit", "themeing")))
 Matching elements by their type as shown above is, however, rarely if ever used
 in style sheets for Vaadin applications. We used it above, because it is the
 normal way in regular HTML documents that use the various HTML elements for
 formatting text, but it is not applicable in Vaadin UIs that consist mostly of
-[literal]#++<div>++# elements. Instead, you need to match by element class, as
+[elementname]#div# elements. Instead, you need to match by element class, as
 described next.
 
 
@@ -169,6 +163,7 @@ follows:
   &lt;/body&gt;
 &lt;/html&gt;
 ----
+
 The class attributes of HTML elements can be matched in CSS rules with a
 selector notation where the class name is written after a period following the
 element name. This gives us full control of matching elements by their type and
@@ -217,11 +212,9 @@ image::img/themes-css-match-class-3.png[]
 To ensure future compatibility, we recommend that you use only matching based on
 the classes and __do not__ match for specific HTML element types in CSS rules,
 because Vaadin may change the exact HTML implementation how components are drawn
-in the future. For example, Vaadin earlier used [literal]#++<div>++# element to
-draw [classname]#Button# components, but later it was changed to use the
-special-purpose [literal]#++<button>++# element in HTML. Because of using the
-[literal]#++v-button++# style class in the CSS rules for the button, styling it
-has changed only very little.
+in the future.
+For example, Vaadin earlier used [elementname]#div# element to draw [classname]#Button# components, but later it was changed to use the special-purpose [elementname]#button# element in HTML.
+Because of using the [literal]#++v-button++# style class in the CSS rules for the button, styling it has changed only very little.
 
 
 [[themes.css.matching-by-descendants]]
@@ -243,10 +236,8 @@ consider the following HTML fragment:
   &lt;/table&gt;
 &lt;/body&gt;
 ----
-Matching by the class name [literal]#++.mytext++# alone would match both the
-[literal]#++<p>++# and [literal]#++<td>++# elements. If we want to match only
-the table cell, we could use the following selector:
-
+Matching by the class name [literal]#++.mytext++# alone would match both the [elementname]#p# and [elementname]#td# elements.
+If we want to match only the table cell, we could use the following selector:
 
 [source, css]
 ----
@@ -375,7 +366,7 @@ public class HelloWorld extends UI {
 
         // Label has v-label style
         content.addComponent(new Label("Hello World!"));
-        
+
         // Button has v-button style
         content.addComponent(new Button("Push Me!",
             new Button.ClickListener() {
@@ -444,7 +435,7 @@ elements. The theme is actually a Sass theme.
   .v-ui {
     background: white;
   }
-  
+
   /* All labels have white text on black background */
   .v-label {
     background: black;
@@ -502,5 +493,3 @@ Compatibility issues are detailed in various CSS handbooks.
 
 
 (((range="endofrange", startref="term.themes.css")))
-
-
-- 
cgit v1.2.3