Re: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters

Joseph Myers
2022-12-06T02:08:30Z

On Sat, 3 Dec 2022, Alejandro Colomar via Gcc wrote:

> What do you think about it? I'm not asking for your opinion about adding it
> to GCC, but rather for replacing the current '.' in the man-pages before I
> release later this month. Do you think I should apply that change?

I think man pages should not use any novel syntax - even syntax newly
added to the C standard or GCC, unless required to express the standard
prototype for a function. They should be written for maximal
comprehensibility to C users in general, who are often behind on knowledge
standard features let alone the more obscure extensions - and certainly
don't know about random, highly speculative suggestions for possible
features suggested in random mailing list threads. So: don't use any
invented syntax (even if you explain it somewhere in the man pages), don't
use any syntax newly introduced in C23 unless strictly necessary and
you're sure it's already extremely widely understood among C users, be
wary of syntax introduced in C11. If a new feature in this area were
introduced in C29, waiting at least several years after that standard is
released (*not* just after the feature gets added to a draft) to start
using the new syntax in man pages would be a good idea.

--
Joseph S. Myers
joseph@codesourcery.com