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

3 files changed, 34 insertions, 46 deletions

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]