Better visualization of default values

On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Reading DOCs sometimes is boring because you want to know only the default value of something. I know what that GUC is, I know how to change it, I only don't remember what its default value is. Then you have to read that entire paragraph just to read that the default value is ...

So, what you think about this.
It's not complete but you can see if it's useful or not

+0.5

IIUC the problem here (if there is one), is just that the default is
sometimes buried within the GUC description.

But just putting the default value adjacent to the GUC name might not
be the best solution because often defaults have special meanings.
e.g. there is no point knowing the default value is -1 unless you know
what that value means. So with your patch, not only is the default
value duplicated, but you are back where you started having to read
all the description text again to learn what it means.

IMO it would be better simply to ensure that defaults are always
described in a consistent place within all GUC descriptions, Then they
are easy to find because you always know where to look for them. In
other words, add nothing new -- just slightly rearrange and/or add
blank lines to the existing text.

Like this:

<guc-name> (type)
<one line terse description>
<default value, and optional special meaning>
<more details, if any>

For example:

CURRENTLY
vacuum_cost_delay (floating point)

The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. The default value is 0, which disables the cost-based
vacuum delay feature. Positive values enable cost-based vacuuming.

When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, perhaps less than 1
millisecond. While vacuum_cost_delay can be set to
fractional-millisecond values, such delays may not be measured
accurately on older platforms. On such platforms, increasing VACUUM's
throttled resource consumption above what you get at 1ms will require
changing the other vacuum cost parameters. You should, nonetheless,
keep vacuum_cost_delay as small as your platform will consistently
measure; large delays are not helpful.

SUGGESTION
vacuum_cost_delay (floating point)

The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. Positive values enable cost-based vacuuming.

The default value is 0, which disables the cost-based vacuum delay feature.

When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, ... blah blah

~~~

Thoughts?

======
Kind Regards,
Peter Smith.
Fujitsu Australia

I agree that duplicating default values is not fine, I can remove them from
the explanation and put it only near definition.

But about adding a new line with its default value, sometimes is fine,
sometimes not.
[1]: https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-RANDOM-PAGE-COST
ones cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost and so on
wouldn't be good.

And obviously, if you don't know the purpose of that GUC, you'll have to
read the entire paragraph to understand it.
Objective here is to those ones who know what it is, but don't remember its
default.

[1]: https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-RANDOM-PAGE-COST
https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-RANDOM-PAGE-COST

regards
Marcos

Em qua., 5 de fev. de 2025 às 20:59, Peter Smith <smithpb2250@gmail.com>
escreveu:

On Thu, Feb 6, 2025 at 6:46 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

And obviously, if you don't know the purpose of that GUC, you'll have to
read the entire paragraph to understand it.
Objective here is to those ones who know what it is, but don't
remember its default.

That seems a somewhat arbitrary goal for us to optimize for. I just read
through https://www.postgresql.org/docs/current/runtime-config-query.html
and while perhaps some of the defaults could be slightly more prominent,
none of them took more than a second of brain-cpu-power to find. The only
one that threw me off was join_collapse_limit, which really should just
state the eight. So for me a -1 for major changes, but a weak +1 to
improving some individual items.

Cheers,
Greg

--
Crunchy Data - https://www.crunchydata.com
Enterprise Postgres Software Products & Tech Support

On Thu, Feb 6, 2025 at 4:46 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Objective here is to those ones who know what it is, but don't
remember its default.

My approach would be to add a summary table (or tables) in the first
subsection of each major X.Y (section X.Y.1) that lists the name, brief
description, type, default value, and notes. Then just leave the full
descriptions self-contained as they are. Pure redundancy but basically put
the output of a psql meta-command directly into the docs.

Between these other two choices I'd lean toward placing the default only
next to the data type.

David J.

Em qui., 6 de fev. de 2025 às 12:32, Greg Sabino Mullane <htamfids@gmail.com>
escreveu:

That seems a somewhat arbitrary goal for us to optimize for.

well, my goal was to standardize these values. As examples of
non standardization you have ...

"The default is typically 100 connections".
Tipically ? Is it 100 or not the default for it ?

"The default value is three connections" or "The default is one thousand
files"
Why three and not 3 or why thousand and not 1000 ?

Sometimes "an empty string", sometimes "empty", sometimes ''.

Sometimes "If this parameter is off (the default)", "Default is off",
"Default value is off"

So, if we move all them to the definition of that GUC they would be written
the same way, just that.

regards
Marcos

On Thu, Feb 6, 2025 at 10:46 PM Marcos Pegoraro <marcos@f10.com.br> wrote:

I agree that duplicating default values is not fine, I can remove them from the explanation and put it only near definition.

But about adding a new line with its default value, sometimes is fine, sometimes not.
[1] is a good example which would be fine but the next ones cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost and so on wouldn't be good.

And obviously, if you don't know the purpose of that GUC, you'll have to read the entire paragraph to understand it.
Objective here is to those ones who know what it is, but don't remember its default.

If you feel a blank line preceding the default in the description is
sometimes inappropriate then forget that; just ensure the default
information is consistently *last* in the GUC short description
paragraph.

Like this:

<guc-name> (type)
<short description><default value>
<more details, if any>

Then.
- No duplicated info
- Locating the default info is effortless (the $SUBJECT goal) because
they are always found in the same place.
- Many descriptions are using this format already (e.g.
cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost etc) so there
is nothing to do for these.

~~~

+1 to your second goal of wanting to use consistent wording [1]/messages/by-id/CAB-JLwa1BwESd_OJZftOeaw4dSCg29rd1nhc3gLwYZ1N8yxwrw@mail.gmail.com

======
[1]: /messages/by-id/CAB-JLwa1BwESd_OJZftOeaw4dSCg29rd1nhc3gLwYZ1N8yxwrw@mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

Marcos Pegoraro писал(а) 2025-02-06 04:07:

Reading DOCs sometimes is boring because you want to know only the
default value of something. I know what that GUC is, I know how to
change it, I only don't remember what its default value is. Then you
have to read that entire paragraph just to read that the default value
is ...

So, what you think about this.
It's not complete but you can see if it's useful or not

regards
Marcos

Hi
It looks helpful.
+1 from me.
--
Best regards,

Vladlen Popolitov.

Well, I don't know if you like it, but here it is.

What I'm trying to do here is put some standard on how variables are
described, because they have lots of ways they are described.
What way is better is to be discussed but I think they are confused because
they were written at different times by different people.
The explaining part sometimes starts with default value, sometimes default
is the last thing, sometimes it doesn't exist at all.
Additionally there is no explanation about read only variables.

These are examples explaining these different ways of writing:

No default value
- restrict_nonsystem_relation_kind
- local_preload_libraries, session_preload_libraries and
shared_preload_libraries
- gin_fuzzy_search_limit
- quote_all_identifiers
- data_checksums
- num_os_semaphores
- archive_mode
- archive_timeout
- restore_command
Default value is written twice
- transform_null_equals
Values written in different ways
- '' vs empty string
- one thousand files vs 1000 files
- The default is five transactions vs The default is five minutes
(<literal>5min</literal>).
- The default value is <literal>10.0</literal> vs The default value is 100
buffers
- 128 megabytes vs 128MB vs two megabytes
- If this parameter is off (the default) vs Default is off
- The default is zero (<literal>0</literal>) vs The default value is
<literal>0</literal>
- <literal>-1</literal> (the default) means vs A value of zero (the
default) disables

regards
Marcos