Skip to content

Fix table guide dot generation and layout - #179

Merged
krperry merged 3 commits into
mainfrom
fix/table-guide-dots
Oct 19, 2026
Merged

krperry merged 3 commits into
mainfrom
fix/table-guide-dots

Conversation

@krperry

@krperry krperry commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Fixes three guide dot problems in simple tables, checked against
Braille Formats 2016, section 11. There is one commit per fix, and
each commit has its own regression tests in
SimpleTableGuideDotsTest. The tests format real BBX documents to
BRF and check the table lines.

1. Single guide dots (9b05ad4)

Problem: In Example 11-3, a single guide dot followed "bore" and
"began" in the Past column. Formats 11.6.1.f calls for two or more.

Cause: PageBuilder.fillSpace filled whatever cells were left
after the entry, minus one blank on each side. A three-cell gap
therefore got one dot. Its minimum argument is never used.

Fix: fillSpace takes an optional minimumFillers (default 1, so
existing callers are unchanged). The simple table formatter passes
MIN_GUIDE_DOTS = 2 for non-empty entries. When only one dot fits,
nothing is drawn and column positions stay the same. Blank-entry fills
and the TOC are unchanged.

Tests: Example 11-3, plus a table whose entries leave room for 0,
1, 2 and 3 dots.

2. Guide dots on multiline entries (9606905)

Problem: In Sample 11-4, "20 ac/ territory" and "1 ac/ territory"
wrap, but guide dots were drawn after "20 ac/" and "1 ac/".

Cause: addRow added guide dots to every column but the last. For
columns after the first, it placed them on the entry's first line,
whether or not the entry ran over. Formats 11.6.1.g says not to use
guide dots after a column runover other than the first column.

Fix: After placing an entry, addRow checks whether the formatted
entry ended on a later line than it started. If so, it skips guide
dots for that entry. Row heading runovers still get guide dots after
their last line (11.5.2.b).

Tests: Sample 11-4 (both entries, with "Variable" keeping its
dots). A single-line entry with dots in a 17-cell column. The same
entry with no dots once a 10-cell column makes it wrap.

3. Unnecessary guide dots and column sizing (56913ac)

Problem: In the weather table, every High Temp. and Low Temp.
entry had a stray guide dot, and "East Village" took three lines.

Cause: calculateColumnWidths shrinks short columns and then
hands the leftover cells, one at a time, to every column whose content
is still longer than the starting width. A column's content includes
its column heading. Each temperature column took a cell because its
heading is 10–11 cells long, though its entries are 7 cells and the
heading wraps anyway. That spare cell is where the stray dot went. The
first column, whose entries really do run over, got only one extra
cell.

Fix: Leftover space now goes first to columns whose entries (not
column headings) are longer than the column, then to the other
columns as before. The column widths change from 9/9/9/5 to 11/8/8/5.
The temperatures have no guide dots, "East Village" and "Woodland
Hills" take two lines, and "Highland Park" fits on one line. The
change has no effect on tables with no leftover space or no runover
entries. Example 11-3 and Sample 11-4 come out the same as before this
commit.

Tests: The test checks the whole weather table layout.

Testing

  • mvnw package (full reactor with tests): BUILD SUCCESS. utd ran
    702 tests and brailleblaster-core ran its default suite, both with
    0 failures. The core suite includes the 6 new tests.
  • Each new test was run against the code before its fix: every
    regression test failed there, except the eligible single-line entry
    check, which guards against over-suppression and passes both before
    and after.
  • Tests were run locally on Windows only.

Notes

  • The three .bbx fixtures come from the reported .bbz files.
  • I could read the Formats section 11 rules (11.5.2.b, 11.6.1.f and
    11.6.1.g), but not the braille images for Example 11-3 and Sample
    11-4. The expected output in the tests is BrailleBlaster's corrected
    output, checked against those rules, not compared cell by cell with
    the printed samples.
  • Not changed here: in Sample 11-4, "Williamson's" is split with the
    continuation indicator (,williamson" / 's) because the column is
    too narrow for the runover.

Braille Formats 11.6.1.f calls for two or more guide dots between
columns. The simple table formatter filled whatever space was left
after an entry, so a column with only three free cells (one blank on
each side) got a single dot, as after "bore" and "began" in Example
11-3.

PageBuilder.fillSpace takes an optional minimum filler count, and the
simple table formatter now asks for at least two dots on non-empty
entries. When only one would fit, nothing is written and the column
positions are unchanged. Blank-entry fills and the TOC are unchanged.

The new tests format Example 11-3 and a table whose entries leave
room for zero, one, two and three guide dots.
Braille Formats 11.6.1.g says not to put guide dots after a column
runover other than the first column, since the runover does not lead
to the next column. The simple table formatter added guide dots to
every column but the last and drew them on the entry's first line, so
"20 ac/ territory" and "1 ac/ territory" in Sample 11-4 got dots after
"20 ac/" and "1 ac/".

addRow now checks whether the entry it just placed ended on a later
line than it started, which is the actual formatted output for the
current column width, and skips guide dots for that entry. Row
heading runovers keep their guide dots after the last line
(11.5.2.b).

Tests cover Sample 11-4, a single-line entry that keeps its guide
dots, and one entry that gets guide dots in a 17-cell column but none
once a 10-cell column makes it run over.
calculateColumnWidths shrinks short columns to fit their content and
then hands the leftover cells, one at a time, to every column whose
content is still longer than the starting width. A column's length
includes its column heading, so in the weather table the "High Temp."
and "Low Temp." columns each took a cell because of their headings,
even though their entries are only seven cells and the headings wrap
either way. The extra cell left room for a stray guide dot after
every temperature, and the row heading column, whose entries do run
over, got only one extra cell, so "East Village" took three lines.

Leftover space now goes first to columns whose entries (not the
column heading) are longer than the column, and only then to the
other columns as before. In the weather table the first column grows
from 9 to 11 cells and the temperature columns stay at 8, so the
temperatures have no guide dots, "East Village" and "Woodland Hills"
take two lines and "Highland Park" fits on one. Tables with no
leftover space or no runover entries are laid out as before.

The test formats the table and checks the whole layout.
@krperry
krperry merged commit 9311f89 into main Oct 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant