Re: FDW API / flow charts for the docs?

On 17 Říjen 2013, 5:32, Stephen Frost wrote:
> Alvaro,
>
> * Alvaro Herrera (alvherre(at)2ndquadrant(dot)com) wrote:
>> Tomas Vondra wrote:
>> > Attached is the set of flow charts, showing the sequence of callbacks
>> > for all the supported commands (i.e. SELECT, INSERT, UPDATE, DELETE,
>> > ANALYZE). Wouldn't it be useful to put something like this into the
>> > docs? I mean, the FDW API is not going to get any simpler, and for me
>> > this was a significant help.
>>
>> Please see this thread
>> http://www.postgresql.org/message-id/4BB9E69F.9080203@usit.uio.no
>
> The conclusion of that thread appears to be "use dia", which was done
> here.. Am I missing something there (full disclosure- I haven't looked
> at the dia yet)?

My impression from that thread was that one of the requirements is
reasonable versioning / diff support, and AFAIK that's not a good match
for any GUI-based product. So while I like dia and I used it for drawing
the charts I submitted today, I don't think it works with this (quite
reasonable) requirement.

The only tool that might be a good match is graphviz (also mentioned in
that thread). It's text-based, widely available and quite customizable.
I'm not a graphviz expert, but attached is a result of 5-minute work with
graphviz. Not perfect, but I'm pretty sure we could get much better /
nicer results in very short time.

It's easy to edit by hand, do versioning and /or diff on that, etc. I
doubt there's a better option available.

> Also, for my part, I'd suggest putting it on the wiki initially anyway,
> as then it can be seen directly (load it as a png or what-have-you) and
> it becomes immediately available to users. The .dia should also be on
> the wiki, of course, and then included in the PG tree eventually if it's
> added as part of the official docs.

No problem with that, but I'd like to know in advance if we're willing to
put that into the docs / under what requirements etc. Otherwise it might
result in a major effort just to get it from wiki into docs later.

Tomas