Command-line starting

It is possible to execute the application by the command-line without showing the UI.

This command-line arguments 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

Version argument

The -version argument^[1]

With no other option present

print the version of the DocJGenerator library on the console. For example:

      java -jar docGenerator.jar -version

Using the tool on Unix-like platforms

You can use the tool on Unix-like platforms exactly as on Windows. For example:

      java -jar -Dfile.encoding=UTF8 soft/docGenerator.jar -config=source/config.properties -input=source -output=wiki

Or with a bash file:

   #!/bin/bash
   java -jar -Dfile.encoding=UTF8 soft/docGenerator.jar -config=source/config.properties -input=source -output=wiki

Input and output properties

The minimal arguments for the command-line starting of the application only specifies the input and the output:

• "input": the input directory or directories where the input XML files and image resources are to be found. If there are more than one directory, the directories paths must be separated by the ";" character. See root directories and packages if you want an explanation on how to use the generator with more than one root directory
• "output": the output directory

General properties

• "config": an optional configuration file (see configuration file)
• "isHeadless": true if the application is used in a headless environment. See also Usage in a headless environment
• "index": the optional index file (can be useful in the case of multiple directories)
• "wikiTitle": the optional title for the wiki home page. By default the title of the home page will be "Home"
• "cleaned": to clean the output directory before the generation
• "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
• "lightbox": specifies if images use lightboxes
• "includeComments": specifies if comments are included. See also Review system
• "styleSheetTheme": specifies yhe CSS file specifying the theming. See also StyleSheet theme
• "locale": The localization for the wiki. See also localization for more information

If the input and output arguments are specified and correspond to existing directories, the application will generate the wiki in the output directory using the specification in the input directory, and exit.

Note that the majority of the arguments (the key/value arguments and obviously "config") can also be specified in a configuration file.

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 javadoc tags) must be checked (true by default)^[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 (true by default)^[3]
  Note that having true for this property (which is the default) can increase the time for the parsing, 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
• "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
• "forkParser": specifies if the parsing will be performed in background threads. See also forkParser parameter for more information
• "defaultHTTPTimeout": set the timeout for checking the availability of an http link 300 ms 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
• "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": allow to add an autocomplete Search box which will be added for each article
• "false": if there is no Search box
• "true" or "articles": if there is a Search box on the articles descriptions only
• "titles": (the default value) if there is a Search box on the articles descriptions 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": true if the PageRank algorithm is 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

• "outputType": the output type (pdf, docx, help, or html). See outputType configuration property
• "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
• "wikiContent" or "chaptersContent": the path of the XML file which filter and configure the content of the wiki output. See also Document content specification
• "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
• "helpPageWidth": the page width used for specifying the images width for the help content
• "cover": the file used for the cover of the ePub file

Performance

• "showDetailedGenerationTimes": true to show a detailed statistics about the generation time. See also Performance for more information
• "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": 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

• "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
• "relaxedSyntax": true if the syntax of the articles is relaxed false by default). 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
• "escapeNonUTF8": true if non UTF8 characters should be escaped in articles (false by default). See also Escaping non UTF8 characters
• "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 (true by default). 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
• "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
• "apidocs": the optional file specifying the the custom internal API documentation. See Internal API documentation configuration
• "limit": to limit the number of articles per directory. The output directory will therefore be separated in several sub-directories which will contain the articles
• "properties": specify a file specifying the properties
• other arguments beginning with $ will define key/value string replacements in the text (see properties file)

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

Inputs and output

The "input" and "output" properties can be undefined in the command-line arguments if the "config" file is defined and contain associated properties for the inputs and output.

Default configuration

By default, the following properties are set when using the command-line:

• The search property is set on "titles" (there is a Search box for the articles titles and their table of content sub-titles)
• The checkLinks property is set to true (the presence of external links is checked)
• The checkHTTPLinks property is set to true (URL links with the "http" protocol are checked)

Note that all File paths can be absolute or relative to the main jar file.

Examples

The most simple generation, with an input directory, and an output directory:

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

Same as the previous one, but uses a version property^[9]

It can for example be used to show the version of the documentation on the header or the footer

:

      java -jar docGenerator.jar -input=wiki/input -output=wiki/output -$version=0.6

We use a configuration file which will contain the properties:

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

The output directory is cleaned before generating the wiki, and the number of output articles per directory is limited:

      java -jar docGenerator.jar -input=wiki/input -output=wiki/output -cleaned=true -limit=500

There are more than one input directories^[10]

See root directories and packages

, and we specifically define our index file:

      java -jar docGenerator.jar -input=wiki/input;wiki2/input -index=myIndex.xml -output=wiki/output