commit | 5470c64d1f7921c85323aead0c57eec1e3efd02e | [log] [tgz] |
---|---|---|
author | ddekany <ddekany@apache.org> | Sat Aug 17 22:49:44 2019 +0200 |
committer | ddekany <ddekany@apache.org> | Sat Aug 17 22:49:44 2019 +0200 |
tree | e82a269afb089b578b678cd44905ac0cfd35895e | |
parent | 517a8f36c34792b6c479e728b9e8310473b7a6a3 [diff] |
Updated XXE addon howto.txt
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:
ant all
This will create lib/docgen.jar
and build/api
.
For documentation see build/api/index.html
. Especially, read the documentation of the Transform
class there.
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. 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:
ant update-deps
To compile LESS and JS separately from the regular Ant build, run:
ant gulp
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:
ant publish-override
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:
ant ide-dependencies
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:
-Ddocgen.generationTime=2015-12-19T17:00Z
As of this writing, the “docgen” dependency is get by freemarker
and site
from the Ivy repo on http://freemarker.org/repos/ivy/
. Those modifying docgen should upload the fresh docgen.jar
there occasonally. For that, first issue:
ant server-publish-last-build
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: