FAQ

What is docJGenerator?

docJGenerator is a Java application allowing to generate a html site with a list of XML files defining a documentation. It allows to produce an offline wiki-like site.

Which version of Java should I use?

The latest version of the project require Java 8.

How this wiki was produced?

This wiki was produced using the docJGenerator application.

I have a version of the library, but I don't remember which version

Just type in the console:

      java -jar docGenerator.jar -version

Alternatively double click on the jar and look at the version in the "About" menu.

So the library just use a custom html format?

No, the format is XML, even if some constructs look like HTML. Your files must have the XML extension, not HTML, and you don't have to include things such as "body", "html", "header", etc...

Is there an editor for the wiki?

You can edit the articles using any text editor. But the application also provides an editor for the wiki.

I want to use non ASCII characters in my wiki, and I don't want to escape them myself, how can I do that?

By default docJGenerator escape non UTF8 characters for you.

I want to use my language for the text in the wiki rather than English, is it possible?

Yes, you have to configure the Locale to use for the wiki. See localization.

I want to use the generation tool in a headless environment, is it possible?

Yes, you can configure it on the command-line. see Usage in a headless environment.

How the syntax of docJGenerator relates to Markdown or Wikipedia syntax?

Wikipedia uses the Mediawiki syntax. See the comparison with wikipedia syntax article for more information. It is possible to use some of the constructs of the Mediawiki syntax by configuring the usage of Relaxed Syntax. It is also possible to specify articles using the Mediawiki syntax directly (see mediawiki syntax) or the Markdown syntax (see markdown syntax).

I don't understand how to do what I want

See how to for more information.

I don't want to use XML, do you support a Markdown or Mediawiki syntax?

Yes, see mediawiki syntax or markdown syntax.

Is it possible to add comments or TODOs in the wiki?

Yes, see todo and review system for more information.

How to I reference the index article?

To specify a reference to the index article, just use the _index_ name for the reference id.

What is the character encoding of the various output files generated by the tool?

You don't need to bother about the platform default character encoding, the generator make sure that all output files are encoded in UTF-8, whatever the encoding of the input files or the platform default character encoding.

OK, I use the Markdown syntax, but how can I link articles between the XML articles and the Markdown articles?

From markdown, you link the articles by their relative or absolute path. From XML articles, you can use the "path" attribute with the ref element.

How docJGenerator compares to X / Y / Z wiki software ?

See comparison with other wikis softwares.

What is the performance of the wiki generator?

The parsing and HTML generation is rather fast if you don't check the validity of external links. For example on my PC it takes only 1 second to parse this wiki and perform the generation without checking the external links. However the validation of external HTTP links can take more time (depending on the number of links you want to check), so prepare to increase the parsing time if the checkHTTPLinks property is set to true (which is the default). For example, for this wiki the time for the parsing and generation increase to 6 seconds if external links are checked.

Do I have to respect a specific directory structure for my files?

No, docJGenerator will automatically walk the entire directory tree for your articles, and as for any wiki, it does not use any file structure to classify its articles. However you must know that the tool will skip directories named as "doc-files" (see doc-files to understand why).

How do I include resources, files, javadocs, etc... to the wiki?

It is possible to link to images, resource files, or even whole APIs. See linking to local resources.

I want to include hand-written html, is it possible?

Yes, see including html content

I want to embed an API for Python / Java / etc..., is it possible?

Yes, see APIs documentation.

In fact I would prefer to link to the API on the Web

It is also possible, see the same APIs documentation article.

I don't understand all the configuration options

There are several ways to configure the tool:

• By using the GUI interface
• By using the command-line arguments to configure the options
• By using the configuration file to configure the options

Note that you can use the GUI interface to generate a configuration file with the options you selected in the GUI (see Saving a configuration file).

Is it possible to customize the way some elements are presented?

Yes, see customizing the elements style .

I want the wiki output to be as small as possible, what can I do?

Don't use the Full text search except at the maximum level of compression, because it can be huge (more than 700 Ko for the compressed format for this wiki). However, using the Full text search at the maximum level of compression only amounts to 300 ko.

I want a PDF or DOCX output rather than a HTML wiki, is it possible?

Yes, see PDF generation and DOCX generation.

In fact, want an Epub output rather than a HTML wiki, is it possible?

Yes, see Epub generation.

I am lost, there are too many options for the generation

See Basic usage.

Is it possible to produce several versions of the wiki depending on our configuration?

Yes, see packages and Conditions. You can also filter the content of the wiki by specifying the Wiki content specification.

Part of my wiki is not finished, and I don't want to include it in the generation

You can use packages and configure their packages dependencies.

It is possible to specify that you accept dependencies from the finished package to the unfinished packages, don't include the unfinished packages in the generation, but don't see errors for the associated references.

I want to add a search box in my wiki, is it possible?

See search box. You can even have full text search.

I want to include APIs in my wiki, how can I do it?

You have two options:

• Either link an element in the wiki to an existing external API (such as a javadoc)
• Or embed the API as a part of the inlined wiki content, as a regular tag

See APIs elements for more information.

I want to add TODOs in the wiki and know how many are still there, is it possible?

Yes, see todo.

I don't want a dictionary or categories, is it possible?

Yes, see Getting rid of the dictionary and Getting rid of the categories.

Is don't understand some errors detected during the parsing?

See errors for more information.

Is it possible to show in the wiki the status of errors detected during the parsing?

Yes, see showing the wiki status.

I want to automatically add elements after the parsing such as requirements, is it possible?

Yes, see Scripting.

I want to use docJGenerator as a library in my own application, is it possible?

Yes, see docJGenerator API. You can programmatically generate a wiki if you want.

How can I speed-up the performance of the generator?

You can have informations on how to manage the performance of the generator in the Performance article.

I have strange errors in the console when generating, or the result is not as expected, can you help me?

See Troubleshooting.

Do you provide some tutorials to show how it works?

Yes, look for the tutorials.