Centralize and document TRACE tags using X-macros (#7657)

* Introduce X-macro-based trace tag definition
- Created trace_tags.def to centralize TRACE tag definitions
- Each tag includes a symbolic name and description
- Set up enum class TraceTag for type-safe usage in TRACE macros

* Add script to generate Markdown documentation from trace_tags.def
- Python script parses trace_tags.def and outputs trace_tags.md

* Refactor TRACE_NEW to prepend TraceTag and pass enum to is_trace_enabled

* trace: improve trace tag handling system with hierarchical tagging

- Introduce hierarchical tag-class structure: enabling a tag class activates all child tags
- Unify TRACE, STRACE, SCTRACE, and CTRACE under enum TraceTag
- Implement initial version of trace_tag.def using X(tag, tag_class, description)
  (class names and descriptions to be refined in a future update)

* trace: replace all string-based TRACE tags with enum TraceTag
- Migrated all TRACE, STRACE, SCTRACE, and CTRACE macros to use enum TraceTag values instead of raw string literals

* trace : add cstring header

* trace : Add Markdown documentation generation from trace_tags.def via mk_api_doc.py

* trace : rename macro parameter 'class' to 'tag_class' and remove Unicode comment in trace_tags.h.

* trace : Add TODO comment for future implementation of tag_class activation

* trace : Disable code related to tag_class until implementation is ready (#7663).

src/sat/sat_gc.cpp

@@ -36,7 +36,7 @@ namespace sat {
 
     void solver::do_gc() {
         if (!should_gc()) return;
-        TRACE("sat", tout << m_conflicts_since_gc << " " << m_gc_threshold << "\n";);
+        TRACE(sat, tout << m_conflicts_since_gc << " " << m_gc_threshold << "\n";);
         unsigned gc = m_stats.m_gc_clause;
         m_conflicts_since_gc = 0;
         m_gc_threshold += m_config.m_gc_increment;
@@ -157,7 +157,7 @@ namespace sat {
        \brief GC (the second) half of the clauses in the database.
     */
     void solver::gc_half(char const * st_name) {
-        TRACE("sat", tout << "gc\n";);
+        TRACE(sat, tout << "gc\n";);
         unsigned sz     = m_learned.size();
         unsigned new_sz = sz/2; // std::min(sz/2, m_clauses.size()*2);
         unsigned j      = new_sz;
@@ -192,7 +192,7 @@ namespace sat {
        \brief Use gc based on dynamic psm. Clauses are initially frozen.
     */
     void solver::gc_dyn_psm() {
-        TRACE("sat", tout << "gc\n";);
+        TRACE(sat, tout << "gc\n";);
         // To do gc at scope_lvl() > 0, I will need to use the reinitialization stack, or live with the fact
         // that I may miss some propagations for reactivated clauses.
         SASSERT(at_base_lvl());
@@ -213,7 +213,7 @@ namespace sat {
         double d_tk = V_tk == 0 ? static_cast<double>(num_vars() + 1) : static_cast<double>(h)/static_cast<double>(V_tk);
         if (d_tk < m_min_d_tk)
             m_min_d_tk = d_tk;
-        TRACE("sat_frozen", tout << "m_min_d_tk: " << m_min_d_tk << "\n";);
+        TRACE(sat_frozen, tout << "m_min_d_tk: " << m_min_d_tk << "\n";);
         unsigned frozen    = 0;
         unsigned deleted   = 0;
         unsigned activated = 0;
@@ -242,7 +242,7 @@ namespace sat {
                     c.unmark_used();
                     if (psm(c) > static_cast<unsigned>(c.size() * m_min_d_tk)) {
                         // move to frozen;
-                        TRACE("sat_frozen", tout << "freezing size: " << c.size() << " psm: " << psm(c) << " " << c << "\n";);
+                        TRACE(sat_frozen, tout << "freezing size: " << c.size() << " psm: " << psm(c) << " " << c << "\n";);
                         detach_clause(c);
                         c.reset_inact_rounds();
                         c.freeze();
@@ -284,7 +284,7 @@ namespace sat {
 
     // return true if should keep the clause, and false if we should delete it.
     bool solver::activate_frozen_clause(clause & c) {
-        TRACE("sat_gc", tout << "reactivating:\n" << c << "\n";);
+        TRACE(sat_gc, tout << "reactivating:\n" << c << "\n";);
         SASSERT(at_base_lvl());
         // do some cleanup
         unsigned sz = c.size();
@@ -304,7 +304,7 @@ namespace sat {
                 break;
             }
         }
-        TRACE("sat", tout << "after cleanup:\n" << mk_lits_pp(j, c.begin()) << "\n";);
+        TRACE(sat, tout << "after cleanup:\n" << mk_lits_pp(j, c.begin()) << "\n";);
         unsigned new_sz = j;
         switch (new_sz) {
         case 0: