svn commit: r1934793 - httpd/docs-build/trunk

Author: rbowen
Date: Sat May 30 22:28:38 2026
New Revision: 1934793

Log:
Update validate-xhtml to use W3C Nu HTML Checker; improve README

The HTML output now uses HTML5, so DTD-based xmlvalidate no longer
applies. Replace with vnu.jar invocation. Rewrite README with
prerequisites, build targets, and link to docs-project site.

Modified:
   httpd/docs-build/trunk/   (props changed)
   httpd/docs-build/trunk/README
   httpd/docs-build/trunk/build.xml

Modified: httpd/docs-build/trunk/README
==============================================================================
--- httpd/docs-build/trunk/README	Sat May 30 22:04:37 2026	(r1934792)
+++ httpd/docs-build/trunk/README	Sat May 30 22:28:38 2026	(r1934793)
@@ -1,37 +1,76 @@
-## Intro
+# Apache httpd Documentation Build Tools
 
-This repository is checked out into docs/manual/build
-of an httpd working tree to support documentation
-authoring, and works on all httpd branches from 2.0
-through trunk.
+Check out this repository into `docs/manual/build/` of an httpd working
+tree. It works on all httpd branches (2.4 and trunk).
 
-To completely rebuild the docs, use:
+Full documentation project info: https://httpd.apache.org/docs-project/
 
-      ./build.sh all convmap
+## Quick Start
 
-To check for valid XML:
+```bash
+cd docs/manual
+svn co https://svn.apache.org/repos/asf/httpd/docs-build/trunk build
+cd build
+./build.sh all
+```
 
-      ./build.sh validate-xml
+## Prerequisites
 
-To check the resulting HTML:
+- **Java 8+** JDK (for Xalan/Xerces via Ant)
+- **Perl** (for metafile generation)
+- **vnu.jar** (for HTML validation — see below)
 
-      ./build.sh validate-xhtml
+## Building
 
-## Current issues
+Rebuild all languages:
 
-### build.sh
+    ./build.sh all
 
-build.sh sometimes needs to be modified to drop -Xbootclasspath as this parm is gone
-from later SDKs. It should probably NOT be dropped for everyone:
+Rebuild a single language:
 
- - On IBM Java 6 this probably causes a built-in xalan to be used which does not have our patch
-   for splitting the XML and DocType lines.  There could be other more subtle changes.
-   - Impact: ???
+    ./build.sh en
 
-### UTF-8 vs. XML entities in foo.html.en
+Rebuild everything including the convenience map:
 
-Old JDK's happily put UTF-8 bytes into ISO8859-1 english files which seems wrong.
-Newer JDK's (w/o -Xbootclasspath? in build.sh?) will replace them with XML entities.
+    ./build.sh all convmap
 
-Impact: XML entities break manpages (if checked in)
+Regenerate the per-language stylesheets (only needed if you modify
+`style/xsl/language.xsl`):
 
+    ./build.sh bootstrap
+
+List all available targets:
+
+    ./build.sh -projecthelp
+
+## 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.

Modified: httpd/docs-build/trunk/build.xml
==============================================================================
--- httpd/docs-build/trunk/build.xml	Sat May 30 22:04:37 2026	(r1934792)
+++ httpd/docs-build/trunk/build.xml	Sat May 30 22:28:38 2026	(r1934793)
@@ -119,12 +119,20 @@
 <!-- time to time...                                                      -->
 <!-- ==================================================================== -->
 <target name="validate-xhtml" description="- validates all (X)HTML result files">
-    <xmlvalidate lenient="false" failonerror="false" warn="true">
-        <xmlcatalog refid="w3c-catalog" />
+    <!-- HTML5 validation using W3C Nu HTML Checker (vnu.jar).
+         Download from https://github.com/validator/validator/releases
+         and place in build/ or set vnu.jar property. -->
+    <property name="vnu.jar" value="vnu.jar" />
+    <echo message="Validating HTML5 with Nu HTML Checker..." />
+    <apply executable="java" failonerror="false" parallel="true"
+           maxparallel="50">
+        <arg value="-jar" />
+        <arg value="${vnu.jar}" />
+        <arg value="--skip-non-html" />
         <fileset dir="../" includes="**/*.html.*">
             <patternset refid="scratch" />
         </fileset>
-    </xmlvalidate>
+    </apply>
 </target>