Horton

Thread

Commits

  1. Doc: restructure documentation of the configure script's options.

  1. Can we bring some organization to the configure options list?

    Tom Lane <tgl@sss.pgh.pa.us> — 2019-06-07T14:22:49Z

    I was just noticing, while answering a user question, the amount of
unorganized urban sprawl we've accumulated in

https://www.postgresql.org/docs/devel/install-procedure.html

We've got practically-essential options like --prefix and
--with-openssl intermixed with obscure portability flags
and options that only developers should take any interest in.
For bonus points, the ordering seems chosen largely by dartboard;
there's certainly no visible plan to it.

I think we should try to improve the situation by dividing the
configure options into categories and/or separating commonly
used options from obscure ones.  I don't have any concrete
proposal to make right now, but I am hoping to kick off a
discussion about what such an organization would look like.

			regards, tom lane

  2. Re: Can we bring some organization to the configure options list?

    Tom Lane <tgl@sss.pgh.pa.us> — 2019-08-29T00:16:08Z

    I wrote:
> I was just noticing, while answering a user question, the amount of
> unorganized urban sprawl we've accumulated in
> https://www.postgresql.org/docs/devel/install-procedure.html
> We've got practically-essential options like --prefix and
> --with-openssl intermixed with obscure portability flags
> and options that only developers should take any interest in.
> For bonus points, the ordering seems chosen largely by dartboard;
> there's certainly no visible plan to it.
> I think we should try to improve the situation by dividing the
> configure options into categories and/or separating commonly
> used options from obscure ones.  I don't have any concrete
> proposal to make right now, but I am hoping to kick off a
> discussion about what such an organization would look like.

Hearing nothing but crickets, I took a stab at this myself,
ending up with a division into these categories:

Installation Locations
PostgreSQL Features
PostgreSQL Anti-Features
Build Process Details
Miscellaneous
Developer Options

plus a separate section for environment variables.

This seems to me to work fairly well, though surely it's not
the only way things could have been divided.  Except for the
"Features" section which contains many commonly-used options,
there's generally only one or two commonly-used options per
section, which I put first.  I also added a short para of
advice about which options to use, where it seemed helpful.

DocBook wasn't happy with putting <sectN> inside a
<procedure>'s step list, so I had to move all this stuff
out of the installation procedure's step list.  I'm not
sure whether I like that or not --- it does result in the
step list being fairly short and comprehensible, but the
info that you need to consult for the "configure" step is
now some distance away.  It's moot unless somebody knows
another way to do the markup, though.

Because of relocating and re-ordering the options, the diff
is just about unreadable :-(.  However, I mostly refrained
from changing the descriptions of individual options.
They're just ordered differently, and there is more text
around them.  I did yield to temptation in some small ways
though.

Comments?

			regards, tom lane