On Thu, Apr 18, 2024 at 2:37 AM Dagfinn Ilmari Mannsåker <ilm...@ilmari.org> wrote: > > Andres Freund <and...@anarazel.de> writes: > > > Hi, > > > > On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Mannsåker wrote: > >> Andres Freund <and...@anarazel.de> 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 <optional> > >> tags for optional parameters, others use square brackets, and some use > >> <literal>VARIADIC</literal> to indicate variadic parameters, others use > >> ellipses (sometimes in <optional> 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. >
hi. I manually checked the html output. It looks good to me.
