MultiXactId concept underdocumented

Hi,

On 2013-08-07 21:25:06 -0400, Peter Eisentraut wrote:

The new MultiXactId concept appears in a number of user-facing error
messages, including in the scary context of transaction ID wraparound,
so it seems kind of important, but it doesn't appear to be documented in
any user-facing places. Should this be rectified? Maybe some of the
material from README.tuplock should be moved to the user manual. Maybe
a less jargony term could be found as well.

Multixacts aren't really new, they've been there since 8.1 or so. It's
just that their use has been a bit expanded and that their internal
format changed a bit.

WRT user facing messages: I think it'd suffice to explain the
anti-wraparound part of the docs that the same holds true for
multixacts. Doing a more detailed explanation seems to require a good
amount of low level explanations and thus seems unlikely to be actually
read.

Greetings,

Andres Freund

--
Andres Freund http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Peter Eisentraut <peter_e@gmx.net> writes:

The new MultiXactId concept appears in a number of user-facing error
messages, including in the scary context of transaction ID wraparound,
so it seems kind of important, but it doesn't appear to be documented in
any user-facing places. Should this be rectified? Maybe some of the
material from README.tuplock should be moved to the user manual. Maybe
a less jargony term could be found as well.

In some other Open Source Product Documentations, I've found it very
useful to have a "Glossary" chapter, e.g.

http://www.gnu.org/software/emacs/manual/html_node/emacs/Glossary.html#Glossary

I think we should consider doing that, mainly copy/pasting definitions
we already have here and there at the beginning of chapters and
sections, and maintain a full Glossary of the technical terms in use
within our product and that you must understand to be able to use it,
either as a developer or a dba or a sysadmin.

Regards,
--
Dimitri Fontaine
http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers