Package org.apache.sis.internal.book
Class Assembler
java.lang.Object
org.apache.sis.internal.book.Assembler
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 thehref
attribute. - Complete
<abbr>
elements withouttitle
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 ah?
element. - Replace the
<!-- TOC -->
comment by a table of content generated from all<h1>
,<h2>
, etc. found in the document.
- Since:
- 0.7
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionThetitle
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 intableOfContent
, 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.Whether we found an abbreviation after the lasth?
element. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static void
Adjusts the relative path in<a href="../../../static/">
or<img src="../../../static/">
attribute value.private static boolean
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
insertWordSeparator
(String text) Allows word break before the code in expression likeClass.method()
.private Document
Loads the XML document from the given file with indentation removed.static void
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
Performs on the given node the processing documented in the class javadoc.private void
processAbbreviation
(Element element) Automatically inserts atitle
attribute in the given<abbr>
element if it meets the condition documented in the class javadoc.private void
removeIndentation
(Node node) 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
Assembles the document and writes to the destination.
-
Field Details
-
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_BREAKMinimal number of characters in a Java identifier before to allows a line break before the next identifier. This value if used in expressions likefoo.bar()
for deciding whether or not we accept line break betweenfoo
and.bar()
.- See Also:
-
PATHS_TO_REPLACE
Relative path to be replaced by"../"
path. We perform this substitution because the source files defined in thesource/developer-guide/<chapter>
directories reference directly the images in their finalstatic/book/images
directory. -
inputDirectory
The directory of all input files to process. -
builder
The factory for creating new XML nodes. -
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
The node where to write the table of content for the whole document. -
MAX_TOC_LEVEL
private static final int MAX_TOC_LEVELMaximal header level to include intableOfContent
, inclusive.- See Also:
-
abbreviations
Thetitle
attributes found in abbreviations. -
writtenAbbreviations
Whether we found an abbreviation after the lasth?
element. This is used in order to avoid inserting too many abbreviation title. -
sectionNumbering
private final int[] sectionNumberingSection numbers, incremented when a new<h1>
,<h2>
, etc. element is found. -
colorizer
Helper class for applying colors on content of<code>
and<samp>
elements.
-
-
Constructor Details
-
Assembler
public Assembler(File input) throws ParserConfigurationException, IOException, SAXException, BookException Creates a new assembler for the given input and output files.- Parameters:
input
- the input file (e.g."sis-site/main/source/developer-guide/index.html"
).- Throws:
ParserConfigurationException
- if this constructor cannot build the XML document.IOException
- if an error occurred while reading the file.SAXException
- if an error occurred while parsing the XML.BookException
- if a logical error occurred while initializing the assembler.
-
-
Method Details
-
load
Loads the XML document from the given file with indentation removed.- Throws:
IOException
SAXException
-
removeIndentation
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 onDocumentBuilder
build-in support mostly because we have been unable to get thexpointer
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
Adjusts the relative path in<a href="../../../static/">
or<img src="../../../static/">
attribute value. -
adjustURL
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
Automatically inserts atitle
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 tofalse
when parsing the content of<aside>
or<article>
elements.- Throws:
IOException
SAXException
BookException
-
prependSectionNumber
Prepend the current section numbers to the given node. The given node shall be a<h1>
,<h2>
, etc. element.- Parameters:
level
- 1 ifhead
is<h1>
, 2 ifhead
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
Creates a<a href="reference">text</a>
node.- Throws:
BookException
-
insertWordSeparator
Allows word break before the code in expression likeClass.method()
. If there is nothing to change in the given text, returnsnull
. -
run
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
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 ofsis-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
-