From b72613132c40c09f5432b44bfec33cb771c22872 Mon Sep 17 00:00:00 2001
From: Max Horn <max@quendi.de>
Date: Fri, 19 Dec 2025 15:11:28 +0100
Subject: [PATCH] Predefine entities VERSION, RELEASEYEAR, RELEASEDATE

---
 CHANGES.md                               |  7 +++++++
 PackageInfo.g                            |  2 +-
 gap/Magic.gd                             | 18 ++++++++++++++++++
 gap/Magic.gi                             | 11 +++++++++++
 tst/manual.expected/_Chapter_AutoDoc.xml | 18 ++++++++++++++++++
 5 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5d356367..ca9c56c2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,12 @@
 This file describes changes in the AutoDoc package.
 
+2025.12.19
+  - Don't replace empty lines in `@BeginCode` blocks by `<P/>`
+  - Fix XML header in generated files (it had a syntax error, which somehow also
+    slips by GAPDoc; so it caused no problems in practice, but the resulting XML
+    was strictly speaking invalid)
+  - Predefine entities `VERSION`, `RELEASEYEAR`, `RELEASEDATE`
+
 2025.10.16
   - Make handling `Date` in `PackageInfo.g` more strict (previously some
     malformed variants were accepted to deal with very old packages, but by
diff --git a/PackageInfo.g b/PackageInfo.g
index 485cbc58..1feb883e 100644
--- a/PackageInfo.g
+++ b/PackageInfo.g
@@ -10,7 +10,7 @@ SetPackageInfo( rec(
 
 PackageName := "AutoDoc",
 Subtitle := "Generate documentation from GAP source code",
-Version := "2025.10.16",
+Version := "2025.12.19",
 
 Date := ~.Version{[ 1 .. 10 ]},
 Date := Concatenation( ~.Date{[ 9, 10 ]}, "/", ~.Date{[ 6, 7 ]}, "/", ~.Date{[ 1 .. 4 ]} ),
diff --git a/gap/Magic.gd b/gap/Magic.gd
index 9d375391..c8a8c893 100644
--- a/gap/Magic.gd
+++ b/gap/Magic.gd
@@ -158,6 +158,24 @@
 #!             This allows you to write <Q>&amp;SomePackage;</Q> and <Q>&amp;RELEASEYEAR;</Q>
 #!             in your documentation, which will be replaced by respective values specified
 #!             in the entities definition.
+#!             <P/>
+#!             Note that &AutoDoc; predefines several entities:
+#!             <List>
+#!             <Mark><A>VERSION</A></Mark>
+#!             <Item>Set to the <C>Version</C> field your package info record.</Item>
+#!             <Mark><A>RELEASEYEAR</A></Mark>
+#!             <Item>Set to a string containing the release year, as derived
+#!                   from the <C>Date</C> field your package info record.</Item>
+#!             <Mark><A>RELEASEDATE</A></Mark>
+#!             <Item>Derived from the <C>Date</C> field your package info record.</Item>
+#!             <Mark><A>SomePackage</A></Mark>
+#!             <Item>
+#!                 The precise name of this entity is derived from the
+#!                 <C>PackageName</C> field your package info record. Note
+#!                 that it is case sensitive. The content is defined as
+#!                 suggested by the example above.
+#!             </Item>
+#!             </List>
 #!         </Item>
 #!
 #!         <Mark><A>TitlePage</A></Mark>
diff --git a/gap/Magic.gi b/gap/Magic.gi
index c9686d11..8b451428 100644
--- a/gap/Magic.gi
+++ b/gap/Magic.gi
@@ -494,6 +494,17 @@ function( arg )
             CreateTitlePage( doc_dir, title_page );
         fi;
 
+        # set some default entities
+        AUTODOC_SetIfMissing( scaffold, "entities", rec() );
+        if IsBound( pkginfo.Version ) then
+            AUTODOC_SetIfMissing( scaffold.entities, "VERSION", pkginfo.Version );
+        fi;
+        if IsBound( pkginfo.Date ) then
+            tmp := AUTODOC_ParseDate( pkginfo.Date );
+            AUTODOC_SetIfMissing( scaffold.entities, "RELEASEYEAR", tmp.year );
+            AUTODOC_SetIfMissing( scaffold.entities, "RELEASEDATE", AUTODOC_FormatDate( tmp ) );
+        fi;
+
         CreateEntitiesPage( gapdoc.bookname, doc_dir, scaffold );
 
         if IsBound( scaffold.MainPage ) and scaffold.MainPage <> false then
diff --git a/tst/manual.expected/_Chapter_AutoDoc.xml b/tst/manual.expected/_Chapter_AutoDoc.xml
index 02ac4500..f707216b 100644
--- a/tst/manual.expected/_Chapter_AutoDoc.xml
+++ b/tst/manual.expected/_Chapter_AutoDoc.xml
@@ -152,6 +152,24 @@
              This allows you to write <Q>&amp;SomePackage;</Q> and <Q>&amp;RELEASEYEAR;</Q>
              in your documentation, which will be replaced by respective values specified
              in the entities definition.
+             <P/>
+             Note that &AutoDoc; predefines several entities:
+             <List>
+             <Mark><A>VERSION</A></Mark>
+             <Item>Set to the <C>Version</C> field your package info record.</Item>
+             <Mark><A>RELEASEYEAR</A></Mark>
+             <Item>Set to a string containing the release year, as derived
+                   from the <C>Date</C> field your package info record.</Item>
+             <Mark><A>RELEASEDATE</A></Mark>
+             <Item>Derived from the <C>Date</C> field your package info record.</Item>
+             <Mark><A>SomePackage</A></Mark>
+             <Item>
+                 The precise name of this entity is derived from the
+                 <C>PackageName</C> field your package info record. Note
+                 that it is case sensitive. The content is defined as
+                 suggested by the example above.
+             </Item>
+             </List>
          </Item>
          <Mark><A>TitlePage</A></Mark>
          <Item>