HBX-2984: Create Reference Guide for Ant

  - Add an example using the native '<configuration>' element
  - Add XML snippet illustrating the use of exporters

Signed-off-by: Koen Aers <[email protected]>

Author: koentsje

ant/docs/examples/native-cfg/.gitignore

@@ -0,0 +1,18 @@
+############################################################################
+# Hibernate Tools, Tooling for your Hibernate Projects                     #
+#                                                                          #
+# Copyright 2004-2025 Red Hat, Inc.                                        #
+#                                                                          #
+# Licensed under the Apache License, Version 2.0 (the "License");          #
+# you may not use this file except in compliance with the License.         #
+# You may obtain a copy of the License at                                  #
+#                                                                          #
+#     http://www.apache.org/licenses/LICENSE-2.0                           #
+#                                                                          #
+# Unless required by applicable law or agreed to in writing, software      #
+# distributed under the License is distributed on an "AS IS" basis,        #
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
+# See the License for the specific language governing permissions and      #
+# limitations under the License.                                           #
+############################################################################
+generated-sources

ant/docs/examples/native-cfg/README.md

@@ -0,0 +1,18 @@
+<!--
+  ~ Copyright 2004 - 2025 Red Hat, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" basis,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+To run this example:
+  - Have [Apache Ant](https://ant.apache.org) installed
+  - Issue `ant` from a command-line window 

ant/docs/examples/native-cfg/build.xml

@@ -0,0 +1,36 @@
+<!--
+  ~ Copyright 2004 - 2025 Red Hat, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" basis,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<project name="native-cfg" default="reveng">
+
+  <!-- Include the 'hibernatetool' task definition from the file '../common/included.xml' -->
+  <include file="../common/included.xml"/>
+
+  <target name="clean">
+    <!-- Delete the folder 'generated-sources' if it exists -->
+    <delete dir="generated-sources"/>
+  </target>
+
+  <target name="reveng" depends="clean">
+    <hibernatetool destdir="generated-sources">
+      <!-- Native configuration reading properties from '../common/hibernate.properties' -->
+      <configuration propertyfile="../common/hibernate.properties"/>
+      <!-- Transform the 'hibernate.properties' file in 'hibernate.cfg.xml' -->
+      <hbm2cfgxml/>
+    </hibernatetool>
+  </target>
+
+</project>
+

ant/docs/reference-guide.md

@@ -186,6 +186,15 @@ elements is to be found in section 2 further down this guide.
 Hibernate Tools is very versatile and can be used to generate a wide variety of artefacts. This generation
 is performed when adding one or more exporter elements to the `<hibernatetool>` task. 
 
+```xml
+<target name="reveng">
+    <hibernatetool destdir="...">
+        <jdbcconfiguration propertyfile="hibernate.properties" />
+        <hbm2java/>
+    </hibernatetool>
+</target>
+```
+
 The most used exporters are
 * `<hbm2java>` for the generation of Java files
 * `<hbmtemplate>` when generating artefacts based on custom templates