Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1eqCJ6-00059f-Kg for pgsql-docs@arkaria.postgresql.org; Mon, 26 Feb 2018 06:30:40 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1eqCJ5-0007Sn-Im for pgsql-docs@arkaria.postgresql.org; Mon, 26 Feb 2018 06:30:39 +0000 Received: from makus.postgresql.org ([2001:4800:1501:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1eqCJ5-0007Sc-68 for pgsql-docs@lists.postgresql.org; Mon, 26 Feb 2018 06:30:39 +0000 Received: from mail-ua0-x22c.google.com ([2607:f8b0:400c:c08::22c]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1eqCJ1-0006Fq-40 for pgsql-docs@lists.postgresql.org; Mon, 26 Feb 2018 06:30:37 +0000 Received: by mail-ua0-x22c.google.com with SMTP id e25so1306053uam.6 for ; Sun, 25 Feb 2018 22:30:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=2ndquadrant-com.20150623.gappssmtp.com; s=20150623; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=CcmL1NvnHWyYd47b0UZ6H3X0VJgifkuZ6wn10RUldaw=; b=BCBE0FKfjshAy4f0JtJDOyPyFIsYzholXWmOlbLl33chEFVQujsjfQ5NzON5vOsZ9c 9WcMCgzTq935Bc01Bpk+0J1iVPAiT4pBwk3TJH2FrDbpbFOlsF4kr6RRWgUpR4E3IZJs UgWCCidpDZA53Cht0GFLYTb1n4LzCTdZwKLIQyZaN+nvAdRnE/gDO22TF9an/xL7aTxI yNwS38GVj1r6TSuE6VQSMSAbxP/7yPuGPVI6oDmVydLjczR2ateAZrjynuiBX3xcqoPC kr3Uu7mPLxtO/DsNWAeknunEBGMD9xem+5MVCqGJrfBTCQSSIWUJu0GUMow7Kn7PFeIa C10w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=CcmL1NvnHWyYd47b0UZ6H3X0VJgifkuZ6wn10RUldaw=; b=KHsy2emHsBwhOb8lh9F9Np65g0O8iu+7Dkp8YeSCBw/6T2K+PqacLcl+H9mi5RZ9Vh EdM1Fvzv5VOv0Ed6kRtqQcCVyl1FruejJTlqokgh/e/9wfYK4+57WvHMYba4LY3FK4HI alcVcZKF7pldB50BA9J111Z88Wl9XS8hJiwdFS9lmsSKSYf+PDbgNO4P4c7xDFgrkXPN Vs7ZRMedW5DjxjTaWGOSSX+3rnDmy9XPmv2Ms/poYqzzm2XKY/Tk0YJqhSEVRAhULifO 0regadkhvUJSZ/pz25y5K8h0tKWECxqM3fcTnaQz6xpKIbprkNQ3A6eJFF3qVJmQ0sfo HORQ== X-Gm-Message-State: APf1xPAi2JIyneO0n8oWYakpJVxk0o+0jGJxWXWDNKto4fCmGJ0VfcXr kWZE0uURI7YR94wDnQtX5A87WwMsCmu6buoYHmu4gA== X-Google-Smtp-Source: AG47ELsA7xRuh0Ze0Z0ZrtdPzvYPKCdjfACMKXXHqiO/CRXj01Dqhstvn60X0fmEwvEERuCnxS3HX1AdVzF1kKGr2PA= X-Received: by 10.159.33.2 with SMTP id 2mr7282178uab.71.1519626632341; Sun, 25 Feb 2018 22:30:32 -0800 (PST) MIME-Version: 1.0 Received: by 10.176.14.13 with HTTP; Sun, 25 Feb 2018 22:30:31 -0800 (PST) In-Reply-To: <22981.1519618609@sss.pgh.pa.us> References: <1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com> <08B83F11-EB17-4436-B73A-1857898B6B9B@blighty.com> <22981.1519618609@sss.pgh.pa.us> From: Craig Ringer Date: Mon, 26 Feb 2018 14:30:31 +0800 Message-ID: Subject: Re: Images in the official documentation To: Tom Lane Cc: Steve Atkins , pgsql-docs@lists.postgresql.org Content-Type: multipart/alternative; boundary="001a114fefce9cc8a9056617a583" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --001a114fefce9cc8a9056617a583 Content-Type: text/plain; charset="UTF-8" On 26 February 2018 at 12:16, Tom Lane wrote: > Craig Ringer 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 --001a114fefce9cc8a9056617a583 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On 2= 6 February 2018 at 12:16, Tom Lane <tgl@sss.pgh.pa.us> wrote= :
Craig Ringer <craig@2ndquadr= ant.com> writes:=C2=A0
> Yeah, I think it'd just effectively preserve the status quo by ren= dering
> 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.=C2=A0 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<= br> the previous patch author used.=C2=A0 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 revi= ew would entail displaying the new and (if present) old SVGs, possibly in t= he context of a build of the docs, or possibly standalone.

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

So IMO whether it's SVG or a raster ima= ge 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 m= uch.

There's diffsvg (https://github.com/jrsmith3/diffsvg), which I h= aven't tried but looks interesting. Combined with filters in .gitattrib= utes 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.

=C2=A0
Maybe we could improve matters a bit by insisting that everyone use the<= br> same version of the same SVG-editing tool.=C2=A0 But that's not too pra= ctical.
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.=C2=A0 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.<= br>
How can we resolve these issues?

Questi= on the assumptions and requirements. Why do we actually _need_ diffable, me= rgeable images? Sure, it'd be *nice*, but what's the real world imp= act if we don't have it?

--
=C2=A0Craig Ringer= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 http://www.2ndQuadrant.com/
=C2=A0PostgreSQL Develo= pment, 24x7 Support, Training & Services
--001a114fefce9cc8a9056617a583--