Re: Images in the official documentation

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
>