Docgen is used to generate HTML pages from the two DocBook 5 “book” XML-s that the FreeMarker Manual and the FreeMarker homepage is written in. As such, it mostly only implements the subset of Docgen elements that we actually use, but otherwise it tries to be reusable in other projects as well.
Before building for the first time:
build.propertiesfile based on
npm installfrom the project directory to install Node.js dependencies. This need to be repeated if you add new dependencies to
Possible node.js related problems and solutions:
npm: Open a new terminal (command window) so that it pick up the “path” environment variable changes. Adjust it if necessary.
npm installto recreate it.
To build Docgen:
This will create
For documentation see
build/api/index.html. Especially, read the documentation of the
Transform class there.
For some examples see:
test.xmlin this project
For editing DocBook, we are using XXE with the
src/xxe-addon installed. Unfortunatelly, the free edition of XXE was discontinued long ago, but if there are problems with the old free version, or you will do serious amount of editing, we can contact XMLmind for more free licenses (in exchange for showing their logo on the generated pages).
If you run into dependency errors, you may need to issue:
To compile LESS and JS separately from the regular Ant build, run:
If you have modified
docgen and want to try the new version then we don‘t recomment doing that with Ant, because it’s slow and also tricky if you need to try it in a dependent project. Instead, see the IDE section later.
But if you must do it with Ant, issue:
This will shadow the
docgen artifact that comes from the Ivy repo on freemarker.org. Then, in the dependent project issue
ant update-deps so that it picks up your version.
You need to run this:
This will create an
ide-dependencies directory that contains all the jars that you have to add to the classpath in the IDE. Note that here we assume that you have run the build or at least
ant update-deps earlier.
You could also use IvyDE instead, with configuration name “IDE”, but as the dependencies hardly ever change, it's unnecessary.
If you want to try your modifications, let‘s say, by regenerating the FreeMarker Manual, don’t fiddle with Ant. Just create a Run Configuration in Eclipse with main class
org.freemarker.docgen.TransformCommandLine, then on the “Arguments” tab enter “Program arguments” like:
C:\work\freemarker\git\freemarker-2.3-gae\src\manual C:\work\freemarker\git\freemarker-2.3-gae\build\manual offline=true
To ease comparing outputs, you can set a fixed value for the last modification time in the “VM arguments” box be entering something like:
As of this writing, the “docgen” dependency is get by
sitefrom the Ivy repo on
http://freemarker.org/repos/ivy/. Those modifying docgen should upload the fresh
docgen.jar there occasonally. For that, first issue:
This won't actually upload anything, but you will find the directory structure to upload in the
build/dummy-server-ivy-repo directory. See the README file in the site Git repo on how to upload content to the FreeMarker homepage!
The icon font in this project was built using IcoMoon and contains selected icons from: