[lmi-commits] [lmi] master 0558d62 1/2: Clarify nomenclature

[Greg Chicares]

branch: master
commit 0558d62e29a13a52cb0f35c54e9e403aaeff2c84
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Clarify nomenclature
    
    Made the implementation easier to understand by distinguishing units:
    rows of data versus lines of printed output.
---
 ledger_pdf_generator_wx.cpp |  6 ++---
 miscellany.cpp              | 57 ++++++++++++++++++++++++++++++++++-----------
 miscellany.hpp              |  2 +-
 3 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/ledger_pdf_generator_wx.cpp b/ledger_pdf_generator_wx.cpp
index e885830..b616837 100644
--- a/ledger_pdf_generator_wx.cpp
+++ b/ledger_pdf_generator_wx.cpp
@@ -1775,11 +1775,11 @@ class page_with_tabular_report
             ,oe_only_measure
             );
 
-        int const rows_per_page = (get_footer_top() - pos_y) / 
table_gen.row_height();
+        int const lines_per_page = (get_footer_top() - pos_y) / 
table_gen.row_height();
 
         int const rows_per_group = wx_table_generator::rows_per_group;
 
-        if(rows_per_page < rows_per_group)
+        if(lines_per_page < rows_per_group)
             {
             // We can't afford to continue in this case as we can never output
             // the table as the template simply doesn't leave enough space for
@@ -1791,7 +1791,7 @@ class page_with_tabular_report
         return page_count
             (ledger.GetMaxLength()
             ,rows_per_group
-            ,rows_per_page
+            ,lines_per_page
             ) - 1;
     }
 };
diff --git a/miscellany.cpp b/miscellany.cpp
index e21af0d..4a530b1 100644
--- a/miscellany.cpp
+++ b/miscellany.cpp
@@ -292,45 +292,74 @@ std::string iso_8601_datestamp_terse()
     return s;
 }
 
-/// Compute the number of pages needed to display the given number of non-blank
-/// rows in groups of the specified size separated by blank rows.
+/// Number of pages needed to display the given number of data
+/// rows in groups of the given size separated by blank lines.
 ///
-/// Preconditions: 0 <= total_rows && 0 < rows_per_group <= rows_per_page
+/// Nomenclature:
+///  - a 'line' is a printable zone of unit height;
+///  - a 'row' is a series of data to be shown side by side.
+/// With quinquennial spacing, the Morse alphabet is printed thus:
+///
+///   A   .-     line  0   row  0
+///   B   -...   line  1   row  1
+///   C   -.-.   line  2   row  2
+///   D   -..    line  3   row  3
+///   E   .      line  4   row  4
+///   [blank]    line  5
+///   F   ..-.   line  6   row  5
+///   G   --.    line  7   row  6
+///   ...
+///   Z   --..   line 30   row 25
+///
+/// with a page length of 50 lines. With a page length of 25 lines,
+/// the first page would end with
+///   T   -      line 22   row 19
+/// and the second page would be printed thus:
+///
+///   U   ..-    line  0   row 20
+///   V   ...-   line  1   row 21
+///   W   .--    line  2   row 22
+///   X   -..-   line  3   row 23
+///   Y   -.--   line  4   row 24
+///   [blank]    line  5
+///   Z   --..   line  6   row 25
+///
+/// Preconditions: 0 <= total_rows && 0 < rows_per_group <= lines_per_page
 
 int page_count
     (int total_rows
     ,int rows_per_group
-    ,int rows_per_page
+    ,int lines_per_page
     )
 {
     LMI_ASSERT(0 <= total_rows);
-    LMI_ASSERT(0 <  rows_per_group                 );
-    LMI_ASSERT(     rows_per_group <= rows_per_page);
+    LMI_ASSERT(0 <  rows_per_group                  );
+    LMI_ASSERT(     rows_per_group <= lines_per_page);
 
     // If there are zero rows of data, then one empty page is wanted.
     if(0 == total_rows)
         return 1;
 
-    // Each group actually takes rows_per_group+1 rows because of the
+    // Each group actually takes rows_per_group+1 lines because of the
     // separator row between groups, hence the second +1, but there is no
     // need for the separator after the last group, hence the first +1.
-    int const groups_per_page = (rows_per_page + 1) / (rows_per_group + 1);
+    int const groups_per_page = (lines_per_page + 1) / (rows_per_group + 1);
 
     // But we are actually interested in the number of rows we can fit per page
     // and not the number of groups.
-    int const used_per_page = groups_per_page * rows_per_group;
+    int const rows_per_page = groups_per_page * rows_per_group;
 
     // Finally determine how many pages are needed to show all the rows.
-    int number_of_pages = outward_quotient(total_rows, used_per_page);
+    int number_of_pages = outward_quotient(total_rows, rows_per_page);
 
     // The last page may not be needed if all the rows on it can fit into the
     // remaining space, too small for a full group, but perhaps sufficient for
-    // these rows, in the last by one page.
+    // these rows, in the last page but one.
     if(1 < number_of_pages)
         {
-        auto const rows_on_last_page = total_rows - (number_of_pages - 1) * 
used_per_page;
-        auto const free_rows = rows_per_page - groups_per_page * 
(rows_per_group + 1);
-        if(rows_on_last_page <= free_rows)
+        auto const rows_on_last_page = total_rows - (number_of_pages - 1) * 
rows_per_page;
+        auto const free_lines = lines_per_page - groups_per_page * 
(rows_per_group + 1);
+        if(rows_on_last_page <= free_lines)
             {
             --number_of_pages;
             }
diff --git a/miscellany.hpp b/miscellany.hpp
index a8f14d5..69dc12b 100644
--- a/miscellany.hpp
+++ b/miscellany.hpp
@@ -202,7 +202,7 @@ inline unsigned char lmi_toupper(unsigned char c)
 int LMI_SO page_count
     (int total_rows
     ,int rows_per_group
-    ,int rows_per_page
+    ,int lines_per_page
     );
 
 /// DWISOTT