Finding your way through a long document / Abbreviations list
An abbreviations list in columns that reads down, not across
Short forms with their expansions, usually at the front of a technical document, set compactly because there are often a lot of them.
Why this block is harder than it looks
An abbreviations list is glossary-shaped but much shorter per entry, so a single-column layout wastes most of the page width and a fifty-item list runs to two pages when it should run to half of one. The obvious fix is columns, and columns introduce the problem the glossary does not have: CSS columns fill top to bottom and then across, which is correct for reading, but people frequently build the list as a grid instead, which fills across and then down, and an alphabetical list that reads across is unusable.
The decisions that make it work
Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.
- Use CSS columns rather than a grid, so the list fills down each column and then moves across, which is the order an alphabetical list has to be read in.
- Set column-fill: auto so the last column is short rather than balancing all columns into equal fragments that break the alphabetical run.
- Keep each entry unbreakable with break-inside: avoid so an abbreviation is never separated from its expansion by a column break.
- Align the abbreviations in a narrow fixed column within each entry, the same hanging-indent principle as a glossary.
- Set the abbreviations in the monospace face where they contain digits or mixed case, so similar-looking short forms are distinguishable.
- Two or three columns, not four. At four the expansion column is too narrow and every entry wraps, which costs more height than the extra column saves.
The fragment
Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.
<dl class="abbrevs">
<div class="entry"><dt>BT</dt><dd>Business term</dd></div>
<div class="entry"><dt>BG</dt><dd>Business group</dd></div>
<div class="entry"><dt>CII</dt><dd>Cross Industry Invoice</dd></div>
<div class="entry"><dt>UBL</dt><dd>Universal Business Language</dd></div>
</dl>
<style>
.abbrevs {
columns: 3;
column-gap: 8mm;
column-fill: auto; /* fills down, then across */
margin: 0;
font-size: 8.5pt;
}
.abbrevs .entry {
display: grid;
grid-template-columns: 16mm 1fr;
gap: 3mm;
break-inside: avoid; /* never split a term from its expansion */
margin-bottom: 2.5pt;
align-items: start;
}
.abbrevs dt {
font-family: "IBM Plex Mono", ui-monospace, monospace;
font-weight: 600;
}
.abbrevs dd { margin: 0; line-height: 1.35; }
</style>What breaks when it is built the obvious way
Building it as a three-column grid. A grid fills left to right, so an alphabetical list reads A, B, C across the first row and D, E, F across the second, and finding a term means scanning the whole block instead of one column.
How to prove it survived pagination
Render thirty entries in alphabetical order and read down the first column. It should run A through to roughly the middle of the alphabet before the second column starts. If the first row reads A, B, C across, it is a grid and it needs to be columns.
Where it sits in a finished document
This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The product datasheet template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.
Frequently asked
Will this fragment work on its own?
Not as a whole document. It has no page rule, no margins and no base type, because those belong to the document rather than to the block, and duplicating them in every fragment would mean thirty copies to keep in step. Paste it into a template that already has them.
Why does it look right in a browser and wrong in the PDF?
Because a browser window is one continuous surface and a document is a stack of fixed rectangles. Nothing in a scrolling view exercises a page boundary, so every break rule in the fragment is inert until the content is paginated. Render the real thing with enough content to cross two or three boundaries, then look.
Do I need a special option on the render request for this?
No. Everything on this page is CSS and markup, which is your side of the boundary. What the render has to give you is a real page size with real margins, and after that the layout is decided by the stylesheet.
Other parts of a document
The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.
A document control block with owner, status and review date
Owner, status, issue date, review date and reference, gathered into one block near the front of a controlled document.
A distribution list showing who received which copy
Names, roles and copy numbers of everyone the document was issued to, printed so a recipient can see who else has it.
A back cover that ends the document rather than trailing off
A final page carrying contact details, a document reference and nothing else, so a reader can tell the document has ended.
A margin note aligned to the paragraph it belongs to
A short note set in the outer margin beside the text it refers to, used for cross-references, dates and editorial comments.
Product datasheet, as a complete file
The whole document with this block already in place, ready to copy and change.
column-count in paged output
The property carrying the weight here, with its real support status.
Every part of a document
The full list, grouped by the kind of problem the block poses.
Paste the fragment into the playground inside a page rule and see what it does at a real page size. That is the only way any of this gets confirmed.