AbstractDocbkxMojo.java
/*
* The contents of this file are subject to the terms of the Common Development and
* Distribution License (the License). You may not use this file except in compliance with the
* License.
*
* You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
* specific language governing permission and limitations under the License.
*
* When distributing Covered Software, include this CDDL Header Notice in each file and include
* the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
* Header, with the fields enclosed by brackets [] replaced by your own identifying
* information: "Portions copyright [year] [name of copyright owner]".
*
* Copyright 2012-2015 ForgeRock AS.
* Partial Copyright 2022 Wren Security
*/
package org.forgerock.doc.maven;
import static org.twdata.maven.mojoexecutor.MojoExecutor.element;
import static org.twdata.maven.mojoexecutor.MojoExecutor.name;
import org.apache.commons.io.FilenameUtils;
import org.apache.maven.execution.MavenSession;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.BuildPluginManager;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.project.MavenProject;
import org.forgerock.doc.maven.backstage.ArtifactItem;
import org.forgerock.doc.maven.utils.NameUtils;
import org.twdata.maven.mojoexecutor.MojoExecutor;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
/**
* AbstractMojo implementation for building core documentation from <a
* href="http://www.docbook.org/tdg51/en/html/docbook.html">DocBook XML</a>
* using <a href="http://code.google.com/p/docbkx-tools/">docbkx-tools</a>.
*/
abstract public class AbstractDocbkxMojo extends AbstractMojo {
/**
* Versions of plugins driven by this plugin.
*/
private Properties versions;
/**
* Load versions of plugins driven by this plugin.
*/
private void loadVersions() {
versions = new Properties();
InputStream inputStream = null;
try {
inputStream = getClass().getResourceAsStream("/versions.properties");
if (inputStream == null) {
throw new IOException("Could not read properties resource");
}
versions.load(inputStream);
} catch (IOException e) {
getLog().error("Failed to read plugin version properties", e);
} finally {
if (inputStream != null) {
try {
inputStream.close();
} catch (IOException e) {
// Ignore exception.
}
}
}
}
/**
* Get a version property based on the version properties file.
*
* <br>
*
* Prefer the current value if it is already set.
*
* @param currentValue If not null or empty, then return this value.
* @param key Otherwise return the value for this key.
* @return The currentValue if set, otherwise the property.
*/
private String getVersionProperty(String currentValue, String key) {
if (currentValue != null && !currentValue.isEmpty()) {
return currentValue;
}
if (versions == null) {
loadVersions();
}
return versions.getProperty(key);
}
/**
* Whether to use WinAnsi encoding for embedded fonts.
* If {@code true}, then some UTF-8 characters cannot be used.
*/
private String ansi = "false";
/**
* Whether to use WinAnsi encoding for embedded fonts.
*
* <br>
*
* Value: {@code false}
*
* @return Whether WinAnsi encoded should be used for embedded fonts.
*/
public final String useAnsi() {
return ansi;
}
/**
* Should sections have numeric labels?
*
* <br>
*
* docbkx-tools element: <sectionAutolabel>
*/
private String areSectionsAutolabeled = "true";
/**
* Whether sections should have numeric labels.
*
* <br>
*
* Value: {@code true}
*
* <br>
*
* docbkx-tools element: <sectionAutolabel>
*
* @return Whether sections should have numeric labels.
*/
public final String areSectionsAutolabeled() {
return areSectionsAutolabeled;
}
/**
* Base directory for Asciidoc source files.
*/
@Parameter(defaultValue = "${basedir}/src/main/asciidoc")
private File asciidocSourceDirectory;
/**
* Get the base directory for Asciidoc source files.
* These files remain unchanged during processing.
*
* <br>
*
* Default: {@code ${basedir}/src/main/asciidoc}.
*
* @return The base directory for Asciidoc source files.
*/
public File getAsciidocSourceDirectory() {
return asciidocSourceDirectory;
}
/**
* Version of the Asciidoctor Maven plugin to use.
*/
@Parameter
private String asciidoctorPluginVersion;
/**
* Returns the version of the Asciidoctor Maven plugin to use.
*
* @return The version of the Asciidoctor Maven plugin to use.
*/
public String getAsciidoctorPluginVersion() {
return getVersionProperty(asciidoctorPluginVersion, "asciidoctorPluginVersion");
}
/**
* File system directory for Backstage layout output
* relative to the build directory.
*/
@Parameter(defaultValue = "backstage")
private String backstageDirectory;
/**
* Get the file system directory for Backstage layout output.
*
* <br>
*
* Default: {@code ${project.build.directory}/backstage}
*
* @return The file system directory for Backstage layout output.
*/
public File getBackstageDirectory() {
return new File(getBuildDirectory(), backstageDirectory);
}
/**
* Product name as shown on Backstage.
*/
@Parameter(property = "backstageProductName")
private String backstageProductName;
/**
* Get the product name as shown on Backstage.
*
* <br>
*
* Default: {@code projectName}
*
* @return The product name as shown on Backstage.
*/
public String getBackstageProductName() {
return backstageProductName != null ? backstageProductName : projectName;
}
/**
* Get the base configuration applicable to all builds with the docbkx-tools plugin.
*
* @return The configuration applicable to all builds.
*/
public ArrayList<MojoExecutor.Element> getBaseConfiguration() {
ArrayList<MojoExecutor.Element> cfg = new ArrayList<>();
cfg.add(element(name("draftMode"), isDraftMode()));
cfg.add(element(name("draftWatermarkImage"), getDraftWatermarkURL()));
cfg.add(element(name("highlightSource"), useSyntaxHighlighting()));
cfg.add(element(name("sectionAutolabel"), areSectionsAutolabeled()));
cfg.add(element(name("sectionLabelIncludesComponentLabel"),
doesSectionLabelIncludeComponentLabel()));
cfg.add(element(name("xincludeSupported"), isXincludeSupported()));
cfg.add(element(name("sourceDirectory"), path(getDocbkxModifiableSourcesDirectory())));
return cfg;
}
/**
* Project base directory, needed to workaround bugs with *target.db and webhelp.
*/
@Parameter(defaultValue = "${basedir}")
private File baseDir;
/**
* Project base directory, needed to workaround bugs with *target.db and webhelp.
*
* <br>
*
* Default: {@code ${basedir}}
*
* @return The project base directory.
*/
public File getBaseDir() {
return baseDir;
}
/**
* The artifactId of the branding to use.
*/
@Parameter(defaultValue = "doc-default-branding")
private String brandingArtifactId;
/**
* Gets the branding artifactId to use.
*
* <br>
*
* Default: {@code doc-default-branding}.
*
* @return The branding artifactId.
*/
public String getBrandingArtifactId() {
return brandingArtifactId;
}
/**
* The groupId of the branding to use.
*/
@Parameter(defaultValue = "org.wrensecurity.commons")
private String brandingGroupId;
/**
* Gets the groupId of the branding artifact to use.
*
* <br>
*
* Default: {@code org.wrensecurity.common}
*
* @return The branding groupId.
*/
public String getBrandingGroupId() {
return brandingGroupId;
}
/**
* Version of the branding artifact to use.
*/
@Parameter
private String brandingVersion;
/**
* Gets the version of the branding artifact to use.
*
* @return The branding artifact version.
*/
public String getBrandingVersion() {
return getVersionProperty(brandingVersion, "brandingVersion");
}
/**
* The project build directory.
*
* <br>
*
* Default: {@code ${project.build.directory}}.
*/
@Parameter(defaultValue = "${project.build.directory}")
private File buildDirectory;
/**
* Get the project build directory for this plugin.
*
* <br>
*
* Default: {@code ${project.build.directory}}.
*
* @return The build directory.
*/
public File getBuildDirectory() {
return buildDirectory;
}
/**
* Whether to build a .zip of the release content.
*/
@Parameter(defaultValue = "false", property = "buildReleaseZip")
private boolean buildReleaseZip;
/**
* Whether to build a .zip containing the release content.
*
* <br>
*
* Default: {@code false}
*
* @return true if the .zip should be built.
*/
public final boolean doBuildReleaseZip() {
return buildReleaseZip;
}
/**
* Location of the chunked HTML XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <htmlCustomization>
*/
private String chunkedHTMLCustomization = "docbkx-stylesheets/html/chunked.xsl";
/**
* Get the location of the chunked HTML XSL stylesheet customization file.
*
* <br>
*
* Default: {@code ${project.build.directory}/docbkx-stylesheets/html/chunked.xsl}
*
* <br>
*
* docbkx-tools element: <htmlCustomization>
*
* @return The location of the chunked HTML XSL stylesheet.
*/
public final File getChunkedHTMLCustomization() {
return new File(getBuildDirectory(), chunkedHTMLCustomization);
}
/**
* The {@code artifactId} of the common content artifact.
*/
@Parameter(defaultValue = "doc-common-content")
private String commonContentArtifactId;
/**
* Get the {@code artifactId} of the common content artifact.
*
* <br>
*
* Default: {@code doc-common-content}.
*
* @return The {@code artifactId} of the common content artifact.
*/
public String getCommonContentArtifactId() {
return commonContentArtifactId;
}
/**
* The {@code groupId} of the common content artifact.
*/
@Parameter(defaultValue = "org.wrensecurity.commons")
private String commonContentGroupId;
/**
* Get the {@code groupId} of the common content artifact.
*
* <br>
*
* Default: {@code org.wrensecurity.common}.
*
* @return The {@code groupId} of the common content artifact.
*/
public String getCommonContentGroupId() {
return commonContentGroupId;
}
/**
* Version of the common content artifact to use.
*/
@Parameter
private String commonContentVersion;
/**
* Get the version of the common content artifact to use.
*
* @return the version of the common content artifact to use.
*/
public String getCommonContentVersion() {
return getVersionProperty(commonContentVersion, "commonContentVersion");
}
/**
* Whether to copy resource files alongside docs for site, release.
*/
@Parameter(defaultValue = "false")
private boolean copyResourceFiles;
/**
* Whether to copy resource files alongside docs for site, release.
*
* <br>
*
* Default: false
*
* @return true if resource files should be copied.
*/
public boolean doCopyResourceFiles() {
return copyResourceFiles;
}
/**
* Whether to build artifacts from pre-processed sources.
*/
@Parameter(defaultValue = "true")
private boolean createArtifacts;
/**
* Whether to build artifacts from pre-processed sources.
*
* <br>
*
* Default: true
*
* @return true if artifacts should be build from pre-processed sources.
*/
public boolean doCreateArtifacts() {
return createArtifacts;
}
/**
* Doc artifacts to unpack when preparing Backstage layout.
*/
@Parameter
private List<ArtifactItem> artifactItems;
/**
* Get the doc artifacts to unpack when preparing Backstage layout.
*
* @return The doc artifacts to unpack when preparing Backstage layout.
*/
public List<ArtifactItem> getArtifactItems() {
return artifactItems != null ? artifactItems : new LinkedList<ArtifactItem>();
}
/**
* Base directory for the modifiable copy of DocBook XML source files,
* relative to the build directory.
*/
private String docbkxModifiableSourcesDirectory = "docbkx-sources";
/**
* Get the base directory for the modifiable copy of DocBook XML source files.
* This copy is modified during preparation for processing.
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx-sources}
*
* @return The base directory for the modifiable copy of DocBook XML source files.
*/
public File getDocbkxModifiableSourcesDirectory() {
return new File(getBuildDirectory(), docbkxModifiableSourcesDirectory);
}
/**
* Base directory for built documentation, relative to the build directory.
*/
private String docbkxOutputDirectory = "docbkx";
/**
* Base directory for built documentation.
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx}
*
* @return The base directory for built documentation.
*/
public File getDocbkxOutputDirectory() {
return new File(buildDirectory, docbkxOutputDirectory);
}
/**
* Base directory for DocBook XML source files.
*/
@Parameter(defaultValue = "${basedir}/src/main/docbkx", property = "docbkxSourceDirectory")
private File docbkxSourceDirectory;
/**
* Get the base directory for DocBook XML source files.
* These files remain unchanged during processing.
*
* <br>
*
* Default: {@code ${basedir}/src/main/docbkx}.
*
* @return The base directory for DocBook XML source files.
*/
public File getDocbkxSourceDirectory() {
return docbkxSourceDirectory;
}
/**
* Docbkx Tools plugin version to use.
*/
@Parameter
private String docbkxVersion;
/**
* Get the docbkx-tools plugin version to use.
*
* @return The docbkx-tools plugin version to use
*/
public String getDocbkxVersion() {
return getVersionProperty(docbkxVersion, "docbkxVersion");
}
/**
* Supported DocBook profile attributes.
*/
public enum ProfileAttributes {
/** Computer or chip architecture, such as i386. */
arch,
/** Intended audience of the content, such as instructor. Added in DocBook version 5.0. */
audience,
/** General purpose conditional attribute, with no preassigned semantics. */
condition,
/** Standards conformance, such as lsb (Linux Standards Base). */
conformance,
/** Language code, such as de_DE. */
lang,
/** Operating system. */
os,
/** Editorial revision, such as v2.1. */
revision,
/** Revision status of the element, such as changed. This attribute has a fixed set of values to choose from. */
revisionflag,
/** General purpose attribute, with no preassigned semantics. Use with caution for profiling. */
role,
/** Security level, such as high. */
security,
/** Editorial or publication status, such as InDevelopment or draft. */
status,
/** Level of user experience, such as beginner. */
userlevel,
/** Product vendor, such as apache. */
vendor,
/** Word size (width in bits) of the computer architecture, such as 64bit. Added in DocBook version 4.4. */
wordsize
}
/**
* Returns true if the attribute is one of the expected ProfileAttributes.
* @param attribute The attribute to check.
* @return true if the attribute is one of the expected ProfileAttributes.
*/
private boolean isProfileAttribute(final String attribute) {
try {
ProfileAttributes.valueOf(attribute);
return true;
} catch (IllegalArgumentException e) {
return false;
}
}
/**
* Include elements with these
* <a href="http://www.sagehill.net/docbookxsl/Profiling.html">DocBook profile</a> settings.
* <br>
* See <a href="http://www.sagehill.net/docbookxsl/Profiling.html#ProfilingAttribs"
* >the list of profile attributes specified for DocBook</a>.
* <br>
* Separate multiple attribute values for the same attribute with spaces.
* <br>
* For example, to include all elements with {@code os="linux"} or {@code os="unix"}
* and all elements with no {@code os} attribute,
* use the following configuration:
* <pre>
* <inclusions>
* <os>linux unix</os>
* </inclusions>
* </pre>
*/
@Parameter
private Map<String, String> inclusions;
/**
* Returns a map of DocBook profile settings to include elements.
* <br>
* This implementation ignores unexpected profile settings.
*
* @return A map of DocBook profile settings to include elements,
* or null if none are set.
*/
public Map<String, String> getInclusions() {
if (inclusions == null) {
return null;
}
Map<String, String> result = new HashMap<>();
for (String attribute : inclusions.keySet()) {
if (isProfileAttribute(attribute)) {
result.put(attribute, inclusions.get(attribute));
}
}
return result;
}
/**
* Exclude elements with these
* <a href="http://www.sagehill.net/docbookxsl/Profiling.html">DocBook profile</a> settings.
* <br>
* See <a href="http://www.sagehill.net/docbookxsl/Profiling.html#ProfilingAttribs"
* >the list of profile attributes specified for DocBook</a>.
* <br>
* Separate multiple attribute values for the same attribute with spaces.
* <br>
* For example, to exclude all elements with {@code os="linux"} and {@code os="unix"},
* use the following configuration:
* <pre>
* <exclusions>
* <os>linux unix</os>
* </exclusions>
* </pre>
*/
@Parameter
private Map<String, String> exclusions;
/**
* Returns a map of DocBook profile settings to exclude elements.
* <br>
* This implementation ignores unexpected profile settings.
*
* @return A map of DocBook profile settings to exclude elements,
* or null if none are set.
*/
public Map<String, String> getExclusions() {
if (exclusions == null) {
return null;
}
Map<String, String> result = new HashMap<>();
for (String attribute : exclusions.keySet()) {
if (isProfileAttribute(attribute)) {
result.put(attribute, exclusions.get(attribute));
}
}
return result;
}
/**
* Get document names for the current project.
*
* @return The document names for the current project.
* @throws MojoExecutionException No document names found.
*/
public Set<String> getDocNames() throws MojoExecutionException {
Set<String> docNames = NameUtils.getDocumentNames(
getDocbkxModifiableSourcesDirectory(), getDocumentSrcName());
if (docNames.isEmpty()) {
throw new MojoExecutionException("No document names found.");
}
return docNames;
}
/**
* URL to site for published documentation.
*/
@Parameter(defaultValue = "https://docs.wrensecurity.org/")
private String docsSite;
/**
* Get the URL to the site for published documentation.
*
* <br>
*
* Default: {@code https://docs.wrensecurity.org/}
*
* @return The URL to the site for published documentation.
*/
public String getDocsSite() {
return docsSite;
}
/**
* Top-level DocBook XML source document name.
*/
@Parameter(defaultValue = "index.xml", property = "documentSrcName")
private String documentSrcName;
/**
* Get the top-level DocBook XML source document name.
*
* <br>
*
* Default: {@code index.xml}.
*
* <br>
*
* Documents included in the documentation set
* such as books, articles, and references share a common entry point,
* which is a file having the name specified by this element.
*
* <br>
*
* For example, if your documentation set has
* Release Notes, an Installation Guide, an Admin Guide, a Dev Guide, and a Reference,
* your source layout under the base DocBook XML source directory
* might look like the following:
*
* <pre>
* src/main/docbkx/
* admin-guide/
* index.xml
* ...other files...
* dev-guide/
* index.xml
* ...other files...
* install-guide/
* index.xml
* ...other files...
* reference/
* index.xml
* ...other files...
* release-notes/
* index.xml
* ...other files...
* shared/
* ...other files...
* </pre>
*
* <br>
*
* The {@code ...other files...} can have whatever names you want,
* as long as the name does not match the file name you configure.
* For example, if you were to hand-code an index file
* you could name it {@code ix.xml}.
*
* @return File name of top-level DocBook XML source document.
*/
public String getDocumentSrcName() {
return documentSrcName;
}
/**
* Whether section labels should include parent numbers,
* like 1.1, 1.2, 1.2.1, 1.2.2.
*
* <br>
*
* docbkx-tools element: <sectionLabelIncludesComponentLabel>
*/
private String doesSectionLabelIncludeComponentLabel = "true";
/**
* Whether section labels should include parent numbers,
* like 1.1, 1.2, 1.2.1, 1.2.2.
*
* <br>
*
* Value: {@code true}
*
* <br>
*
* docbkx-tools element: <sectionLabelIncludesComponentLabel>
*
* @return Whether section labels should include parent numbers.
*/
public final String doesSectionLabelIncludeComponentLabel() {
return doesSectionLabelIncludeComponentLabel;
}
/**
* For draft mode, URL to the background watermark image.
*
* <br>
*
* docbkx-tools element: <draftWatermarkImage>
*/
@Parameter(defaultValue = "http://docbook.sourceforge.net/release/images/draft.png")
private String draftWatermarkURL;
/**
* For draft mode, URL to the background watermark image.
*
* <br>
*
* Default: {@code http://docbook.sourceforge.net/release/images/draft.png}
*
* <br>
*
* docbkx-tools element: <draftWatermarkImage>
*
* @return The URL to the background watermark image.
*/
public final String getDraftWatermarkURL() {
return draftWatermarkURL;
}
/**
* URL to JSON object showing EOSL versions for each project.
*/
@Parameter(defaultValue = "http://docs.wrensecurity.org/eosl.json")
private String eoslJson;
/**
* Get the URL to JSON object showing EOSL versions for each project.
*
* @return The URL to the JSON object.
*/
public String getEoslJson() {
return eoslJson;
}
/**
* Location of the EPUB XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <epubCustomization>
*/
private String epubCustomization = "docbkx-stylesheets/epub/coredoc.xsl";
/**
* Get the location of the EPUB XSL stylesheet customization file.
*
* <br>
*
* Default: {@code ${project.build.directory}/docbkx-stylesheets/epub/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <epubCustomization>
*
* @return The location of the EPUB XSL stylesheet customization file.
*/
public final File getEpubCustomization() {
return new File(getBuildDirectory(), epubCustomization);
}
/**
* Favicon link element for the pre-site version of the HTML.
*/
@Parameter(defaultValue = "<link rel=\"shortcut icon\" href=\"https://wrensecurity.org/favicon.ico\">")
private String faviconLink;
/**
* Get the favicon link element for the pre-site version of the HTML.
*
* @return The link element.
*/
public final String getFaviconLink() {
return faviconLink;
}
/**
* Location of the FO XSL stylesheet customization file (for PDF, RTF),
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <foCustomization>
*/
private String foCustomization = "docbkx-stylesheets/fo/coredoc.xsl";
/**
* Get the location of the FO XSL stylesheet customization file (for PDF, RTF).
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx-stylesheets/fo/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <foCustomization>
*
* @return The location of the FO XSL stylesheet.
*/
public final File getFoCustomization() {
return new File(getBuildDirectory(), foCustomization);
}
/**
* Directory where fonts and font metrics are stored,
* relative to the build directory.
*/
private String fontsDirectory = "fonts";
/**
* Directory where fonts and font metrics are stored.
*
* <br>
*
* Value: {@code ${project.build.directory}/fonts}
*
* @return The directory where fonts and font metrics are stored.
*/
public final File getFontsDirectory() {
return new File(getBuildDirectory(), fontsDirectory);
}
/**
* Version of the FOP hyphenation plugin to use.
*/
@Parameter
private String fopHyphVersion;
/**
* Get the version of the FOP hyphenation plugin to use.
* @return The version of the FOP hyphenation plugin to use.
*/
public String getFopHyphVersion() {
return getVersionProperty(fopHyphVersion, "fopHyphVersion");
}
/**
* Log level when building FO output (PDF, RTF).
*
* <br>
*
* docbkx-tools element: <fopLogLevel>
*/
@Parameter(defaultValue = "ERROR")
private String fopLogLevel;
/**
* Log level when building FO output (PDF, RTF).
*
* <br>
*
* Default: {@code ERROR}
*
* <br>
*
* docbkx-tools element: <fopLogLevel>
*
* @return The log level for Apache FOP.
*/
public final String getFopLogLevel() {
return fopLogLevel;
}
/**
* Supported output formats.
*/
public enum Format {
/**
* EPUB v2 without styling; not ready for publication.
*/
epub,
/**
* Styled single-page and chunked HTML 4.
*/
html,
/**
* Styled with HtmlForBootstrap single-page HTML 4.
*/
bootstrap,
/**
* Reference manual pages for use with the {@code man} command.
*/
man,
/**
* PDF.
*/
pdf,
/**
* RTF without styling; not ready for publication.
*/
rtf,
/**
* Styled DocBook Webhelp format.
*/
webhelp,
/**
* Single-page XHTML5 without styling except syntax highlighting;
* not ready for publication as is.
*/
xhtml5
}
/**
* Comma-separated list of output formats to generate.
*/
@Parameter(property = "formats", defaultValue = "bootstrap,pdf")
private List<Format> formats;
/**
* Return a list of output formats to generate.
*
* <br>
*
* Default: bootstrap,pdf
*
* @return List of output formats.
*/
public List<Format> getFormats() {
return this.formats;
}
/**
* Google Analytics identifier for the project.
*
* <br>
*
* The identifier for docs.forgerock.org is {@code UA-REMOVED-VALUE}.
*/
@Parameter(defaultValue = "UA-REMOVED-VALUE")
private String googleAnalyticsId;
/**
* Google Analytics identifier for the project.
*
* <br>
*
* Default: {@code UA-REMOVED-VALUE}
*
* @return The Google Analytics identifier.
*/
public String getGoogleAnalyticsId() {
return googleAnalyticsId;
}
/**
* Whether these are draft documents, rather than final documents.
*
* <br>
*
* docbkx-tools element: <draftMode>
*/
@Parameter(defaultValue = "yes", property = "isDraftMode")
private String isDraftMode;
/**
* Whether these are draft documents, rather than final documents.
*
* <br>
*
* Default: {@code yes}
*
* <br>
*
* docbkx-tools element: <draftMode>
*
* @return Whether these are draft documents.
*/
public final String isDraftMode() {
return isDraftMode;
}
/**
* Whether documents should be allowed to include other documents.
*
* <br>
*
* docbkx-tools element: <xincludeSupported>
*/
private String isXincludeSupported = "true";
/**
* Whether documents should be allowed to include other documents.
*
* <br>
*
* Value: {@code true}
*
* <br>
*
* docbkx-tools element: <xincludeSupported>
*
* @return Where documents should be allowed to include other documents.
*/
public final String isXincludeSupported() {
return isXincludeSupported;
}
/**
* JavaScript file name, found under {@code /js/} in plugin resources.
*/
private String javaScriptFileName = "uses-jquery.js";
/**
* Get the main JavaScript file name, found under {@code /js/} in plugin resources.
*
* <br>
*
* Value: {@code uses-jquery.js}
*
* @return The JavaScript file name.
*/
public String getJavaScriptFileName() {
return javaScriptFileName;
}
/**
* The set of source paths where cited Java files are found.
*/
@Parameter
private List<File> jCiteSourcePaths;
/**
* Get the source paths where cited Java files are found.
*
* <br>
*
* If source paths are not set, {@code src/main/java} is used.
*
* @return the set of source paths where cited Java files are found.
*/
public List<File> getJCiteSourcePaths() {
return jCiteSourcePaths;
}
/**
* JCite version to use for code citations.
*/
@Parameter
private String jCiteVersion;
/**
* Get the JCite artifact version to use for Java code citations.
*
* @return The JCite artifact version to use for Java code citations.
*/
public String getJCiteVersion() {
return getVersionProperty(jCiteVersion, "jCiteVersion");
}
/**
* Whether to keep a custom index.html file for the documentation set.
*/
@Parameter(defaultValue = "false")
private boolean keepCustomIndexHtml;
/**
* Whether to keep a custom index.html file for the documentation set.
*
* <br>
*
* Default: {@code false}
*
* @return Whether to keep a custom index.html file.
*/
public boolean keepCustomIndexHtml() {
return keepCustomIndexHtml;
}
/**
* URL to JSON object showing latest versions for each project.
*/
@Parameter(defaultValue = "http://docs.wrensecurity.org/latest.json")
private String latestJson;
/**
* Get the URL to JSON object showing latest versions for each project.
*
* @return The URL to the JSON object.
*/
public String getLatestJson() {
return latestJson;
}
/**
* ForgeRock link tester plugin version to use.
*/
@Parameter
private String linkTesterVersion;
/**
* ForgeRock link tester plugin version to use.
*
* @return The link tester plugin version to use.
*/
public String getLinkTesterVersion() {
return getVersionProperty(linkTesterVersion, "linkTesterVersion");
}
/**
* Locale tag for the documentation set.
*/
@Parameter(defaultValue = "en")
private String localeTag;
/**
* Get the Locale tag for the documentation set.
*
* <br>
*
* Default: {@code en}
*
* @return The Locale tag for the documentation set.
*/
public String getLocaleTag() {
return localeTag;
}
/**
* Location of the man page XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <manpagesCustomization>
*/
private String manpagesCustomization = "docbkx-stylesheets/man/coredoc.xsl";
/**
* Get the location of the man page XSL stylesheet customization file.
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx-stylesheets/man/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <manpagesCustomization>
*
* @return The location of the man page XSL stylesheet.
*/
public final File getManpagesCustomization() {
return new File(getBuildDirectory(), manpagesCustomization);
}
/**
* Version of the Maven assembly plugin to use.
*/
@Parameter
private String mavenAssemblyVersion;
/**
* Get the version of the Maven dependency plugin to use.
* @return The version of the Maven dependency plugin to use.
*/
public String getMavenAssemblyVersion() {
return getVersionProperty(mavenAssemblyVersion, "mavenAssemblyVersion");
}
/**
* Version of the Maven dependency plugin to use.
*/
@Parameter
private String mavenDependencyVersion;
/**
* Get the version of the Maven dependency plugin to use.
* @return The version of the Maven dependency plugin to use.
*/
public String getMavenDependencyVersion() {
return getVersionProperty(mavenDependencyVersion, "mavenDependencyVersion");
}
/**
* Version of the Maven filtering library to use.
*/
@Parameter
private String mavenFilteringVersion;
/**
* Get the version of the Maven filtering library to use.
* <br>
* This is used as a workaround for
* <a href="https://jira.codehaus.org/browse/MSHARED-325">MSHARED-325</a>.
*
* @return The version of the Maven filtering library to use.
*/
public String getMavenFilteringVersion() {
return getVersionProperty(mavenFilteringVersion, "mavenFilteringVersion");
}
/**
* Maven resources plugin version.
* Executions seem to hit an NPE when the version is not specified.
*/
@Parameter
private String mavenResourcesVersion;
/**
* Get the Maven resources plugin version.
* Executions seem to hit an NPE when the version is not specified.
*
* @return The Maven resources plugin version.
*/
public String getMavenResourcesVersion() {
return getVersionProperty(mavenResourcesVersion, "mavenResourcesVersion");
}
/**
* Maximum height for PNG images used in PDF, in inches.
*/
@Parameter(defaultValue = "5")
private int maxImageHeightInInches;
/**
* Get maximum height for PNG images used in PDF, in inches.
*
* @return Maximum height for PNG images used in PDF, in inches.
*/
public int getMaxImageHeightInInches() {
return maxImageHeightInInches;
}
/**
* Overwrite the copy of DocBook sources if it exists.
*/
@Parameter(defaultValue = "true")
private boolean overwriteModifiableCopy;
/**
* Whether to overwrite the copy of DocBook sources if it exists.
*
* <br>
*
* One of the first things the plugin does when preparing DocBook sources
* is to make a working copy of the files that is separate from the sources.
* This allows the plugin to make changes to the files as necessary.
*
* <br>
*
* If for some reason you must provide the copy yourself,
* and your copy must be in the {@code docbkxModifiableSourcesDirectory},
* then you can set this to {@code false}
* to prevent the plugin from replacing the copy.
* The plugin will then pre-process the copy, however,
* so expect the files in the modifiable copy to be changed.
*
* <br>
*
* Default: true
*
* @return Whether to overwrite the copy of DocBook sources if it exists.
*/
public boolean doOverwriteModifiableCopy() {
return overwriteModifiableCopy;
}
/**
* Overwrite project files with shared content.
*/
@Parameter(defaultValue = "true", property = "overwriteProjectFilesWithSharedContent")
private boolean overwriteProjectFilesWithSharedContent;
/**
* Whether to overwrite project files with shared content.
*
* <br>
*
* Default: true
*
* @return Whether to overwrite project files with shared content.
*/
public boolean doOverwriteProjectFilesWithSharedContent() {
return overwriteProjectFilesWithSharedContent;
}
/**
* Get path name in UNIX format.
*
* @param file Path to return in UNIX format.
* @return The path in UNIX format.
*/
public String path(final File file) {
String result = "";
if (file != null) {
result = FilenameUtils.separatorsToUnix(file.getPath());
}
return result;
}
/**
* Version of the PlantUML artifact to use.
*/
@Parameter
private String plantUmlVersion;
/**
* Get the version of the PlantUML artifact.
*
* @return The version of the PlantUML artifact.
*/
public String getPlantUmlVersion() {
return getVersionProperty(plantUmlVersion, "plantUmlVersion");
}
/**
* The version of Plexus Utils used by the XCite Maven plugin.
*/
@Parameter
private String plexusUtilsVersion;
/**
* Return the version of Plexus Utils used by the XCite Maven plugin.
*
* @return The version of Plexus Utils used by the XCite Maven plugin.
*/
public String getPlexusUtilsVersion() {
return getVersionProperty(plexusUtilsVersion, "plexusUtilsVersion");
}
/**
* The Maven {@code BuildPluginManager} object.
*/
@Component
private BuildPluginManager pluginManager;
/**
* Get the Maven {@code BuildPluginManager} object.
*
* @return The Maven {@code BuildPluginManager} object.
*/
public BuildPluginManager getPluginManager() {
return pluginManager;
}
/**
* CSS file for the pre-site version of the HTML,
* relative to the build directory.
*/
private String preSiteCssFileName = "coredoc.css";
/**
* Get the CSS file for the pre-site version of the HTML.
*
* <br>
*
* Value: {@code ${project.build.directory}/coredoc.css}
*
* @return The CSS file.
*/
public final File getPreSiteCss() {
return new File(getBuildDirectory(), preSiteCssFileName);
}
/**
* The {@code MavenProject} object, which is read-only.
*/
@Parameter(property = "project", required = true, readonly = true)
private MavenProject project;
/**
* Get the {@code MavenProject} object.
*
* @return The {@code MavenProject} object.
*/
public MavenProject getProject() {
return project;
}
/**
* Short name of the project, such as OpenAM, OpenDJ, OpenIDM.
*/
@Parameter(property = "projectName", required = true)
private String projectName;
/**
* Short name of the project, such as OpenAM, OpenDJ, OpenIDM.
*
* @return The short name of the project.
*/
public String getProjectName() {
return projectName;
}
/**
* Project version.
*/
@Parameter(property = "projectVersion", required = true)
private String projectVersion;
/**
* Get the project version.
*
* @return The project version.
*/
public String getProjectVersion() {
return projectVersion;
}
/**
* CSS file for the release version of the HTML,
* relative to the build directory.
*/
private String releaseCssFileName = "dfo.css";
/**
* Get the CSS file for the release version of the HTML.
*
* <br>
*
* Value: {@code ${project.build.directory}/dfo.css}
*
* @return The CSS file.
*/
public final File getReleaseCss() {
return new File(getBuildDirectory(), releaseCssFileName);
}
/**
* Software release date.
*/
@Parameter(property = "releaseDate")
private String releaseDate;
/**
* Get the software release date.
*
* <br>
*
* Default: now
*
* @return The software release date.
*/
public String getReleaseDate() {
SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
return releaseDate == null || releaseDate.isEmpty() ? format.format(new Date()) : releaseDate;
}
/**
* File system directory for release layout documentation,
* relative to the build directory.
*/
@Parameter(defaultValue = "release")
private String releaseDirectory;
/**
* Get the file system directory for release layout documentation.
*
* <br>
*
* Default: {@code ${project.build.directory}/release}
*
* @return {@link #releaseDirectory}
*/
public final File getReleaseDirectory() {
return new File(getBuildDirectory(), releaseDirectory);
}
/**
* Favicon link element for the release version of the HTML.
*/
@Parameter(defaultValue = "<link rel=\"shortcut icon\" href=\"https://wrensecurity.org/favicon.ico\">")
private String releaseFaviconLink;
/**
* Get the favicon link element for the release version of the HTML.
*
* @return The link element.
*/
public final String getReleaseFaviconLink() {
return releaseFaviconLink;
}
/**
* Version for this release.
*/
@Parameter(property = "releaseVersion", required = true)
private String releaseVersion;
/**
* Get the version for this release.
*
* @return The version for this release.
*/
public final String getReleaseVersion() {
return releaseVersion;
}
/**
* Get the path to the directory to hold the release version documents,
* such as {@code ${project.build.directory}/release/1.0.0}.
*
* @return The path to the release version directory.
*/
public final String getReleaseVersionPath() {
return getReleaseDirectory().getPath() + File.separator + getReleaseVersion();
}
/**
* File system directory for arbitrary documentation set resources,
* relative to the modifiable sources directory.
*/
@Parameter(defaultValue = "resources")
private String resourcesDirectory;
/**
* Path to arbitrary documentation set resources,
* relative to the modifiable sources directory.
*
* <br>
*
* Default: {@code resources}
*
* @return The resources directory path, relative to the modifiable sources directory.
*/
public String getRelativeResourcesDirectoryPath() {
return resourcesDirectory;
}
/**
* Directory for arbitrary documentation set resources.
*
* <br>
*
* Default: {@code ${basedir}/src/main/docbkx/resources}
*
* @return The resources directory.
*/
public File getResourcesDirectory() {
return new File(getDocbkxModifiableSourcesDirectory(), resourcesDirectory);
}
/**
* Whether to run the ForgeRock link tester plugin.
*/
@Parameter(defaultValue = "true", property = "runLinkTester")
private String runLinkTester;
/**
* Whether to run the ForgeRock link tester plugin.
*
* <br>
*
* You only need to run the link test from the top level of a project.
*
* <br>
*
* Default: {@code "true"}
*
* @return Whether to run the ForgeRock link tester plugin.
*/
public String runLinkTester() {
return runLinkTester;
}
/**
* The {@code MavenSession} object, which is read-only.
*/
@Parameter(property = "session", required = true, readonly = true)
private MavenSession session;
/**
* Get the {@code MavenSession} object.
* @return The {@code MavenSession} object.
*/
public MavenSession getSession() {
return session;
}
/**
* Location of the single page HTML XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <htmlCustomization>
*/
private String singleHTMLCustomization = "/docbkx-stylesheets/html/coredoc.xsl";
/**
* Get the location of the single page HTML XSL stylesheet customization file.
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx-stylesheets/html/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <htmlCustomization>
*
* @return The location of the single-page HTML XSL stylesheet.
*/
public final File getSingleHTMLCustomization() {
return new File(getBuildDirectory(), singleHTMLCustomization);
}
/**
* File system directory for site content, relative to the build directory.
*/
@Parameter(defaultValue = "site")
private String siteDirectory;
/**
* Get the file system directory for site content.
*
* <br>
*
* Default: {@code ${project.build.directory}/site}
*
* @return The file system directory for site content.
*/
public final File getSiteDirectory() {
return new File(getBuildDirectory(), siteDirectory);
}
/**
* Whether the ForgeRock link tester plugin should skip checking
* that external URLs are valid.
*
* <br>
*
* See the {@code skipUrls} parameter of the <a
* href="https://github.com/aldaris/docbook-linktester/">linktester plugin</a>.
*/
@Parameter(defaultValue = "false", property = "skipLinkCheck")
private String skipLinkCheck;
/**
* Whether the ForgeRock link tester plugin should skip checking
* that external URLs are valid.
*
* <br>
*
* See the {@code skipUrls} parameter of the <a
* href="https://github.com/aldaris/docbook-linktester/">linktester plugin</a>.
*
* <br>
*
* Default: {@code false}
*
* @return Whether to test that external URLs are valid.
*/
public String skipLinkCheck() {
return skipLinkCheck;
}
/**
* Regex patterns of URLs to skip when checking external links.
*
* <br>
*
* See the {@code skipUrlPatterns} parameter of the <a
* href="https://github.com/aldaris/docbook-linktester/">linktester plugin</a>.
*/
@Parameter
private String[] skipUrlPatterns;
/**
* Get regex patterns of URLs to skip when checking external links.
*
* <br>
*
* Default: {@code null}
*
* @return Regex patterns of URLs to skip when checking external links.
*/
public String[] getSkipUrlPatterns() {
return skipUrlPatterns;
}
/**
* Whether to build from pre-processed DocBook XML sources.
*/
@Parameter(defaultValue = "false", property = "usePreProcessedSources")
private boolean usePreProcessedSources;
/**
* Whether to build from pre-processed DocBook XML sources.
*
* <p>
*
* Default: {@code false}
*
* @return True if {@code docbkxSourceDirectory} contains fully pre-processed sources.
*/
public boolean doUsePreProcessedSources() {
return usePreProcessedSources;
}
/**
* Whether <programlisting> content has syntax highlighting.
*
* <br>
*
* docbkx-tools element: <highlightSource>
*/
private String useSyntaxHighlighting = "1";
/**
* Whether <programlisting> content has syntax highlighting.
*
* <br>
*
* Value: {@code 1} (true)
*
* <br>
*
* docbkx-tools element: <highlightSource>
*
* @return Where program listings use syntax highlighting.
*/
public final String useSyntaxHighlighting() {
return useSyntaxHighlighting;
}
/**
* Location of the main CSS for webhelp documents,
* relative to the build directory.
*/
private String webhelpCss = "docbkx-stylesheets/webhelp/positioning.css";
/**
* Get the location of the main CSS file for webhelp documents.
*
* <br>
*
* Value: {@code ${project.build.dir}/docbkx-stylesheets/webhelp/positioning.css}
*
* @return The main CSS file for webhelp documents.
*/
public final File getWebHelpCss() {
return new File(getBuildDirectory(), webhelpCss);
}
/**
* Location of the webhelp XSL stylesheet customization file, relative to
* the build
* directory.
*
* <br>
*
* docbkx-tools element: <webhelpCustomization>
*/
private String webhelpCustomization = "docbkx-stylesheets/webhelp/coredoc.xsl";
/**
* Get the location of the webhelp XSL stylesheet customization file.
*
* <br>
*
* Value: {@code ${project.build.dir}/docbkx-stylesheets/webhelp/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <webhelpCustomization>
*
* @return The location of the webhelp XSL stylesheet.
*/
public final File getWebHelpCustomization() {
return new File(getBuildDirectory(), webhelpCustomization);
}
/**
* Location of the logo image for webhelp documents,
* relative to the build directory.
*/
private String webhelpLogo = "docbkx-stylesheets/webhelp/logo.png";
/**
* Get the location of the logo image for webhelp documents.
*
* <br>
*
* Value: {@code ${project.build.dir}/docbkx-stylesheets/webhelp/logo.png}
*
* @return The logo image for webhelp documents.
*/
public final File getWebHelpLogo() {
return new File(getBuildDirectory(), webhelpLogo);
}
/**
* Version of the XCite Maven plugin to use.
*/
@Parameter
private String xCiteVersion;
/**
* Return the version of the XCite Maven plugin to use.
*
* @return The version of the XCite Maven plugin to use.
*/
public String getXCiteVersion() {
return getVersionProperty(xCiteVersion, "xCiteVersion");
}
/**
* Location of the XHTML5 XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <xhtml5Customization>
*/
private String xhtml5Customization = "docbkx-stylesheets/xhtml5/coredoc.xsl";
/**
* Location of the XHTML5 XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* Value: {@code ${project.build.directory}/docbkx-stylesheets/xhtml5/coredoc.xsl}
*
* <br>
*
* Default: {@code ${project.build.directory}/docbkx-stylesheets/xhtml5/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <xhtml5Customization>
*
* @return The location of the XHTML5 XSL stylesheet.
*/
public final File getXhtml5Customization() {
return new File(getBuildDirectory(), xhtml5Customization);
}
/**
* Location of the HtmlForBootstrap XSL stylesheet customization file,
* relative to the build directory.
*
* <br>
*
* docbkx-tools element: <bootstrapCustomization>
*/
private String bootstrapCustomization =
"docbkx-stylesheets/bootstrap/coredoc.xsl";
/**
* Get the location of the HtmlForBootstrap XSL stylesheet customization file.
*
* <br>
*
* Default: {@code ${project.build.directory}/docbkx-stylesheets/bootstrap/coredoc.xsl}
*
* <br>
*
* docbkx-tools element: <bootstrapCustomization>
*
* @return The location of the HtmlForBootstrap XSL stylesheet.
*/
public final File getBootstrapCustomization() {
return new File(getBuildDirectory(), bootstrapCustomization);
}
}