MIME-Version: 1.0
References: <CA+TgmoZ2F+K0j=6BOJLD=YfpJMdJRXC7sWmtXGRjx1Rq0x8PUA@mail.gmail.com>
 <CAD5tBcJUVQu=9zpr9C+Z=3SjxrECURtr_i1oipMqke4dpZXtyQ@mail.gmail.com>
 <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> <87sezjj0ny.fsf@wibble.ilmari.org>
In-Reply-To: <87sezjj0ny.fsf@wibble.ilmari.org>
From: jian he <jian.universality@gmail.com>
Date: Thu, 18 Apr 2024 21:28:00 +0800
Message-ID: <CACJufxEOwG2xMBky4Ga2ttSkF95GOkbcWyH7w+7NoDnaRvjoGQ@mail.gmail.com>
Subject: Re: documentation structure
To: =?UTF-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org>
Cc: Andres Freund <andres@anarazel.de>, Tom Lane <tgl@sss.pgh.pa.us>, 
	Andrew Dunstan <andrew@dunslane.net>, Robert Haas <robertmhaas@gmail.com>, 
	"pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CACJufxEOwG2xMBky4Ga2ttSkF95GOkbcWyH7w%2B7NoDnaRvjoGQ%40mail.gmail.com>
Precedence: bulk

On Thu, Apr 18, 2024 at 2:37=E2=80=AFAM Dagfinn Ilmari Manns=C3=A5ker
<ilmari@ilmari.org> wrote:
>
> Andres Freund <andres@anarazel.de> writes:
>
> > Hi,
> >
> > On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Manns=C3=A5ker wrote:
> >> Andres Freund <andres@anarazel.de> writes:
> >> > I think the manual work for writing signatures in sgml is not insign=
ificant,
> >> > nor is the volume of sgml for them. Manually maintaining the signatu=
res makes
> >> > it impractical to significantly improve the presentation - which I d=
on'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 us=
e
> >> ellipses (sometimes in <optional> tags or brackets).
> >
> > That seems almost inevitably the outcome of many people having to manua=
lly
> > infer the recommended semantics, for writing something boring but nontr=
ivial,
> > 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 occasionall=
y fairly
> >> > annoying, because a \df+ doesn't provide enough information to use f=
unctions.
> >>
> >> I was also annoyed by this the other day (specifically wrt. the boolea=
n
> >> arguments to pg_ls_dir),
> >
> > My bane is regexp_match et al, I have given up on remembering the argum=
ent
> > 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 chan=
ges
> > would be. If we end up rewriting the whole file the tradeoff is less cl=
ear
> > 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.