On 27 February 2018 at 03:23, Tom Lane <t...@sss.pgh.pa.us> wrote: > Craig Ringer <cr...@2ndquadrant.com> writes: > > On 26 February 2018 at 12:16, Tom Lane <t...@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. >
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
