Predefine entities VERSION, RELEASEYEAR, RELEASEDATE (#295)

Author: fingolfin

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

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 ]} ),

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>

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

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>