[CC += Michael Kerrisk] Hi Ingo,
On Thu, Jan 09, 2025 at 08:07:34PM +0100, Ingo Schwarze wrote:
> Hi,
>
> Alejandro Colomar wrote on Wed, Jan 08, 2025 at 09:32:25PM +0100:
>
> > So, let's break the line before the first parameter if it would overrun
> > the right margin (-rLL=NNn), and automagically calculate an appropriate
> > indentation for the first parameter.
>
> Sounds better, but still not like a fully thought-through analysis of the
> problem.
Ahh, yep, this is why I didn't propose that in the first place, and
ended up requesting a manual indentation parameter. I keep forgetting
things while I write. :p
On the other hand, I'm not sure how many cases there are where that
happens. I need to check (once I finish transforming function
prototypes to use SY --in a development branch; don't worry about it
yet--).
> For example, it's not necessarily the first argument that is
> long. Consider this real-world example from an actual manual page:
>
> void
> SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
> void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
I have a few similar cases in the Linux man-pages project. I'm
currently using this style:
void
SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
typeof(void (SSL_CTX *ctx, SSL_SESSION *))
*remove_session_cb);
I found that using typeof() with function pointer arguments makes it
easier to have a nice alignment.
>
> By the way, in mdoc(7), writing that is totally straightforward
> for documentation author:
>
> .Ft void
> .Fo SSL_CTX_sess_set_remove_cb
> .Fa "SSL_CTX *ctx"
> .Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)"
> .Fc
>
> The mdoc(7) language automatically breaks the line before the long
> argument, even though it's the second one, and proceed with an
> indentation of 4n.
>
> > As for the right indentation, I'd make it the exact indentation that
> > would make the first parameter touch the right margin,
>
> Probably, simply always using 4n would look better and more uniform.
> With flush-right, you might get very large indentations that look
> weird. Besides, KISS! - especially considering that name+argument
> overflow is an unusual edge case in the first place.
Hmmm, I personally use this style when programming. I use tabs in code,
but in function prototypes, I use 4 spaces for line continuation. I
find it more readable in source code.
<https://github.com/shadow-maint/shadow/blob/master/lib/string/sprintf/stpeprintf.h>
However, I'm not sure if I'd like in in manual pages, though. There's a
lot of bold, and it would make stuff too packed, I think. In mdoc(7),
you use significantly less BI in the SYNOPSIS section, which makes it
less of a problem. In source code, since usually there's syntax
highlighting with a lot of colors, each color is less crowded, and my
brain copes good with it. Bold + 4n is a problematic combination, IMO.
> Also, while indentation conventions vary among projects (for example,
> BSD uses 8n tabs for statements and 4n for continuations of the same
> statement on the next line, whereas groff source code tends to use 2n
> troughout IIUC), using flush-right in source code formatting feels
> very unusual to me.
>
> > with a minimum indentation of 2n (being such a rare case, I'd hardcode
> > this value; it shouldn't be hit under normal conditions).
>
> If you really want to make the indentation variable in this special
> case of name+argument overrun (rather than just using 4n), then
> constraining it in the range from 2n to 8n inclusive would make
> sense to me because i would consider tab settings outside that
> range highly unusual in any source code formatting convention.
Hmmm, sounds good. 8n is decent for avoiding a packed left-hand side.
>
> Yours,
> Ingo
Have a lovely night!
Alex
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
