From b09a089f549aa7c67ab4fecc07da47c28f7526d4 Mon Sep 17 00:00:00 2001
From: Mike Dunston <m_dunston@comcast.net>
Date: Wed, 20 Nov 2024 07:31:12 -0800
Subject: [PATCH 1/4] Initial implementation of the Hints() element for Group
 and Int fields in the CDI. This is based on how the <map> element is handled.

---
 src/openlcb/ConfigRenderer.hxx       | 24 ++++++++++++++++++++++--
 src/openlcb/ConfigRepresentation.hxx |  1 +
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/openlcb/ConfigRenderer.hxx b/src/openlcb/ConfigRenderer.hxx
index cc307870f..102dc463f 100644
--- a/src/openlcb/ConfigRenderer.hxx
+++ b/src/openlcb/ConfigRenderer.hxx
@@ -52,6 +52,7 @@ struct AtomConfigDefs
     DECLARE_OPTIONALARG(Name, name, const char *, 0, nullptr);
     DECLARE_OPTIONALARG(Description, description, const char *, 1, nullptr);
     DECLARE_OPTIONALARG(MapValues, mapvalues, const char *, 2, nullptr);
+    DECLARE_OPTIONALARG(Hints, hints, const char *, 3, nullptr);
     DECLARE_OPTIONALARG(SkipInit, skip_init, int, 15, 0);
     DECLARE_OPTIONALARG(Offset, offset, int, 10, 0);
     using Base = OptionalArg<AtomConfigDefs, Name, Description, MapValues, SkipInit, Offset>;
@@ -71,6 +72,8 @@ public:
     DEFINE_OPTIONALARG(Description, description, const char *);
     /// Represent the value enclosed in the "<map>" tag of the data element.
     DEFINE_OPTIONALARG(MapValues, mapvalues, const char *);
+    /// Represent the value enclosed in the "<hints>" tag of the data element.
+    DEFINE_OPTIONALARG(Hints, hints, const char *);
     /// When set to true, the event initializers will be skipped in this event
     /// or group.
     DEFINE_OPTIONALARG(SkipInit, skip_init, int);
@@ -94,6 +97,10 @@ public:
         {
             *r += StringPrintf("<map>%s</map>\n", mapvalues());
         }
+        if (hints())
+        {
+            *r += StringPrintf("<hints>%s</hints>\n", mapvalues());
+        }
     }
 };
 
@@ -147,7 +154,7 @@ struct NumericConfigDefs : public AtomConfigDefs
     DECLARE_OPTIONALARG(Max, maxvalue, int, 7, INT_MAX);
     DECLARE_OPTIONALARG(Default, defaultvalue, int, 8, INT_MAX);
     using Base = OptionalArg<NumericConfigDefs, Name, Description, MapValues,
-                             Min, Max, Default, SkipInit, Offset>;
+                             Hints, Min, Max, Default, SkipInit, Offset>;
 };
 
 /// Definitions for the options for numeric CDI entries.
@@ -164,6 +171,8 @@ public:
     DEFINE_OPTIONALARG(Description, description, const char *);
     /// Represent the value enclosed in the <map> tag of the data element.
     DEFINE_OPTIONALARG(MapValues, mapvalues, const char *);
+    /// Represent the value enclosed in the <hints> tag of the data element.
+    DEFINE_OPTIONALARG(Hints, hints, const char *);
     DEFINE_OPTIONALARG(Min, minvalue, int);
     DEFINE_OPTIONALARG(Max, maxvalue, int);
     DEFINE_OPTIONALARG(Default, defaultvalue, int);
@@ -197,6 +206,10 @@ public:
         {
             *r += StringPrintf("<map>%s</map>\n", mapvalues());
         }
+        if (hints())
+        {
+            *r += StringPrintf("<hints>%s</hints>\n", mapvalues());
+        }
     }
 
     int clip(int value) {
@@ -263,7 +276,7 @@ struct GroupConfigDefs : public AtomConfigDefs
     DECLARE_OPTIONALARG(FixedSize, fixed_size, unsigned, 13, 0);
     DECLARE_OPTIONALARG(Hidden, hidden, int, 14, 0);
     using Base = OptionalArg<GroupConfigDefs, Name, Description, Segment,
-                             Offset, RepName, FixedSize, Hidden>;
+                             Hints, Offset, RepName, FixedSize, Hidden>;
 };
 
 /// Implementation class for the condifuration options of a CDI group element.
@@ -299,6 +312,9 @@ public:
     /// reserved and skipped.
     DEFINE_OPTIONALARG(Hidden, hidden, int);
 
+    /// Represents the value enclosed in the <hints> tag of the data element.
+    DEFINE_OPTIONALARG(Hints, hints, const char*);
+
     /// Declares that this group is a toplevel CDI. Causes the group to render
     /// the xml header.
     /// static constexpr Segment MainCdi() { return Segment(-2); }
@@ -358,6 +374,10 @@ public:
             *r +=
                 StringPrintf("<repname>%s</repname>\n", repname());
         }
+        if (hints())
+        {
+            *r += StringPrintf("<hints>%s</hints>\n", hints());
+        }
     }
 };
 
diff --git a/src/openlcb/ConfigRepresentation.hxx b/src/openlcb/ConfigRepresentation.hxx
index 7fbbab751..f931a11f5 100644
--- a/src/openlcb/ConfigRepresentation.hxx
+++ b/src/openlcb/ConfigRepresentation.hxx
@@ -100,6 +100,7 @@ public:
     using Name = AtomConfigOptions::Name;
     using Description = AtomConfigOptions::Description;
     using MapValues = AtomConfigOptions::MapValues;
+    using Hints = AtomConfigOptions::Hints;
     using SkipInit = AtomConfigOptions::SkipInit;
     using Min = NumericConfigOptions::Min;
     using Max = NumericConfigOptions::Max;

From 419bbd8d160a17c205118e65ba212c51617b03be Mon Sep 17 00:00:00 2001
From: Mike Dunston <m_dunston@comcast.net>
Date: Fri, 22 Nov 2024 07:23:03 -0800
Subject: [PATCH 2/4] Add LinkRef/LinkText to Group/Segment and Identification.

---
 src/openlcb/ConfigRenderer.hxx       | 70 +++++++++++++++++++++++-----
 src/openlcb/ConfigRepresentation.hxx |  2 +
 2 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/src/openlcb/ConfigRenderer.hxx b/src/openlcb/ConfigRenderer.hxx
index 102dc463f..47b90b64a 100644
--- a/src/openlcb/ConfigRenderer.hxx
+++ b/src/openlcb/ConfigRenderer.hxx
@@ -55,7 +55,8 @@ struct AtomConfigDefs
     DECLARE_OPTIONALARG(Hints, hints, const char *, 3, nullptr);
     DECLARE_OPTIONALARG(SkipInit, skip_init, int, 15, 0);
     DECLARE_OPTIONALARG(Offset, offset, int, 10, 0);
-    using Base = OptionalArg<AtomConfigDefs, Name, Description, MapValues, SkipInit, Offset>;
+    using Base = OptionalArg<AtomConfigDefs, Name, Description, MapValues,
+                             Hints, SkipInit, Offset>;
 };
 
 /// Configuration implementation class for CDI Atom elements (strings, events
@@ -99,7 +100,7 @@ public:
         }
         if (hints())
         {
-            *r += StringPrintf("<hints>%s</hints>\n", mapvalues());
+            *r += StringPrintf("<hints>%s</hints>\n", hints());
         }
     }
 };
@@ -190,6 +191,10 @@ public:
             *r +=
                 StringPrintf("<description>%s</description>\n", description());
         }
+        if (hints())
+        {
+            *r += StringPrintf("<hints>%s</hints>\n", hints());
+        }
         if (minvalue() != INT_MAX)
         {
             *r += StringPrintf("<min>%d</min>\n", minvalue());
@@ -206,10 +211,6 @@ public:
         {
             *r += StringPrintf("<map>%s</map>\n", mapvalues());
         }
-        if (hints())
-        {
-            *r += StringPrintf("<hints>%s</hints>\n", mapvalues());
-        }
     }
 
     int clip(int value) {
@@ -275,8 +276,12 @@ struct GroupConfigDefs : public AtomConfigDefs
     DECLARE_OPTIONALARG(RepName, repname, const char*, 12, nullptr);
     DECLARE_OPTIONALARG(FixedSize, fixed_size, unsigned, 13, 0);
     DECLARE_OPTIONALARG(Hidden, hidden, int, 14, 0);
+    // 15 is used for SkipInit
+    DECLARE_OPTIONALARG(LinkRef, linkref, const char *, 16, nullptr);
+    DECLARE_OPTIONALARG(LinkText, linktext, const char *, 17, nullptr);
     using Base = OptionalArg<GroupConfigDefs, Name, Description, Segment,
-                             Hints, Offset, RepName, FixedSize, Hidden>;
+                             Hints, LinkRef, LinkText, Offset, RepName,
+                             FixedSize, Hidden>;
 };
 
 /// Implementation class for the condifuration options of a CDI group element.
@@ -312,8 +317,14 @@ public:
     /// reserved and skipped.
     DEFINE_OPTIONALARG(Hidden, hidden, int);
 
-    /// Represents the value enclosed in the <hints> tag of the data element.
-    DEFINE_OPTIONALARG(Hints, hints, const char*);
+    /// Represent the value enclosed in the <hints> tag of the data element.
+    DEFINE_OPTIONALARG(Hints, hints, const char *);
+
+    /// Represent the <link ref=..> value.
+    DEFINE_OPTIONALARG(LinkRef, linkref, const char *);
+
+    /// Represent the value enclosed in the <link> tag of the data element.
+    DEFINE_OPTIONALARG(LinkText, linktext, const char *);
 
     /// Declares that this group is a toplevel CDI. Causes the group to render
     /// the xml header.
@@ -369,14 +380,28 @@ public:
             *r +=
                 StringPrintf("<description>%s</description>\n", description());
         }
+        if (hints())
+        {
+            *r += StringPrintf("<hints>%s</hints>\n", hints());
+        }
         if (repname())
         {
             *r +=
                 StringPrintf("<repname>%s</repname>\n", repname());
         }
-        if (hints())
+        if (linkref())
         {
-            *r += StringPrintf("<hints>%s</hints>\n", hints());
+            *r +=
+                StringPrintf("<link ref=\"%s\"", linkref());
+            if (linktext())
+            {
+                *r +=
+                    StringPrintf(">%s</link>\n", linktext());
+            }
+            else
+            {
+                *r += " />\n";
+            }
         }
     }
 };
@@ -500,8 +525,13 @@ struct IdentificationConfigDefs
     DECLARE_OPTIONALARG(Model, model, const char *, 1, nullptr);
     DECLARE_OPTIONALARG(HwVersion, hardware_version, const char *, 2, nullptr);
     DECLARE_OPTIONALARG(SwVersion, software_version, const char *, 3, nullptr);
+    // NOTE: the unique index for LinkRef and LinkText must match the values
+    // used in GroupConfigDefs otherwise complile_cdi will enter recursive loop
+    // and segfault.
+    DECLARE_OPTIONALARG(LinkRef, linkref, const char *, 16, nullptr);
+    DECLARE_OPTIONALARG(LinkText, linktext, const char *, 17, nullptr);
     using Base = OptionalArg<IdentificationConfigDefs, Manufacturer, Model,
-                             HwVersion, SwVersion>;
+                             HwVersion, SwVersion, LinkRef, LinkText>;
 };
 
 /// Configuration implementation options for rendering CDI (identification)
@@ -516,6 +546,8 @@ public:
     DEFINE_OPTIONALARG(Model, model, const char *);
     DEFINE_OPTIONALARG(HwVersion, hardware_version, const char *);
     DEFINE_OPTIONALARG(SwVersion, software_version, const char *);
+    DEFINE_OPTIONALARG(LinkRef, linkref, const char *);
+    DEFINE_OPTIONALARG(LinkText, linktext, const char *);
 
     constexpr int skip_init() const
     {
@@ -562,6 +594,20 @@ public:
             alt(opts.hardware_version(), SNIP_STATIC_DATA.hardware_version), s);
         render_tag("softwareVersion",
             alt(opts.software_version(), SNIP_STATIC_DATA.software_version), s);
+        if (opts.linkref())
+        {
+            *s +=
+                StringPrintf("<link ref=\"%s\"", opts.linkref());
+            if (opts.linktext())
+            {
+                *s +=
+                    StringPrintf(">%s</link>\n", opts.linktext());
+            }
+            else
+            {
+                *s += " />\n";
+            }
+        }
         *s += "</identification>\n";
     }
 };
diff --git a/src/openlcb/ConfigRepresentation.hxx b/src/openlcb/ConfigRepresentation.hxx
index f931a11f5..ae7a109a8 100644
--- a/src/openlcb/ConfigRepresentation.hxx
+++ b/src/openlcb/ConfigRepresentation.hxx
@@ -110,6 +110,8 @@ public:
     using RepName = GroupConfigOptions::RepName;
     using FixedSize = GroupConfigOptions::FixedSize;
     using Hidden = GroupConfigOptions::Hidden;
+    using LinkRef = GroupConfigOptions::LinkRef;
+    using LinkText = GroupConfigOptions::LinkText;
     using Manufacturer = IdentificationConfigOptions::Manufacturer;
     using Model = IdentificationConfigOptions::Model;
     using HwVersion = IdentificationConfigOptions::HwVersion;

From 6fef9662e741f81c343e14c7541b39c19995411f Mon Sep 17 00:00:00 2001
From: Mike Dunston <m_dunston@comcast.net>
Date: Fri, 22 Nov 2024 07:48:16 -0800
Subject: [PATCH 3/4] Default link text to link ref when not specified

---
 src/openlcb/ConfigRenderer.hxx | 24 ++++--------------------
 1 file changed, 4 insertions(+), 20 deletions(-)

diff --git a/src/openlcb/ConfigRenderer.hxx b/src/openlcb/ConfigRenderer.hxx
index 47b90b64a..22cbf9b2f 100644
--- a/src/openlcb/ConfigRenderer.hxx
+++ b/src/openlcb/ConfigRenderer.hxx
@@ -392,16 +392,8 @@ public:
         if (linkref())
         {
             *r +=
-                StringPrintf("<link ref=\"%s\"", linkref());
-            if (linktext())
-            {
-                *r +=
-                    StringPrintf(">%s</link>\n", linktext());
-            }
-            else
-            {
-                *r += " />\n";
-            }
+                StringPrintf("<link ref=\"%s\">%s</link>\n", linkref(),
+                linktext() ? linktext() : linkref());
         }
     }
 };
@@ -597,16 +589,8 @@ public:
         if (opts.linkref())
         {
             *s +=
-                StringPrintf("<link ref=\"%s\"", opts.linkref());
-            if (opts.linktext())
-            {
-                *s +=
-                    StringPrintf(">%s</link>\n", opts.linktext());
-            }
-            else
-            {
-                *s += " />\n";
-            }
+                StringPrintf("<link ref=\"%s\">%s</link>\n", opts.linkref(),
+                alt(opts.linktext(), opts.linkref()));
         }
         *s += "</identification>\n";
     }

From 53f31f32b98284609f957bbd956ba428f653713a Mon Sep 17 00:00:00 2001
From: Mike Dunston <m_dunston@comcast.net>
Date: Fri, 22 Nov 2024 07:57:30 -0800
Subject: [PATCH 4/4] Fix Group level link text reference for when missing

---
 src/openlcb/ConfigRenderer.hxx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/openlcb/ConfigRenderer.hxx b/src/openlcb/ConfigRenderer.hxx
index 22cbf9b2f..b7d1cb603 100644
--- a/src/openlcb/ConfigRenderer.hxx
+++ b/src/openlcb/ConfigRenderer.hxx
@@ -393,7 +393,7 @@ public:
         {
             *r +=
                 StringPrintf("<link ref=\"%s\">%s</link>\n", linkref(),
-                linktext() ? linktext() : linkref());
+                has_linktext() ? linktext() : linkref());
         }
     }
 };