Re: Poll: are people okay with function/operator table redesign?

Alvaro Herrera <alvherre@2ndquadrant.com>

From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Bruce Momjian <bruce@momjian.us>, Peter Eisentraut <peter.eisentraut@2ndquadrant.com>, Robert Haas <robertmhaas@gmail.com>, Steven Pousty <steve.pousty@gmail.com>, Pavel Stehule <pavel.stehule@gmail.com>, Isaac Morland <isaac.morland@gmail.com>, Pierre Giraud <pierre.giraud@dalibo.com>, PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Date: 2020-04-23T17:43:43Z
Lists: pgsql-hackers
If we're doing nicer markup+CSS for this, then it might make sense to
find a better solution for this kind of entry with multiple signatures
(which was already an issue in the previous version):

text || anynonarray or anynonarray || text → text
	Converts the non-string input to text, then concatenates the two
	strings. (The non-string input cannot be of an array type, because that
	would create ambiguity with the array || operators. If you want to
	concatenate an array's text equivalent, cast it to text explicitly.)
	'Value: ' || 42 → Value: 42

I think it would make sense to split the first line to put each of the
two signatures on their own line.  So it would look like this:

text || anynonarray
anynonarray || text → text
	Converts the non-string input to text, then concatenates the two
	strings. (The non-string input cannot be of an array type, because that
	would create ambiguity with the array || operators. If you want to
	concatenate an array's text equivalent, cast it to text explicitly.)
	'Value: ' || 42 → Value: 42


Another example:

to_ascii ( string text [, encoding name or integer ] ) → text

should be (I think):

to_ascii ( string text [, encoding name ] ) → text
to_ascii ( string text [, integer ] ) → text


-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services



Commits

  1. Doc: re-re-revise markup for tables of functions.

  2. Doc: revise formatting of function/operator tables.