Re: Documentation for building with meson

Hi,

On 2023-03-28 12:27:26 -0700, samay sharma wrote:
> + <para>
> + If you want to build the docs, you can type:
> +<screen>
> +ninja docs
> +</screen>
> + </para>

To me 'you can type' sounds odd. To me even just "To build the docs:" would
sound better. But the make docs do it "your" way, so I'll just go along with
it for now.

> From c5e637a54c2b83e5bd8c4155784d97e82937eb51 Mon Sep 17 00:00:00 2001
> From: Samay Sharma <smilingsamay(at)gmail(dot)com>
> Date: Mon, 6 Feb 2023 16:09:42 -0800
> Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
> docs
>
> This commit separates out blocksize, segsize and wal_blocksize
> options into a separate Data layout options sub-section in both
> the make and meson docs. They were earlier in a miscellaneous
> section which included several unrelated options. This change
> also helps reduce the repetition of the warnings that changing
> these parameters breaks on-disk compatibility.

I still like this change, but ISTM that the "Data Layout" section should
follow the "PostgreSQL Features" section, rather than follow "Anti Features",
"Build Process Details" and "Miscellaneous". I realize some of these are
reorganized later on, but even then "Build Process Details"

Would anybody mind if I swapped these around?

> + <varlistentry id="meson-option-with-blocksize">

I don't quite understand the "-with" added to the ids?

> From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
> From: Samay Sharma <smilingsamay(at)gmail(dot)com>
> Date: Mon, 13 Feb 2023 16:23:52 -0800
> Subject: [PATCH v9 3/5] Remove Anti-Features section from Installation from
> source docs
>
> Currently, several meson setup options are listed in anti-features.
> However, they are similar to most other options in the postgres
> features list as they are 'auto' features themselves. Also, other
> options are likely better suited to the developer options section.
> This commit, therefore, moves the options listed in the anti-features
> section into other sections and removes that section.
> For consistency, this reorganization has been done on the make section
> of the docs as well.
> ---
> doc/src/sgml/installation.sgml | 140 ++++++++++++++-------------------
> 1 file changed, 57 insertions(+), 83 deletions(-)
>
> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
> index 7e65cdd72e..d7ab0c205e 100644
> --- a/doc/src/sgml/installation.sgml
> +++ b/doc/src/sgml/installation.sgml
> @@ -1214,23 +1214,6 @@ build-postgresql:
> </listitem>
> </varlistentry>
>
> - </variablelist>
> -
> - </sect3>
> -
> - <sect3 id="configure-options-anti-features">
> - <title>Anti-Features</title>
> -
> - <para>
> - The options described in this section allow disabling
> - certain <productname>PostgreSQL</productname> features that are built
> - by default, but which might need to be turned off if the required
> - software or system features are not available. Using these options is
> - not recommended unless really necessary.
> - </para>
> -
> - <variablelist>
> -
> <varlistentry id="configure-option-without-readline">
> <term><option>--without-readline</option></term>
> <listitem>

I don't think this is quite right. The section above the list says

"The options described in this section enable building of various PostgreSQL
features that are not built by default. Most of these are non-default only
because they require additional software, as described in Section 17.1."

So just merging --without-icu, --without-readline, --without-zlib,
--disable-thread-safety, in with the rest doesn't quite seem right.

I suspect that the easiest way for that is to just move --disable-atomics,
--disable-spinlocks to the developer section and then to leave the
anti-features section around for autoconf.

Any better idea?

Greetings,

Andres Freund