Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1rxAAB-006kOp-7V for pgsql-hackers@arkaria.postgresql.org; Wed, 17 Apr 2024 18:37:44 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1rxAA8-00EajB-D6 for pgsql-hackers@arkaria.postgresql.org; Wed, 17 Apr 2024 18:37:40 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1rxAA6-00EaiE-SD for pgsql-hackers@lists.postgresql.org; Wed, 17 Apr 2024 18:37:40 +0000 Received: from wfhigh6-smtp.messagingengine.com ([64.147.123.157]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1rxA9y-001VHC-12 for pgsql-hackers@postgresql.org; Wed, 17 Apr 2024 18:37:38 +0000 Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailfhigh.west.internal (Postfix) with ESMTP id 5A1DF180018B; Wed, 17 Apr 2024 14:37:25 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute5.internal (MEProxy); Wed, 17 Apr 2024 14:37:25 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ilmari.org; h=cc :cc:content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm2; t=1713379044; x=1713465444; bh=XC/aKT2oYQ MDFBfxZkcYj9uCdciA6Bw6zXYU18L3Ssk=; b=WqOoRR/7sPYM0UtdSb2tWwWVNz JxrIryx0l5VCGoguKvRd4w2MJn8y1ou2x1jTeJyeoZ73YFDF+WkdjTcuY/DkgzSr jr/GImLZRBZhHXszvyKKrT7olGCDQwlRg+KXI0sItphYndwoZtH32VzWe+2ijL6r syVnlKXpzdFd9czQFdM9snP0b/xpmhI5IY1gAsJiazAhjP8/zMD0Z7KnCGAHzj0w cA6tBpFm7deC4Q9kRVaqazy/yO29owEyWrmxUoDaMolftcAWPHwItbYD+AI2qoAe gPUbPFhLvxWde1+tfp1pFwoEFx2U4x28ykev2irnQfHg7K+dsa/Dxt3+pHoQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1713379044; x=1713465444; bh=XC/aKT2oYQMDFBfxZkcYj9uCdciA 6Bw6zXYU18L3Ssk=; b=HzmTw3r2Mpl4Cyq/GisJgcx+z/wfrRvDfXotKRPBE2m5 dev0zNVccxjsIcHdSuosIP1PhPYv649vVXOddsLxLba8lsiiv0MVMKJx/eMFr/Jq rMrySAdW8Kgyd4Q4a2DhDdrgY3xvCkMbOpDRx5W4HCEWqvAJiZyvAEdVoh8Sgoan rS/b60tDfc8vAVhq2GJ/eIisTwGsWvlJGeyOxxArUyIo+jEGJaigd2+rADyPlrhF zLFFc4OJ7RGXYaoZrLBocQYOxRzQkjlcaxZ52fP1px980PoGRULYHUO+S4kQzJXq WkohM4PCGPO/QUg4PwMrwe1EgwUP3xW5XSs+lYBJhg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvledrudejkedguddvjecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpefhvfevufhfffgjkfgfgggtsehmtderredtreejnecuhfhrohhmpeffrghg fhhinhhnucfklhhmrghrihcuofgrnhhnshonkhgvrhcuoehilhhmrghrihesihhlmhgrrh hirdhorhhgqeenucggtffrrghtthgvrhhnpedvvdfhhedtfeekudfgtedufeehgffggeej ieejheeugfethefggedtleegteetjeenucevlhhushhtvghrufhiiigvpedtnecurfgrrh grmhepmhgrihhlfhhrohhmpehilhhmrghrihesihhlmhgrrhhirdhorhhg X-ME-Proxy: Feedback-ID: i1ff147bf:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Wed, 17 Apr 2024 14:37:23 -0400 (EDT) From: =?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= To: Andres Freund Cc: Tom Lane , Andrew Dunstan , Robert Haas , "pgsql-hackers@postgresql.org" Subject: Re: documentation structure References: <20240416182310.2j6g5fqqcwi4s6wm@awork3.anarazel.de> <1355791.1713294332@sss.pgh.pa.us> <20240416201700.wyz7ojp3fr7222xt@awork3.anarazel.de> <87v84gi6xf.fsf@wibble.ilmari.org> <20240417172803.3xzcipouw74unuen@awork3.anarazel.de> Date: Wed, 17 Apr 2024 19:37:21 +0100 In-Reply-To: <20240417172803.3xzcipouw74unuen@awork3.anarazel.de> (Andres Freund's message of "Wed, 17 Apr 2024 10:28:03 -0700") Message-ID: <87sezjj0ny.fsf@wibble.ilmari.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Andres Freund writes: > Hi, > > On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Mannsåker wrote: >> Andres Freund writes: >> > I think the manual work for writing signatures in sgml is not insignificant, >> > nor is the volume of sgml for them. Manually maintaining the signatures makes >> > it impractical to significantly improve the presentation - which I don't think >> > is all that great today. >> >> And it's very inconsistent. For example, some functions use >> tags for optional parameters, others use square brackets, and some use >> VARIADIC to indicate variadic parameters, others use >> ellipses (sometimes in tags or brackets). > > That seems almost inevitably the outcome of many people having to manually > infer the recommended semantics, for writing something boring but nontrivial, > from a 30k line file. As Corey mentioned elsethread, having a markup style guide (maybe a comment at the top of the file?) would be nice. >> > And the lack of argument names in the pg_proc entries is occasionally fairly >> > annoying, because a \df+ doesn't provide enough information to use functions. >> >> I was also annoyed by this the other day (specifically wrt. the boolean >> arguments to pg_ls_dir), > > My bane is regexp_match et al, I have given up on remembering the argument > order. There's a thread elsewhere about those specifically, but I can't be bothered to find the link right now. >> and started whipping up a Perl script to parse func.sgml and generate >> missing proargnames values for pg_proc.dat, which is how I discovered the >> above. > > Nice. > >> The script currently has a pile of hacky regexes to cope with that, >> so I'd be happy to submit a doc patch to turn it into actual markup to get >> rid of that, if people think that's a worhtwhile use of time and won't clash >> with any other plans for the documentation. > > I guess it's a bit hard to say without knowing how voluminious the changes > would be. If we end up rewriting the whole file the tradeoff is less clear > than if it's a dozen inconsistent entries. It turned out to not be that many that used [] for optional parameters, see the attached patch. I havent dealt with variadic yet, since the two styles are visually different, not just markup (... renders as [...]). The two styles for variadic are the what I call caller-style: concat ( val1 "any" [, val2 "any" [, ...] ] ) format(formatstr text [, formatarg "any" [, ...] ]) which shows more clearly how you'd call it, versus definition-style: num_nonnulls ( VARIADIC "any" ) jsonb_extract_path ( from_json jsonb, VARIADIC path_elems text[] ) which matches the CREATE FUNCTION statement. I don't have a strong opinion on which we should use, but we should be consistent. > Greetings, > > Andres Freund - ilmari --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-func.sgml-Consistently-use-optional-to-indicate-opti.patch From f71e0669eb25b205bd5065f15657ba6d749261f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= Date: Wed, 17 Apr 2024 16:00:52 +0100 Subject: [PATCH] func.sgml: Consistently use to indicate optional parameters Some functions were using square brackets instead. --- doc/src/sgml/func.sgml | 54 +++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 8dfb42ad4d..afaaf61d69 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -3036,7 +3036,7 @@ concat concat ( val1 "any" - [, val2 "any" [, ...] ] ) + , val2 "any" [, ...] ) text @@ -3056,7 +3056,7 @@ concat_ws ( sep text, val1 "any" - [, val2 "any" [, ...] ] ) + , val2 "any" [, ...] ) text @@ -3076,7 +3076,7 @@ format format ( formatstr text - [, formatarg "any" [, ...] ] ) + , formatarg "any" [, ...] ) text @@ -3170,7 +3170,7 @@ parse_ident parse_ident ( qualified_identifier text - [, strict_mode boolean DEFAULT true ] ) + , strict_mode boolean DEFAULT true ) text[] @@ -3309,8 +3309,8 @@ regexp_count regexp_count ( string text, pattern text - [, start integer - [, flags text ] ] ) + , start integer + , flags text ) integer @@ -3331,11 +3331,11 @@ regexp_instr regexp_instr ( string text, pattern text - [, start integer - [, N integer - [, endoption integer - [, flags text - [, subexpr integer ] ] ] ] ] ) + , start integer + , N integer + , endoption integer + , flags text + , subexpr integer ) integer @@ -3360,7 +3360,7 @@ regexp_like regexp_like ( string text, pattern text - [, flags text ] ) + , flags text ) boolean @@ -3380,7 +3380,7 @@ regexp_match - regexp_match ( string text, pattern text [, flags text ] ) + regexp_match ( string text, pattern text , flags text ) text[] @@ -3400,7 +3400,7 @@ regexp_matches - regexp_matches ( string text, pattern text [, flags text ] ) + regexp_matches ( string text, pattern text , flags text ) setof text[] @@ -3426,8 +3426,8 @@ regexp_replace regexp_replace ( string text, pattern text, replacement text - [, start integer ] - [, flags text ] ) + , start integer + , flags text ) text @@ -3447,7 +3447,7 @@ regexp_replace ( string text, pattern text, replacement text, start integer, N integer - [, flags text ] ) + , flags text ) text @@ -3467,7 +3467,7 @@ regexp_split_to_array - regexp_split_to_array ( string text, pattern text [, flags text ] ) + regexp_split_to_array ( string text, pattern text , flags text ) text[] @@ -3486,7 +3486,7 @@ regexp_split_to_table - regexp_split_to_table ( string text, pattern text [, flags text ] ) + regexp_split_to_table ( string text, pattern text , flags text ) setof text @@ -3510,10 +3510,10 @@ regexp_substr regexp_substr ( string text, pattern text - [, start integer - [, N integer - [, flags text - [, subexpr integer ] ] ] ] ) + , start integer + , N integer + , flags text + , subexpr integer ) text @@ -3980,7 +3980,7 @@ -format(formatstr text [, formatarg "any" [, ...] ]) +format(formatstr text , formatarg "any" [, ...] ) formatstr is a format string that specifies how the result should be formatted. Text in the format string is copied @@ -10568,7 +10568,7 @@ -date_trunc(field, source [, time_zone ]) +date_trunc(field, source , time_zone ) source is a value expression of type timestamp, timestamp with time zone, @@ -29308,11 +29308,11 @@ pg_logical_emit_message - pg_logical_emit_message ( transactional boolean, prefix text, content text [, flush boolean DEFAULT false] ) + pg_logical_emit_message ( transactional boolean, prefix text, content text , flush boolean DEFAULT false ) pg_lsn - pg_logical_emit_message ( transactional boolean, prefix text, content bytea [, flush boolean DEFAULT false] ) + pg_logical_emit_message ( transactional boolean, prefix text, content bytea , flush boolean DEFAULT false ) pg_lsn -- 2.39.2 --=-=-=--