Configuration file

It is possible to define an optional property / value configuration file when starting the application (using the graphical UI or the command line^[1]

The property to set the configuration file on the command-line is config

).

This configuration file allows to set the following groups of properties:

• General properties
• Error handling: used to specify how parsing errors are handled
• Search configuration: used for the search configuration
• Output formats: used to specify and configure the output formats of the generator
• Performance: used to tweak the performance of the generation
• Roots: used for root directories and packages configuration
• Miscellanous parameters
• Updating parameters: used for the incremental generation mode

General properties

• "cleaned": true if the content of the output directory must be cleaned before the generation. Works as the "-cleaned" argument on the command-line
• "fixedLeftMenuOptions": Specifies if the options in the left menu are always present (meaning that all options are present even for the page on which we are). If this option is set to true, we will have a "Home" option even on the Home page, for example. See also default left menu for more information
• "preventExit": true if the tool must not use System.exit(0) at the end of the generation. It can be useful if the tool is used in a list of other tasks in ant or maven. See Preventing exit for more information
• "index": the optional index file (can be useful in the case of multiple directories)
• "locale" : the localization of the wiki (the default is "en", which means that the wiki will be in English)
• "limit" : specifies the maximum number of output articles per directory (if this is limited)
• "dynamicMaps": specifies if maps will be dynamically loaded
• "hasNotesTooltips": specifies if notes show an integrated tooltip when hovering on the note associated element
• "notesTooltipsLength": the length of the integrated tooltips
• "wikilinksTooltips": specifies if wikipedia show an integrated tooltip when hovering on the note associated element
• "lightbox": specifies if images use lightboxes
• "includeTODO": specifies if TODOs are included (true by default). See also TODO system
• "includeComments": specifies if comments are included. See also Review system
• "styleSheetTheme": specifies yhe CSS file specifying the theming. See also StyleSheet theme

Error handling

These options are used to specify how parsing errors are handled.

• "checkLinks": to specify that the presence of external links (in a, cite and APIs syntax elements tags) must be checked^[2]
  for html pages, the presence of anchors if the "#" tag is found in the link construction is also checked
• "checkHTTPLinks": set if the URL links with the "http" protocol are checked. This property will only be used if the "checkLinks" property is set to true. ^[3]
  Note that having true for this property (which is the default) can increase the time for the parsing and generation, see the FAQ for more information
  . The possible values for this property are:
  • "false": do not check the URL links with the "http" protocol
  • "true": check the URL links with the "http" protocol
• "checkInternalJavaAPI": avoid to use internal jars which hold Java APIs for the checking if the API is not available through http of checkHTTPLinks is false
• "acceptLocalLinks": to specify which kinds of local links outside of the wiki are allowed (by default all local links outside of the wiki are not allowed). See also checking local links
• "resolveAPILinks": to specify if APIs which are defined internal to the wiki output will be resolved (true by default). See also Resolving API links
• "showWarnings": to specify if warnings should be presented (false by default). By default only errors are presented
• "defaultHTTPTimeout": set the timeout for chrecking the availability of an http link (500 ms by default)
• "checkHTTPLinksThreaded": specifies if HTTP links must be checked in a Thread pool (true by default)
• "checkHTTPLinksTimeOut": set the timeout of the Thread pool used for checking URL links with the "http" protocol, if the check is performed in background Threads
• "checkHTTPLinksPool": set the number of Threads in the Thread pool used for checking URL links with the "http" protocol, if the check is performed in background Threads. See also checkHTTPLinksPool parameter for more information
• "urlExceptions": specifies the XML file for which URLs won't be checked (useful only if the "checkLinks" property is set to true). See urlExceptions
• "timeouts": specifies the XML file setting specific timeouts for URLs (useful only if the "checkLinks" property is set to true). See timeouts
• "showGlossaryErrors": show the warnings in the glossary generation
• "errorsFullPath": specifies if the full path of the files where errors are encountered must be presented (by default only the relative path to the root directory is shown)
• "errorsViewerType": specifies how to view the files if errors are encountered. See also Errors viewer for more information

Search configuration

• "search": Set if an autocomplete Search box which will be added for each article. Works as the "-search" argument on the command-line allow to add an autocomplete Search box will be added for each article:
  • "false" (the default value) if there is no Search box
  • "true" or "articles" if there is a Search box for the articles titles only
  • "titles" if there is a Search box for the articles titles and their table of content sub-titles
  • "anchors" if there is a Search box on the articles descriptions, their titles, and their anchors
  • "custom": for custom search categories
• "searchLimit": the limit on the number of results for the Search
• "pageRank": set the PageRank algorithm used to sort the Search results
• "pageRankIterations": the number of iterations for the PageRank algorithm, when the PageRank is using a fixed value for the iterations
• "pageRankMaxIterations": the maximum number of iterations for the PageRank algorithm, when the PageRank is using a convergence algorithm
• "pageRankConvergeDelta": the value to stop the iterations when the PageRank is using a convergence algorithm
• "searchCustomSpec": for the custom search categories specification
• "fullTextSearch": Set if a Full text search in the wiki is available. Note that for a Full text search to be available, the "search" must be set. See also Full text search for more information
• "fullTextSearchCompressionLevel": the compression level of the full text search. See also Full text search for more information
• "fullTextSearchRemoveAccents": Set if accents should be removed from the full text search (true by default). See also Full text search for more information
• "fullTextSearchMetaphone": Set if the Metaphone algorithm should be used for the full text search (false by default). See also Full text search for more information
• "pruneAltTitles": Set if alternate titles are automatically pruned in the dictionary if their text is sufficiently similar to the article title. See regular article for more information

PageRank algorithm

The pageRank property specifies the PageRank algorithm used to sort the Search results:

• "false" : don't use the PageRank algorithm to sort the Search results
• "true" or "fixed" : use the PageRank algorithm with a fixed number of iterations to sort the Search results. The "pageRankIterations" property specifies the number of iterations
• "converge" : use the PageRank algorithm and use a convergence algorithm for the number of iterations to sort the Search results. The "pageRankMaxIterations" property specifies the maximum number of iterations, and the "pageRankConvergeDelta" the value to use for the convergence

Output formats

• "allowMediawiki": true if the Mediawiki format is also accepted for articles (the default is false)^[4]
  allowMediawiki is incompatible with allowMarkdown. If the two propeties are set to true, the result will be as if only allowMediawiki has been set to true
  . See mediawiki syntax.
• "allowMarkdown": true if the Markdown format is also accepted for articles (the default is false)^[4]
  allowMediawiki is incompatible with allowMarkdown. If the two propeties are set to true, the result will be as if only allowMediawiki has been set to true
  . See markdown syntax.
• "docFile": the generated document file, for Word, PDF, or ePub generation types
• "helpFileName": the name of the generated help file, for the Help generation type
• "helpFile": the generated help file, for the Help generation type
• "helpOptimizedForSwing": specifies if the help content is optimized for the Swing API
• "helpContent": the optional file which specifies how the chapters in the help content will be created
• "cover": the file used for the cover of the ePub file
• "helpPageWidth": the page width used for specifying the images width for the help content
• "wikiContent" or "chaptersContent": the path of the XML file which filter and configure the content of the wiki output. See also Document content specification
• "outputType": the output type (pdf, docx, help, or html). See outputType configuration property

Performance

• "forkParser": specifies if the parsing will be performed in background threads. See also forkParser parameter for more information
• "forkParserSplit": specifies the maximum number of files to parse per thread (useful only if the "forkParser" is set to true)

Roots parameters

• "dependencies": specifies the file which specifies the packages dependencies. See root directories and packages and packages dependencies for more information
• "inputsSubdirectories" or "includeSubdirectories": specifies that the inputs sub-directories will be used rather that directly the inputs directory. See also Using the inputs sub-directories for more information

Miscellanous parameters

• "wikiTitle": the optional title for the wiki home page. By default the title of the home page will be "Home"
• "lightbox": true if images have a lightbox^[5]
  A Lightbox effect is a JavaScript mechanism that displays images and videos by filling the screen, and dimming out the rest of the web page, when the image is clicked on
• "hasTOC": false if articles Table of content must not be present on html^[6]
  See also table of content configuration
• "tocThreshold": the threshold of the numebr of titles for articles on html. By default an article must have at least 3 titles to have a table of content^[6]
  See also table of content configuration
• "hasDictionary": false if the dictionary must not be generated^[7]
  See also Getting rid of the dictionary
• "hasCategories": false if the categories must not be generated^[8]
  See also Getting rid of the categories
• "wikilinksTooltips": true if there are wiki links tooltips. False by default.
• "hasNotesTooltips": true if there should be tooltips for notes. True by default. See also notes tooltip
• "notesTooltipsLength": the text length in notes tooltips
• "notesTwoColumns": true if the notes chapter presents the notes on two columns rather than one. False by default. See also notes chapter
• "limit": to limit the number of articles per directory. Works as the "-limit" argument on the command-line. The output directory will therefore be separated in several sub-directories which will contain the articles
• "relaxedSyntax": true if the syntax of the articles is relaxed. See Relaxed syntax for more information about how to define this property and how to use it
• "IECompatibilityEdge": true if the compatibility mode for Internet Explorer is set to the highest value. This may be necessary to allow jQuery to work correctly with high-level versions of IE (used for the Search field). The value is true by default but can be set to false
• "justification": specifies if the wiki text is justified by default See justification for more information
• "alignment": specifies if the wiki text is aligned by default See Justification for more information
• "supportEscaping": true if characters can be escaped with CDATA elements in articles. See Escaping characters for more information
• "escapeNonUTF8": false if non UTF8 characters should not be escaped automatically in articles. See also Escaping non UTF8 characters. The default is false.
• "emptyLines": specifies how empty lines in the source should be converted. See also processing empty lines
• "allowHTMLEntities": true if HTML entities are taken into account (true by default). See also Handling HTML entities
• "dynamicMaps": false if maps will be processed as images. The default is true, meaning that the maps will be loaded dynamically by scripts in the HTML articles. Note that PDF generation will use static images for Maps
• "staticMapsTimeOut": the timeOut value in milliseconds for maps processed as images. The default is 2000 milliseconds
• "urlExceptions": specifies the XML file for which URLs won't be checked (useful only if the "checkLinks" property is set to true). See urlExceptions
• "timeouts": specifies the XML file setting specific timeouts for URLs (useful only if the "checkLinks" property is set to true). See timeouts
• "userAgent": specifies the user agent used when accessing external links. The value "ie9" will set an IE9 user agent, other values will specify directly the user agent^[9]
  If this property is not set, a default Firefox 10 user agent will be used
• "proxy.host": specifies the host for a proxy when accessing external links
• "proxy.port": specifies the port for a proxy when accessing external links
• "proxy.authentication": specifies that the proxy must be authenticated (default is false)
• "background": the optional background image to use for the article pages
• "backgroundOpacity": the optional opacity of the background image to use for the article pages
• "backgroundGlobal": false if the background should only be set on the home page
• "backgroundColor": the optional background color to use for the article pages
• "codeHasBackground": If true, code and source elements will have a background as in Wikipedia
• "preHasBackground": If true, pre elements will have a background as in Wikipedia. See also pre element background for more information
• "preScrollingType": Specifies how the pre elements content is scrolled. See also pre scrolling type for more information
• "css": a custom additional CSS StyleSheet that will be added to each article. The path of the file can be absolute or relative to the configuration file
• "script": the optional Javascript file to use for the HTML result. It will be added to each article. The path of the file can be absolute or relative to the configuration file
• "footer": the optional file specifying the custom additional content to add in the footer. The file should contain regular HTML content
• "leftIndexMenu": the optional file specifying the custom additional content to put in the left menu for the index file. The file should contain regular HTML content
• "rightIndexMenu": the optional file specifying the custom content to put in the right menu for the index file. The file should contain regular HTML content
• "apidocs": the optional file specifying the the custom internal API documentation. See Internal API documentation configuration. Note that contrary to the "APIs" property, the API has to be specified and it will be included in the wiki
• "APIs": the path to the APIs XML file. See APIs property
• javadoc-<api name>: the path to a Javadoc API. The path can be absolute or relative to the configuration file, and can also sepcify an http location. Note that by default the JAVASE API is always available. It's name is JAVASE, it points to the Java 8 API, and it can be overriden by the configuration
• "preSyntax": an optional list of Jar files specifying pack of syntaxes for the "pre" element. See pre syntax packs
• "locale": allows to specify the localization of the wiki pages. See localization
• "input": the input directories, used if the input directories in the command-line are not defined
• "output": the output directory, used if the output directory in the command-line is not defined
• other arguments beginning with $ will define key/value string replacements in the text (see properties file)

Note that almost all these properties can be specified directly on the command-line. All File paths can be absolute or relative to the configuration file.

Preventing exit

By default the tool will not do anything at the end of the generation. However it is possible to specify that it must execute a System.exit()0 instruction at the end of the generation (which might cause problems for tools like ant or maven if the wiki generation is part of a list of tasks).

It is possible to configure how the tool will behave after the end of the generation with the preventExit property:

• "false": It is the default value. The tool will execute a System.exit(0) instruction at the end of the generation
• "true": The tool not do anything at the end of the generation
• "runtimeException": The tool will throw a org.docgene.main.ExitRuntimeException at the end of the generation, if the parsing encountered errors, and not do anything if the parsing did not encounter any error

Updating parameters

• "incrementalGeneration": true if the wiki generation is in incremental generation mode. By default this property is set to false
• "incrementalGenerationFile": the file used for the incremental generation mode. By default this property is not set and the default file will be used

Access to external links

Several properties can be used to configure the way external links are accessed. See Access to external links for more information.

APIs

The location of APIs (local or accessible through http) can be specified using one of the two following properties:

• javadoc-<api name>: defines a Javadocs API whose name is api name which points to the directory or http URL defined by the value of the property
• APIs: the path to an APIs XML file

Note that APIs paths can either be:

• Absolute in an external http link
• Relative to the output wiki directory content

See APIs property for more information on how to specify javadocs APIs locations.

Processing empty lines

The emptyLines property specifies how empty lines in the source should be converted:

• "newline" (the default): specifies that empty lines should be processed as new lines
• "break": specifies that empty lines should be processed as break

Any other value will be assumed as "newline".

Custom StyleSheet

The "css" property allows to specify a custom StyleSheet for the HTML result.

Pre syntax packs

The application uses the jeditor library to highlight the pre element syntax. It is possible to use additional syntax packs by specifying the list of jar files containing the syntaxes separated by ";" (semicolon). See syntax highlighting for more information.

For example:

      preSyntax=lib/jEditor-syntaxes.jar

Example

In the following example, we:

• Clean the wiki output before its generation
• Don't check the http URL links
• Specify that the language to use is French
• Add a right index menu

   cleaned=true
   checkHTTPLinks=false
   localization=fr
   rightIndexMenu=right.txt

To use the configuration file:

      java -jar docGenerator.jar input=wiki/input -output=wiki/output -config=config.properties