MIME-Version: 1.0
Reply-To: obartunov@gmail.com
In-Reply-To: <323.1519672994@sss.pgh.pa.us>
References: <1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com>
 <ff69cb83-9f90-4967-7de7-629bdfaa0c75@purtz.de>
 <08B83F11-EB17-4436-B73A-1857898B6B9B@blighty.com>
 <CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>
 <22981.1519618609@sss.pgh.pa.us>
 <CAMsr+YGE8PU4THTTEXk4YkbfkZQrU32JJYojJzhQaKkZUKfXAQ@mail.gmail.com>
 <323.1519672994@sss.pgh.pa.us>
From: Oleg Bartunov <obartunov@gmail.com>
Date: Tue, 27 Feb 2018 11:52:45 +0300
Message-ID: 
 <CAF4Au4ySVu8y0MP-D1Jfrpi1B_cmdqNjBazq-76tVRAh47GJ-Q@mail.gmail.com>
Subject: Re: Images in the official documentation
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Craig Ringer <craig@2ndquadrant.com>, Steve Atkins <steve@blighty.com>,
	pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Mon, Feb 26, 2018 at 10:23 PM, 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 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.
>
> Admittedly, this was 15+ years ago.  Maybe the state of the art in
> figure editors has advanced to the point where it won't be so hard.
> But color me suspicious.


In case you missed, a couple of years ago we discussed this on pgcon:

Heikki's version:
https://wiki.postgresql.org/wiki/Figures_%26_Pics_in_Docs

Emre suggested to use Markdeep (BSD license),
http://casual-effects.com/markdeep/
http://www.sai.msu.su/~megera/postgres/gin-ascii-v2.md.html

It looks good for small diagrams, but will not work for complex stuff,
such as pg_catalog structure.


>
>                         regards, tom lane
>