Re: Images in the official documentation

On 26 February 2018 at 12:16, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Craig Ringer <craig(at)2ndquadrant(dot)com> writes:
> > Yeah, I think it'd just effectively preserve the status quo by rendering
> > anyone who's willing to add images and designs to the docs unable - or
> > unlikely to be willing - to do so.
>
> This is an entirely reasonable complaint. But I don't see how we'd cope
> with patches that rewrite an entire SVG file because the patch author's
> WYSIWG editor emits its output in a style randomly different from the tool
> the previous patch author used. It seems like such patches would be
> effectively unreviewable, and certainly incapable of being merged.
>

Well, they definitely couldn't be merged in any situation entailing
conflicts, no.

Patch review would entail displaying the new and (if present) old SVGs,
possibly in the context of a build of the docs, or possibly standalone.

This is always going to be the case for anything but the most trivial SVG
changes anyway. After all, even small textual changes can cause elements to
overlap, break out of their expected bounaries, or otherwise look wrong.

So IMO whether it's SVG or a raster image format, the net effect isn't that
different: you have to review the rendered result not the source.
Personally I'd just mark svg as binary in .gitattributes to stop it from
spamming noise in diffs.

Github offers a cool tool for side-by-side compares of svg diffs (
https://github.com/blog/1902-svg-viewing-diffing) but that likely won't
help us much.

There's diffsvg (https://github.com/jrsmith3/diffsvg), which I haven't
tried but looks interesting. Combined with filters in .gitattributes this
might offer improved visibility into change history if we really need it.

Personally, I don't think images will be changing that often and they
should just be tracked as blobs.

> Maybe we could improve matters a bit by insisting that everyone use the
> same version of the same SVG-editing tool. But that's not too practical.
> Worse, from what I've seen, even that would not really fix the problem.
> The tools simply don't give a damn about comparability of their dump
> files. I don't blame their authors exactly (try diffing Postgres data
> file changes :-() but that doesn't mean it isn't a problem for us.
>
> How can we resolve these issues?
>

Question the assumptions and requirements. Why do we actually _need_
diffable, mergeable images? Sure, it'd be *nice*, but what's the real world
impact if we don't have it?

--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services