/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.xwiki.officeimporter.splitter;

import java.util.Map;

import org.xwiki.component.annotation.Role;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.officeimporter.OfficeImporterException;
import org.xwiki.officeimporter.document.XDOMOfficeDocument;

/**
 * Component responsible for splitting office imports.
 * 
 * @version $Id$
 * @since 2.1M1
 */
@Role
public interface XDOMOfficeDocumentSplitter
{
    /**
     * Splits an {@link XDOMOfficeDocument} into multiple {@link XDOMOfficeDocument} instances using the provided
     * heading levels as boundaries. The namingCriterion & the baseName determines the target wiki pages for the newly
     * split documents.
     * 
     * @param xdomOfficeDocument {@link XDOMOfficeDocument} to be split.
     * @param headingLevelsToSplit heading levels (1..6) to be used as boundaries. The split process is recursive, if
     *        there are multiple heading levels specified, the original document will be split from the highest heading
     *        level (lowest value >= 1) first and then the resulting office documents will be re-split from the next
     *        highest heading level.
     * @param namingCriterionHint naming criterion to be used when producing target page names for the newly split
     *        documents. Currently three schemes are supported:
     *        <ul>
     *        <li>headingNames - Uses the first heading name as target document name.</li>
     *        <li>mainPageNameAndHeading - Base document name followed by heading name.</li>
     *        <li>mainPageNameAndNumbering - Base document name followed by index.</li>
     *        </ul>
     * @param baseDocumentReference base (root) page name to be used when generating target page names for child (newly
     *        split) documents.
     * @return a map of page descriptors vs xdom office documents. Each page descriptor describes the target wiki page
     *         name for the corresponding xdom office document.
     * @throws OfficeImporterException if an error occurs while splitting.
     * @since 2.2M1
     */
    Map<TargetDocumentDescriptor, XDOMOfficeDocument> split(XDOMOfficeDocument xdomOfficeDocument,
        int[] headingLevelsToSplit, String namingCriterionHint, DocumentReference baseDocumentReference)
        throws OfficeImporterException;
}

@@ -1486,24 +1486,25 @@
 . The naming
+ 
 Criterion & 
@@ -1505,9 +1505,11 @@
 ion 
-&
+and
  the
@@ -1513,17 +1513,18 @@
 the base
-N
+ n
 ame dete
@@ -1563,21 +1563,21 @@
  the
- newly
 %0A     *
+ newly
  spl
@@ -1669,17 +1669,16 @@
 be split
-.
 %0A     * 
@@ -1929,16 +1929,23 @@
  level (
+%7B@code 
 lowest v
@@ -1953,16 +1953,17 @@
 lue %3E= 1
+%7D
 ) first 
@@ -2031,13 +2031,8 @@
  the
- next
 %0A   
@@ -2042,16 +2042,21 @@
         
+next 
 highest 
@@ -2068,17 +2068,16 @@
 ng level
-.
 %0A     * 
@@ -2277,24 +2277,26 @@
    *        
+  
 %3Cli%3EheadingN
@@ -2349,25 +2349,24 @@
 ocument name
-.
 %3C/li%3E%0A     *
@@ -2357,32 +2357,34 @@
 name%3C/li%3E%0A     *
+  
         %3Cli%3Emain
@@ -2447,17 +2447,16 @@
 ing name
-.
 %3C/li%3E%0A  
@@ -2451,32 +2451,34 @@
 name%3C/li%3E%0A     *
+  
         %3Cli%3Emain
@@ -2536,17 +2536,16 @@
 by index
-.
 %3C/li%3E%0A  
@@ -2704,33 +2704,32 @@
 split) documents
-.
 %0A     * @return 
@@ -2894,17 +2894,16 @@
 document
-.
 %0A     * 
@@ -2968,17 +2968,16 @@
 plitting
-.
 %0A     * 

Fix javadoc