Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,17 @@ follow semantic versioning; release dates are ISO 8601.

### Public API

- **A DOCX export names a border Word draws at another width than the page, and writes a text
header's or footer's separator of no width.** A Word border is no thinner than a quarter of a
point and no wider than twelve, and the export held a border to that without a word: a panel's
20pt border, a table cell's or a row's, was written 12pt wide, a 0.1pt hairline a quarter of a
point, a rule as thin and a separator as thin or as wide. Each is now named (`border width`),
once for a panel, a table and a rule, and once for a separator however many headers it is
written into. A separator of no width, which the page strokes as the thinnest line a screen or
a printer shows, was not written; it is drawn at Word's thinnest and named, and counts as Word
draws it where the export decides whether a band reaches past the page margin. One set below
zero, or not a number, is named as not written. A width that rounds to an eighth Word draws —
0.2pt to a quarter of a point — is drawn at it, unnamed.
- **A DOCX export says why a drawing is not in it and what a section with no layout leaves to
the editor, names the application that made it, gives every table a grid, and names an anchor
in a repeated table header.** Without the layout — a document the engine refused, or a bare
Expand Down
8 changes: 4 additions & 4 deletions docs/architecture/backend-capability-matrix.md

Large diffs are not rendered by default.

10 changes: 8 additions & 2 deletions docs/recipes/docx-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -544,7 +544,9 @@ How it lands:
sets it; above, then, the room over its first line. What none of them takes stands the
content, or the block below, that much lower, and the report names it: on the panel for its
top border, on the block below for its bottom one (`space above`). A panel's border is
written from two to ninety-six eighths of a point, as a table cell's rule is. A shape container's
written from two to ninety-six eighths of a point, as a table cell's rule and a rule are: a
width that, rounded to the eighth Word counts in, is thinner than a quarter of a point or
wider than twelve is drawn at Word's thinnest or widest, and named (`border width`). A shape container's
borders, its layers centred in it, stay inside its outline, which its row holds less them as
wide as Word draws them, two and a half twips an eighth of a point rounded down (measured:
taken off at the 0.7pt the page strokes, a 20.3pt chip whose border Word draws 0.75pt wide
Expand Down Expand Up @@ -1179,7 +1181,11 @@ fields, and `{date}` is the date of the export, as the page prints the date
it was rendered. Its separator is the paragraph's border, and the line
stands as far from the page edge as the page sets the text — its baseline
within 0.1pt, its separator within 0.6pt (measured in LibreOffice at 7, 9
and 12pt). A band that shares its kind with another band or a page zone — an
and 12pt). The separator's width is held to Word's range, as a panel's border
is, and named where it falls outside it (`border width`); one
of no width, which the page strokes as the thinnest
line a screen or a printer shows, is drawn at Word's thinnest, a quarter of
a point, and named, and one set below zero is named and not written. A band that shares its kind with another band or a page zone — an
invoice's legal lines and its page number — stands in a frame at its own
height on the page, since one after another in the footer they would keep
the order they were added in rather than the page's order by height. A
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
package com.demcha.compose.document.backend.semantic.docx;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.TreeSet;
import java.util.stream.Collectors;

/**
* How wide Word draws a border, and which of the widths the page strokes it does not draw.
*
* <p>A Word border's width is its {@code w:sz}, in eighths of a point, and a line border's runs
* from two to ninety-six (ECMA-376): no border Word draws is thinner than a quarter of a point
* or wider than twelve. The page strokes a border at the width it is given, so a panel's 20pt
* border is drawn 12pt wide and a 0.1pt hairline a quarter of a point, and the report names
* each; a width that rounds to an eighth Word draws is drawn at that eighth, unnamed.</p>
*
* @author Artem Demchyshyn
*/
final class DocxBorderWidths {

/** Word's thinnest border, in eighths of a point. */
static final long THINNEST = 2;

/** Word's widest, in eighths of a point. */
static final long WIDEST = 96;

private DocxBorderWidths() {
}

/**
* A border's width as {@code w:sz}: eighths of a point, held from Word's thinnest to its
* widest.
*
* @param points the width the page strokes it at
* @return the eighths written
*/
static long eighths(double points) {
return Math.max(THINNEST, Math.min(WIDEST, Math.round(points * 8)));
}

/**
* What a note says of borders Word draws at another width than the page strokes them, or
* {@code null} where it draws each in the eighth of a point nearest the page's.
*
* @param what what the borders are, as "its borders" or "the rule"
* @param plural whether {@code what} names more than one
* @param widths the widths the page strokes them at, in points, each above zero
* @return the note's text, or {@code null}
*/
static String notHeld(String what, boolean plural, Collection<Double> widths) {
TreeSet<Double> thinner = new TreeSet<>();
TreeSet<Double> wider = new TreeSet<>();
for (double width : widths) {
long eighths = Math.round(width * 8);
if (eighths < THINNEST) {
thinner.add(width);
} else if (eighths > WIDEST) {
wider.add(width);
}
}
if (thinner.isEmpty() && wider.isEmpty()) {
return null;
}
String them = plural ? "them" : "it";
List<String> drawn = new ArrayList<>(2);
if (!thinner.isEmpty()) {
drawn.add(pointsOf(THINNEST / 8.0) + "pt wide where the page strokes " + them + " " + listed(thinner));
}
if (!wider.isEmpty()) {
drawn.add(pointsOf(WIDEST / 8.0) + "pt wide where the page strokes " + them + " " + listed(wider));
}
return what + (plural ? " are" : " is") + " drawn " + String.join(", and ", drawn)
+ ": a Word border is no thinner than " + pointsOf(THINNEST / 8.0) + "pt and no wider than "
+ pointsOf(WIDEST / 8.0) + "pt";
}

/**
* What a note says of a border the page strokes at no width, which it draws as the thinnest
* line a screen or a printer shows (a line width of 0, in PDF).
*
* @param what what the border is, as "a page header's separator"
* @return the note's text
*/
static String ofNoWidth(String what) {
return what + ", which the page strokes 0pt wide, the thinnest line a screen or a printer shows, is "
+ "drawn " + pointsOf(THINNEST / 8.0) + "pt wide: a Word border is no thinner";
}

/** Widths as a note lists them: "0.1pt", "0.05pt and 0.1pt". */
private static String listed(TreeSet<Double> widths) {
List<String> each = widths.stream().map(width -> pointsOf(width) + "pt").collect(Collectors.toList());
if (each.size() == 1) {
return each.get(0);
}
return String.join(", ", each.subList(0, each.size() - 1)) + " and " + each.get(each.size() - 1);
}

/** A width to the thousandth of a point, with no trailing zeros: a hairline is no tenth of one. */
private static String pointsOf(double points) {
return BigDecimal.valueOf(Math.round(points * 1000) / 1000.0).stripTrailingZeros().toPlainString();
}
}
Loading
Loading