[groff] 16/20: [tbl]: Add roff comments to generated output.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a2d598c9b8af88c775b26972f0ad9b4719a36671
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Feb 3 12:10:04 2023 -0600

    [tbl]: Add roff comments to generated output.
    
    * src/preproc/tbl/table.cpp (table::compute_total_separation)
      (table::compute_separation_factor, table::compute_widths): Add
      comments to generated roff output to assist the mystified user.
    
    Also annotate source code.
---
 ChangeLog                 | 6 ++++++
 src/preproc/tbl/table.cpp | 7 +++++--
 src/preproc/tbl/table.h   | 4 ++--
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b3b8325bd..2fe3537ca 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2023-02-03  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * src/preproc/tbl/table.cpp (table::compute_total_separation)
+       (table::compute_separation_factor, table::compute_widths): Add
+       comments to generated roff output to assist the mystified user.
+
 2023-02-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [tbl]: Refactor.
diff --git a/src/preproc/tbl/table.cpp b/src/preproc/tbl/table.cpp
index 82c51afb2..cf25ea913 100644
--- a/src/preproc/tbl/table.cpp
+++ b/src/preproc/tbl/table.cpp
@@ -2260,6 +2260,7 @@ void table::compute_total_separation()
 
 void table::compute_separation_factor()
 {
+  prints(".\\\" compute column separation factor\n");
   // Don't let the separation factor be negative.
   prints(".nr " SEPARATION_FACTOR_REG " \\n[.l]-\\n[.i]");
   for (int i = 0; i < ncolumns; i++)
@@ -2297,13 +2298,15 @@ void table::compute_separation_factor()
 
 void table::compute_column_positions()
 {
+  prints(".\\\" compute column positions\n");
   printfs(".nr %1 0\n", column_divide_reg(0));
   printfs(".nr %1 %2*\\n[" SEPARATION_FACTOR_REG "]\n",
          column_start_reg(0),
          as_string(left_separation));
+  // In nroff mode, compensate for width of vertical rule.
   if (left_separation)
     printfs(".if n .nr %1 +1n\n", column_start_reg(0));
-  int i;
+  int i; // needed after loop
   for (i = 1;; i++) {
     printfs(".nr %1 \\n[%2]+\\n[%3]\n",
            column_end_reg(i-1),
@@ -2357,7 +2360,7 @@ void table::make_columns_equal()
 
 void table::compute_widths()
 {
-  prints(".\\\" compute widths\n");
+  prints(".\\\" compute column widths\n");
   build_span_list();
   int i;
   horizontal_span *p;
diff --git a/src/preproc/tbl/table.h b/src/preproc/tbl/table.h
index bac0979c9..be6dc4450 100644
--- a/src/preproc/tbl/table.h
+++ b/src/preproc/tbl/table.h
@@ -97,8 +97,8 @@ class table {
   string *minimum_width;
   int *column_separation;
   char *equal;
-  int left_separation;
-  int right_separation;
+  int left_separation; // from a vertical rule or box border, in ens
+  int right_separation; // from a vertical rule or box border, in ens
   int total_separation;
   int allocated_rows;
   void build_span_list();