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.properties
file based on build.properties.sample
npm install
from the project directory to install Node.js dependencies. This need to be repeated if you add new dependencies to gulpfile.js
.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 install
to recreate it.To build Docgen:
mvn install
For some examples see:
src/test
and test.xml
in this projectsrc/manual
in the freemarker
projectsrc/main/docgen
the site
projectFor editing DocBook, we are using XXE with the src/xxe-addon
installed.
If you want to try your modifications, let's say, by regenerating the FreeMarker Manual, just create a Run Configuration in you IDE, with main class org.freemarker.docgen.TransformCommandLine
, then specify these command line arguments:
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 with a java argument like this:
-Ddocgen.generationTime=2020-07-15T17:00Z
This happens automatically during build, in the generate-resources
. The generated output is in target\resources-gulp
.
TODO
The icon font in this project was built using IcoMoon and contains selected icons from: