INSTALLATION
-------------

You need ImageMagic installed.    apt install imagemagick

Check this if imagemagick policy prevent PDF generation
https://stackoverflow.com/questions/52998331/imagemagick-security-policy-pdf-blocking-conversion

FONT DIFFERENCES
----------------

Due to slight differences in PDF -> PNG conversion on different platforms,
the "difference images" may show a lot of highlighted pixels, especially on
rendered text.

To get around this problem, first make sure that the differences reported
by the tool are really only marginal font-rendering shifts. Then create
your own set of reference images with the following command:

$ ./testrender.py --create-reference <REFDIR>

This will create a new set of reference PNGs rendered with your font engine
to the directory <REFDIR>. ATTENTION: the directory you specify here will be
deleted and recreated!

After the images haven been created, you can use your reference dir for
your test renderings:

$ ./testrender.py --ref-dir <REFDIR>


BROWSER COMPARISON
------------------

testrender.py compares xhtml2pdf against itself: the reference is produced by
the same library, so it catches changes in the output but never tells you
whether that output is right.

browsercompare.py adds an external reference. Each case has two sources that
express the same intended result:

    data/source/<name>.html     fed to xhtml2pdf; may use <pdf:*>, @frame, -pdf-*
    data/browser/<name>.html    fed to a browser; plain HTML and CSS

xhtml2pdf-only constructs are written with ordinary markup on the browser side:
@frame becomes absolute positioning, <pdf:toc> a hand-written list,
<pdf:pagenumber> a counter() in an @page margin box. data/manifest.toml says
which fixtures participate and what is compared for each.

Both sides are printed to PDF with the same page geometry, rasterised by the
same ghostscript, then compared on pagination, per-page text, and SSIM. Scores
land in data/baseline.json and a run fails when one regresses.

    pip install -e '.[browsertest]'      # selenium + numpy
    make test-browser                    # compare and check the baseline
    make test-browser-update             # re-record the baseline
    x-www-browser testrender/output/browser-compare.html

The browser runs headless, so no window appears. Use --headed to watch it while
debugging an equivalent that does not line up.

Two things the comparison depends on, and why the baseline is machine specific:

  * The browser version. It is the reference, so a browser upgrade moves the
    scores without xhtml2pdf changing. browsercompare.py refuses to enforce a
    baseline recorded with a different build, and says so.

  * The fonts. xhtml2pdf uses ReportLab's base-14; the browser uses whatever
    fontconfig resolves. The comparison only works well when Helvetica resolves
    to a metric-compatible clone such as URW Nimbus Sans (Debian/Ubuntu package
    fonts-urw-base35). Without it, line breaking diverges and every score drops.

Absolute scores are not meaningful on their own -- two different engines never
agree exactly. What matters is that the agreement does not get worse.


KNOWN DIFFERENCES FOUND BY THE BROWSER COMPARISON
-------------------------------------------------

Divergences the comparison has surfaced that are not yet resolved. Each is
recorded in data/manifest.toml against the fixture that shows it, so the score
is explained rather than mysterious.

  * text-decoration: overline is not drawn. Underline and strike each carry
    their own accumulator and drawing pass through
    xhtml2pdf/reportlab_paragraph.py, and overline needs a third. Shown by
    css-text.

  * list-style-type: circle draws a filled bullet. No font in the base-14 set
    has a hollow circle, and a list marker must not depend on an embedded font
    being present. Shown by css-list-style.

  * list-style-position is not implemented; every marker is drawn outside the
    box. Shown by css-list-style.

  * The first line of a block sits a little higher than a browser puts it.
    CSS centres the font's content area inside the line box, so half of the
    leading falls above the first line; ReportLab starts the ascent at the top
    of the box instead. Worth about 4pt at a 10px font with 150% line height,
    the same on every block, so it does not accumulate.

  * A table with no column widths gets equal columns, where a browser sizes
    each column to its content, so the table comes out wider. As a block it
    also takes the whole frame width rather than shrink-wrapping. Shown by
    test-tables, and inherited by flex-item-content, whose flex item is only
    as wide as the table it holds.

  * Arabic letters are joined by substituting presentation forms, because
    ReportLab does no shaping of its own. A font built for OpenType shaping
    carries the plain Arabic block and few or no presentation forms, and the
    letters are then left unjoined rather than replaced by boxes -- readable,
    but not what the browser draws. Shown by arabic_font_rendering, which is
    why it does not compare SSIM.

A trap that is not a difference, because a browser does the same thing: a
<div> inside a <p> is not allowed, and the HTML parser closes the paragraph
and lifts the <div> out of every inline element around it. A flex container
written as <p>... <span style="display:flex"><div>a</div></span> ...</p>
therefore ends up empty, and a descendant selector rooted at anything outside
it stops matching, because the items are no longer inside it. Chrome's DOM
agrees element for element. Use inline children -- spans -- for a flex row
that lives in a paragraph. inline-block-nested and inline-flex-workaround both
had this and were comparing two identically-restructured documents.
