Class Assembler

java.lang.Object
org.apache.sis.internal.book.Assembler

public final class Assembler extends Object
Generates the developer guide from the given input file. This class performs the following processing:
  • Replace elements of the form <xi:include href="introduction.html"/> by content of the <body> element in the file given by the href attribute.
  • Complete <abbr> elements without title attribute by reusing the last title used for the same abbreviation. This automatic insertion is performed only for the first occurrence of that abbreviation after a h? element.
  • Replace the <!-- TOC --> comment by a table of content generated from all <h1>, <h2>, etc. found in the document.
See package javadoc for usage example.
Since:
0.7
Version:
1.3
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final Map<String,String>
    The title attributes found in abbreviations.
    private final DocumentBuilder
    The factory for creating new XML nodes.
    private final CodeColorizer
    Helper class for applying colors on content of <code> and <samp> elements.
    private final Document
    The XML document to write.
    private final File
    The directory of all input files to process.
    private static final String
    The line separator to be used in the output file.
    private static final int
    Maximal header level to include in tableOfContent, inclusive.
    private static final int
    Minimal number of characters in a Java identifier before to allows a line break before the next identifier.
    private static final String[]
    Relative path to be replaced by "../" path.
    private final int[]
    Section numbers, incremented when a new <h1>, <h2>, etc. element is found.
    private final Element
    The node where to write the table of content for the whole document.
    private final Set<String>
    Whether we found an abbreviation after the last h? element.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Assembler(File input)
    Creates a new assembler for the given input and output files.
  • Method Summary

    Modifier and Type
    Method
    Description
    private static void
    adjustURL(Element element)
    Adjusts the relative path in <a href="../../../static/"> or <img src="../../../static/"> attribute value.
    private static boolean
    adjustURL(Element element, String prefix)
    Adjusts the relative path in <a href="../../../static/"> or <img src="../../../static/"> attribute value.
    private void
    appendToTableOfContent(Node appendTo, int level, Element referenced)
    Appends the given header to the table of content.
    private Element
    createLink(String reference, String text)
    Creates a <a href="reference">text</a> node.
    private static String
    Allows word break before the code in expression like Class.method().
    private Document
    load(File input)
    Loads the XML document from the given file with indentation removed.
    static void
    main(String[] args)
    Generates the "static/book/en|fr/developer-guide.html" files from "source/developer-guide/[fr/]index.html" files.
    private void
    prependSectionNumber(int level, Node head)
    Prepend the current section numbers to the given node.
    private void
    process(File directory, Node node, boolean index)
    Performs on the given node the processing documented in the class javadoc.
    private void
    Automatically inserts a title attribute in the given <abbr> element if it meets the condition documented in the class javadoc.
    private void
    Removes the indentation at the beginning of lines in the given node and all child nodes.
    private Node[]
    replaceByBody(File input, Node toReplace)
    Copies the body of the given source HTML file in-place of the given target node.
    void
    run(File output)
    Assembles the document and writes to the destination.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • LINE_SEPARATOR

      private static final String LINE_SEPARATOR
      The line separator to be used in the output file. We fix it to the Unix style (not the native style of the platform) for more compact output file.
      See Also:
    • MINIMAL_LENGTH_BEFORE_BREAK

      private static final int MINIMAL_LENGTH_BEFORE_BREAK
      Minimal number of characters in a Java identifier before to allows a line break before the next identifier. This value if used in expressions like foo.bar() for deciding whether or not we accept line break between foo and .bar().
      See Also:
    • PATHS_TO_REPLACE

      private static final String[] PATHS_TO_REPLACE
      Relative path to be replaced by "../" path. We perform this substitution because the source files defined in the source/developer-guide/<chapter> directories reference directly the images in their final static/book/images directory.
    • inputDirectory

      private final File inputDirectory
      The directory of all input files to process.
    • builder

      private final DocumentBuilder builder
      The factory for creating new XML nodes.
    • document

      private final Document document
      The XML document to write. This is initially the XML document parsed from the given input file. Then all included files are inserted in-place and some nodes are processed as documented in the class javadoc.
    • tableOfContent

      private final Element tableOfContent
      The node where to write the table of content for the whole document.
    • MAX_TOC_LEVEL

      private static final int MAX_TOC_LEVEL
      Maximal header level to include in tableOfContent, inclusive.
      See Also:
    • abbreviations

      private final Map<String,String> abbreviations
      The title attributes found in abbreviations.
    • writtenAbbreviations

      private final Set<String> writtenAbbreviations
      Whether we found an abbreviation after the last h? element. This is used in order to avoid inserting too many abbreviation title.
    • sectionNumbering

      private final int[] sectionNumbering
      Section numbers, incremented when a new <h1>, <h2>, etc. element is found.
    • colorizer

      private final CodeColorizer colorizer
      Helper class for applying colors on content of <code> and <samp> elements.
  • Constructor Details

  • Method Details

    • load

      private Document load(File input) throws IOException, SAXException
      Loads the XML document from the given file with indentation removed.
      Throws:
      IOException
      SAXException
    • removeIndentation

      private void removeIndentation(Node node)
      Removes the indentation at the beginning of lines in the given node and all child nodes. This can reduce the file length by as much as 20%. Note that the indentation was broken anyway after the treatment of <xi:include>, because included file does not use the right amount of spaces for the location where it is introduced.
    • replaceByBody

      private Node[] replaceByBody(File input, Node toReplace) throws IOException, SAXException, BookException
      Copies the body of the given source HTML file in-place of the given target node. This method is doing the work of <xi:include> element. We do this work ourself instead of relying on DocumentBuilder build-in support mostly because we have been unable to get the xpointer to work.
      Parameters:
      input - the source XML file.
      toReplace - the target XML node to be replaced by the content of the given file.
      Throws:
      IOException
      SAXException
      BookException
    • adjustURL

      private static void adjustURL(Element element)
      Adjusts the relative path in <a href="../../../static/"> or <img src="../../../static/"> attribute value.
    • adjustURL

      private static boolean adjustURL(Element element, String prefix)
      Adjusts the relative path in <a href="../../../static/"> or <img src="../../../static/"> attribute value.
      Parameters:
      element - the element to adjust.
      prefix - the path prefix to search and replace.
      Returns:
      whether replacement has been done.
    • processAbbreviation

      private void processAbbreviation(Element element)
      Automatically inserts a title attribute in the given <abbr> element if it meets the condition documented in the class javadoc.
    • process

      private void process(File directory, Node node, boolean index) throws IOException, SAXException, BookException
      Performs on the given node the processing documented in the class javadoc. This method invokes itself recursively.
      Parameters:
      directory - the directory of the file being processed. Used for resolving relative links.
      index - true for including the <h1>, etc. texts in the Table Of Content (TOC). This is set to false when parsing the content of <aside> or <article> elements.
      Throws:
      IOException
      SAXException
      BookException
    • prependSectionNumber

      private void prependSectionNumber(int level, Node head)
      Prepend the current section numbers to the given node. The given node shall be a <h1>, <h2>, etc. element.
      Parameters:
      level - 1 if head is <h1>, 2 if head is <h2>, etc.
      head - the <h1>, <h2>, <h3>, <h4>, etc. element.
    • appendToTableOfContent

      private void appendToTableOfContent(Node appendTo, int level, Element referenced) throws BookException
      Appends the given header to the table of content.
      Parameters:
      appendTo - the root node of the table of content where to append a new line.
      level - level of the <h1>, <h2>, <h3>, etc. element found.
      referenced - the <h1>, <h2>, <h3>, etc. element to reference.
      Throws:
      BookException
    • createLink

      private Element createLink(String reference, String text) throws BookException
      Creates a <a href="reference">text</a> node.
      Throws:
      BookException
    • insertWordSeparator

      private static String insertWordSeparator(String text)
      Allows word break before the code in expression like Class.method(). If there is nothing to change in the given text, returns null.
    • run

      public void run(File output) throws IOException, SAXException, BookException, TransformerException
      Assembles the document and writes to the destination.
      Parameters:
      output - the output file (e.g. "site/content/en/developer-guide.html").
      Throws:
      IOException - if an error occurred while reading or writing file.
      SAXException - if an error occurred while parsing an input XML.
      BookException - if an error was found in the content of the XML file.
      TransformerException - if an error occurred while formatting the output XML.
    • main

      public static void main(String[] args) throws Exception
      Generates the "static/book/en|fr/developer-guide.html" files from "source/developer-guide/[fr/]index.html" files. The only argument expected by this method is the root of sis-site project.
      Parameters:
      args - command-line arguments. Should contain exactly on value, which is the site root directory.
      Throws:
      Exception - if an I/O error, a XML parsing error or other kinds of error occurred.
      Since:
      0.8