Re: New developer papercut - Makefile references INSTALL

Hi,

On 2022-01-21 17:25:08 -0500, Tom Lane wrote:
> Andres Freund <andres(at)anarazel(dot)de> writes:
> > It seems quite workable to continue for INSTALL to be generated, but have the
> > result checked in. The rate of changes to {installation,install-windows}.sgml
> > isn't that high, and when things change, it's actually useful to be able to
> > see the current instructions from a console.
> > Might even be good to be forced to see the text version of INSTALL when
> > changing the sgml docs...
>
> Not sure about that, because
>
> (1) if done wrong, it'd make it impossible to commit into the
> docs unless you have a working docs toolchain on your machine,
> whether you wanted to touch installation.sgml or not;

Hm, do we really want committers do that at any frequency? I think that
concern makes sense for contributors, but I think it's reasonable to expect
the docs to be built before committing changes.

It might be relevant that the dependencies for INSTALL generation are
considerably smaller than for a full docs build. It needs xsltproc, xmllint
and pandoc. Not tiny, but still a lot less than the full docbook toolchain.

On a debian container with just enough stuff installed to get through
./configure --without-readline --without-zlib (to minimize things installed
from another source):

apt-get install -y xsltproc libxml2-utils pandoc
...
The following NEW packages will be installed:
libcmark-gfm-extensions0 libcmark-gfm0 libicu67 libxml2 libxml2-utils libxslt1.1 pandoc pandoc-data xsltproc
0 upgraded, 9 newly installed, 0 to remove and 0 not upgraded.
Need to get 28.8 MB of archives.
After this operation, 193 MB of additional disk space will be used.

Re committers, the biggest issue would presumably be working on windows :(. I
don't think the docs build is integrated into the msvc tooling right now.

> (2) we'd inevitably get a lot of diff noise because of different
> committers having different versions of the docs toolchain.
> (Unlike configure, trying to require uniformity of those tools
> seems quite impractical.)

Fair point, no idea how big that aspect is. I'd expect xsltproc to be halfway
OK in that regard, and it's certainly not changing much anymore. Pandoc, I
have no idea.

> Perhaps this could be finessed by making updating of INSTALL
> the responsibility of some post-commit hook on the git server.
> Not sure that we want to go there, though. In any case, that
> approach would negate your point about seeing the results.

It would. I guess it'd still be better than the situation today, but...

Greetings,

Andres Freund