README.md - freemarker-docgen - Git at Google

 # Docgen

 ## About

 Docgen was originally written to generate HTML pages from the DocBook 5 XML
 that [the FreeMarker Manual](http://freemarker.org/docs/) is written in. As
 such, it's not a general purpose DocBook 5 to HTML converter, however, we
 use it for other projects as well, so it's not entirely specialized either.

 ## Requirements

 You must have the following libraries installed to build this project:

 * [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
 * [NodeJS 0.10 or higher](https://nodejs.org/)
 * [Apache Ant](http://ant.apache.org/bindownload.cgi)

 ## Usage

 Before building for the first time:
 * JDK 8 must be installed (tried with 1.8.0_20)
 * Apache Ant must be installed (tried with 1.8.1).
 * [Node.js](https://nodejs.org/) must be installed (tried with v0.10.32).
 * Create a `build.properties` file based on `build.properties.sample`
 * Issue `npm install` from the project directory to install Node.js
   dependencies. This need to be repeated if you add new dependencies
   to `gulpfile.js`.

 To build Docgen:

 ```sh
 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`, and of course, `src/manual`
 in the [`freemarker` project][fmProj].

 For editing DocBook, we are using [XXE](http://www.xmlmind.com/xmleditor/)
 with the `src/xxe-addon` installed.

 ## Building tricks

 If you run into dependency errors, you may need to issue:

 ```sh
 ant update-deps
 ```

 If you have modified `docgen`, and want to try the new version in the
 [`freemarker` project][fmProj], you will have to issue:

 ```sh
 ant publish-override
 ```

 This will shadow the `docgen` artifact that comes from the Ivy repo on
 [freemarker.org](http://freemarker.org). Then, in the `freemarker` project you
 have to issue `ant update-deps` so that it picks up your version.

 ### Compiling LESS and JS

 To compile LESS and JS separately from the regular ant build, run:

 ```sh
 ant gulp
 ```


 ## Eclipse and other IDE-s

 You need to run this:

 ```sh
 ant ide-dependencies
 ```

 This will create an `ide-dependencies` library 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 "IDE", but as the
 dependencies hardly ever change, it's unnecessary.

 [fmProj]: https://github.com/freemarker/freemarker

 ## Icon Font Attribution

 The icon font in this project was built using [IcoMoon](https://icomoon.io/)
 and contains selected icons from:

 * [Entypo](http://www.entypo.com/) by [Daniel Bruce](http://www.danielbruce.se/)
 * [Font Awesome](http://fontawesome.io) by Dave Gandy.
 * [Google's Material Design Icons](https://github.com/google/material-design-icons)
	# Docgen

	## About

	Docgen was originally written to generate HTML pages from the DocBook 5 XML
	that [the FreeMarker Manual](http://freemarker.org/docs/) is written in. As
	such, it's not a general purpose DocBook 5 to HTML converter, however, we
	use it for other projects as well, so it's not entirely specialized either.

	## Requirements

	You must have the following libraries installed to build this project:

	* [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
	* [NodeJS 0.10 or higher](https://nodejs.org/)
	* [Apache Ant](http://ant.apache.org/bindownload.cgi)

	## Usage

	Before building for the first time:
	* JDK 8 must be installed (tried with 1.8.0_20)
	* Apache Ant must be installed (tried with 1.8.1).
	* [Node.js](https://nodejs.org/) must be installed (tried with v0.10.32).
	* Create a `build.properties` file based on `build.properties.sample`
	* Issue `npm install` from the project directory to install Node.js
	dependencies. This need to be repeated if you add new dependencies
	to `gulpfile.js`.

	To build Docgen:

	```sh
	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`, and of course, `src/manual`
	in the [`freemarker` project][fmProj].

	For editing DocBook, we are using [XXE](http://www.xmlmind.com/xmleditor/)
	with the `src/xxe-addon` installed.

	## Building tricks

	If you run into dependency errors, you may need to issue:

	```sh
	ant update-deps
	```

	If you have modified `docgen`, and want to try the new version in the
	[`freemarker` project][fmProj], you will have to issue:

	```sh
	ant publish-override
	```

	This will shadow the `docgen` artifact that comes from the Ivy repo on
	[freemarker.org](http://freemarker.org). Then, in the `freemarker` project you
	have to issue `ant update-deps` so that it picks up your version.

	### Compiling LESS and JS

	To compile LESS and JS separately from the regular ant build, run:

	```sh
	ant gulp
	```


	## Eclipse and other IDE-s

	You need to run this:

	```sh
	ant ide-dependencies
	```

	This will create an `ide-dependencies` library 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 "IDE", but as the
	dependencies hardly ever change, it's unnecessary.

	[fmProj]: https://github.com/freemarker/freemarker

	## Icon Font Attribution

	The icon font in this project was built using [IcoMoon](https://icomoon.io/)
	and contains selected icons from:

	* [Entypo](http://www.entypo.com/) by [Daniel Bruce](http://www.danielbruce.se/)
	* [Font Awesome](http://fontawesome.io) by Dave Gandy.
	* [Google's Material Design Icons](https://github.com/google/material-design-icons)