# Apache httpd Documentation Build Tools

Check out this repository into `docs/manual/build/` of an httpd working
tree. It works on all httpd branches (2.4 and trunk).

Full documentation project info: https://httpd.apache.org/docs-project/

## Quick Start

```bash
cd docs/manual
svn co https://svn.apache.org/repos/asf/httpd/docs-build/trunk build
cd build
./build.sh all
```

## Prerequisites

- **Java 8+** JDK (for Xalan/Xerces via Ant)
- **Perl** (for metafile generation)
- **vnu.jar** (for HTML validation — see below)

## Building

Rebuild all languages:

    ./build.sh all

Rebuild a single language:

    ./build.sh en

Rebuild everything including the convenience map:

    ./build.sh all convmap

Regenerate the per-language stylesheets (only needed if you modify
`style/xsl/language.xsl`):

    ./build.sh bootstrap

List all available targets:

    ./build.sh -projecthelp
    ./build.sh -p

## Validating

Check source XML is well-formed:

    ./build.sh validate-xml

Check the generated HTML:

    ./build.sh validate-xhtml

The `validate-xhtml` target uses the W3C Nu HTML Checker. Download
`vnu.jar` into this directory if you don't already have it:

    curl -L -o vnu.jar https://github.com/validator/validator/releases/download/latest/vnu.jar

See https://github.com/validator/validator for details.

## Known Issues

### build.sh -Xbootclasspath

`build.sh` may need the `-Xbootclasspath` flag removed on newer JDKs
where it is no longer supported. On very old JVMs (IBM Java 6) removing
it may cause a built-in Xalan to be used instead of the patched one
bundled here.

### UTF-8 vs. XML entities

Newer JDKs may emit XML character entities (e.g. `é`) where older
ones wrote raw UTF-8 bytes into ISO-8859-1 English files. This can
break nroff man page generation if the entity-laden files are committed.