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 1eqTfU-0001Ry-RB for pgsql-docs@arkaria.postgresql.org; Tue, 27 Feb 2018 01:02:57 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1eqTfS-0005gT-WA for pgsql-docs@arkaria.postgresql.org; Tue, 27 Feb 2018 01:02:54 +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 1eqTfS-0005eG-Hx for pgsql-docs@lists.postgresql.org; Tue, 27 Feb 2018 01:02:54 +0000 Received: from mail-vk0-x234.google.com ([2607:f8b0:400c:c05::234]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1eqTfG-0004rG-CU for pgsql-docs@lists.postgresql.org; Tue, 27 Feb 2018 01:02:53 +0000 Received: by mail-vk0-x234.google.com with SMTP id k187so11158335vke.12 for ; Mon, 26 Feb 2018 17:02:41 -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=9RoAmoKNPDXFUdSk+9DlcnCA6HN2D4vlqqFD8njlMaU=; b=JXc679JlTsolMHGmYLheRqFDcSfuiItXD6QXRnJaY+pEMiBul3n5/Jc9TaYXXCC9lR DGIEYB76TrskfUQ6zAwurdLx6yQW4YX1XlcNt8kmW29+bOJiDSwjQcgz3JvggueH87Fv j/2sbtZBwK94L/qpIOhCFEH+VgtTWRoPWQd6ta87BV4oc17oIrygX7WWRQ/80ITGT2CH upx9zSQ/6vs/Jy4py2WH9/jnzBVtBWwLqxEfWkViyJ1sqfZXGtL1rRWJSKNRrdAU3d2B xmC4R6OWWTf+cUwVQOMWgEp5/mjbqEeG28/Juaset2nx5kMhcsZonF9/L7toHoFnYtvC zlNg== 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=9RoAmoKNPDXFUdSk+9DlcnCA6HN2D4vlqqFD8njlMaU=; b=I+FdZcH7yeopYNzrNehWbpvjEuXrQRbKqwKTTibx8T8SDaCEnDdWpKdfhExOWy6l12 kybfgwlRqT+jGXJd51VV7pGOYv45m0xIkB+LY6WxIYDWhe7zKJNJ/5XdEmYpISQM/rt4 0Th2XGNzoDxK6Y6ID6zfoPupnVWiJPOieAjDeyAKK4Ar/sjWKvIbzeVflfpNDv20Bp1j Aa4FCN0noB+IEhvCPcZbcWvueFe7JTTj8pB+tgTHhBpI2H9SoJfTrt1PwKIvj21Qyr6v nJ+Ig2238psxE4Gg12QZ+FQgc1xwTsr5izScEiUJGQQMVcqocDyp4ljpxM5fsbHMcQO/ MCfw== X-Gm-Message-State: APf1xPAiOSw9qWHzA5jh6u4wuPIk3sR+x5iR2xCOZPFoKH/pctJUurxj mC4pSpL7z7m0FvqWaoZF//lD5Xh1RZQI7M0MqyRL1mllh6M= X-Google-Smtp-Source: AG47ELsTTtWXX0OwMSgRSbERGlC5p+RVJhIH4lt32ZYLPY2F3G29U7/WzIXaAoFa0r+JwWrk+CBwG6JHBUMS5pnQHKQ= X-Received: by 10.31.149.129 with SMTP id x123mr9175985vkd.196.1519693360917; Mon, 26 Feb 2018 17:02:40 -0800 (PST) MIME-Version: 1.0 Received: by 10.176.14.13 with HTTP; Mon, 26 Feb 2018 17:02:40 -0800 (PST) In-Reply-To: <323.1519672994@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> <323.1519672994@sss.pgh.pa.us> From: Craig Ringer Date: Tue, 27 Feb 2018 09:02:40 +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="001a114266a2f20dbe0566272ea8" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --001a114266a2f20dbe0566272ea8 Content-Type: text/plain; charset="UTF-8" On 27 February 2018 at 03:23, Tom Lane wrote: > Craig Ringer writes: > > On 26 February 2018 at 12:16, Tom Lane wrote: > >> 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? > > Well, I'll tell you exactly why I'm being sticky about this: we've been > down this road before. We used to have some figures in .gif format, > and one of the problems with them was they were too hard to update. > I don't buy the "they won't need updates" argument for a second, either. > For instance, I recall that one of the images we had was a diagram of > the system catalog cross-references, and it was constantly out of date > because of the difficulty of updating it. > Yeah, that sounds painful. I can certainly see your objection when framed in terms of things like illustrations of catalogs and catalog relationships. If I were maintaining the docs in a vacuum, I'd use graphviz for something like that, because it's a figure that does need regular updates and changes. And because the list of fun things to do in my life definitely does not include hand-writing SVG. Not that tweaking GraphViz .dot is fun, but it's the default tool for a reason. I'd be awfully tempted to generate the node-map part of the catalog relationship .dot file from a query, too. I still advocate for relaxing the policy for images that are *not* likely to need frequent updates, but also for being conservative about how/when we include images. Does this add real value to the docs, is it worth any maintenance hassle? Then, for things that will change more, like catalogs, using a tool like graphviz. If we object to adding a docs build-dependency, we could always commit generated files like we already do for the 'configure' script, and make sure there's a committer/maintainer Make target that warns if the sources are newer than the docs. -- Craig Ringer http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services --001a114266a2f20dbe0566272ea8 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On 2= 7 February 2018 at 03:23, Tom Lane <tgl@sss.pgh.pa.us> wrote= :
Craig Ringer <craig@2ndquadrant.com> writes: > On 26 February 2018 at 12:16, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> 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 t= he real world
> impact if we don't have it?

Well, I'll tell you exactly why I'm being sticky about this:= we've been
down this road before.=C2=A0 We used to have some figures in .gif format, and one of the problems with them was they were too hard to update.
I don't buy the "they won't need updates" argument for a = second, either.
For instance, I recall that one of the images we had was a diagram of
the system catalog cross-references, and it was constantly out of date
because of the difficulty of updating it.

Yeah, that sounds painful.=C2=A0I can certainl= y see your objection when framed in terms of things like illustrations of c= atalogs and catalog relationships.

If I wer= e maintaining the docs in a vacuum, I'd use graphviz for something like= that, because it's a figure that does need regular updates and changes= . And because
=C2=A0the list of fun things to do in my life defin= itely does not include hand-writing SVG. Not that tweaking GraphViz .dot is= fun, but it's the default tool for a reason.

= I'd be awfully tempted to generate the node-map part of the catalog rel= ationship .dot file from a query, too.

I still adv= ocate for relaxing the policy for images that are *not* likely to need freq= uent updates, but also for being conservative about how/when we include ima= ges. Does this add real value to the docs, is it worth any maintenance hass= le? Then, for things that will change more, like catalogs, using a tool lik= e graphviz. If we object to adding a docs build-dependency, we could always= commit generated files like we already do for the 'configure' scri= pt, and make sure there's a committer/maintainer Make target that warns= if the sources are newer than the docs.

--
<= div class=3D"gmail_signature" data-smartmail=3D"gmail_signature">
=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 Development, 24x7 Support, Tra= ining & Services
--001a114266a2f20dbe0566272ea8--