Hi Branden, On Sun, May 05, 2024 at 04:11:21PM +0200, Alejandro Colomar wrote: > > Thanks for giving it some field testing. groff's own man pages aren't > > the best test bed because I've revised nearly all of them so extensively > > that they don't do things I wouldn't anticipate. > > > > > - Hardcoded line widths have an interesting feature: the author > > > decides the breaking point, which is interesting to highlight > > > differences between similar functions. See for example printf(3): > > > > > > int printf(const char *restrict format, ...); > > > int fprintf(FILE *restrict stream, > > > const char *restrict format, ...); > > > int dprintf(int fd, > > > const char *restrict format, ...); > > > int sprintf(char *restrict str, > > > const char *restrict format, ...); > > > int snprintf(char str[restrict .size], size_t size, > > > const char *restrict format, ...); > > > > > > As you can see, the breaking point clearly shows the differences > > > between all of those, and leaves the common part in a separate > > > line. > > > > Yes. You could still use the `br` request to force a break here. `SY` > > and `YS` should not interfere. groff and mandoc do discourage the use > > of *roff requests, but in frankness no one will ever be able to get away > > with not supporting `br`. And at least its semantics are very obvious > > and easy to implement in just about any text formatting system. > > Hmmm, I hadn't considered .br. That changes things. > > > > Still, this is not the common case, and most pages would benefit of > > > this SY. I'm just mentioning here to note that old hard-coded BI > > > still has its place in some pages. I will probably never use SY in > > > printf(3). > > > > Awww. Too bad. I think a lot of aspiring page authors would look > > there, because the function is so familiar, and they might wonder how to > > do the variadic thing. > > With .br I think I retire my previous statement. I'll test it when I > finish some other stuff I'm working on.
I found one of the pages where I'm not sure how to handle it:
dl_iterate_phdr(3).
So far, I'm considering this:
diff --git i/man/man3/dl_iterate_phdr.3 w/man/man3/dl_iterate_phdr.3
index 8f80f20c9..48e60b4ab 100644
--- i/man/man3/dl_iterate_phdr.3
+++ w/man/man3/dl_iterate_phdr.3
@@ -13,12 +13,18 @@ .SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <link.h>
-.P
-.B int dl_iterate_phdr(
-.BI " typeof(int (struct dl_phdr_info *" info ", size_t " size ", void
*" data ))
-.BI " *" callback ,
-.BI " void *" data );
.fi
+.P
+.B int
+.br
+.SY dl_iterate_phdr(
+.br
+.BI typeof(int\~(struct\~dl_phdr_info\~* info ,\~size_t\~ size ,\~void\~* data
))
+.br
+.BI \~\~\~\~* callback ,
+.br
+.BI void\~* data );
+.YS
.SH DESCRIPTION
The
.BR dl_iterate_phdr ()
which results in
$ diffman-git
--- HEAD:man/man3/dl_iterate_phdr.3
+++ ./man/man3/dl_iterate_phdr.3
@@ -10,10 +10,11 @@
#define _GNU_SOURCE /* See feature_test_macros(7) */
#include <link.h>
- int dl_iterate_phdr(
- typeof(int (struct dl_phdr_info *info, size_t size, void *data))
- *callback,
- void *data);
+ int
+ dl_iterate_phdr(
+ typeof(int (struct dl_phdr_info *info, size_t size, void
*data))
+ *callback,
+ void *data);
DESCRIPTION
The dl_iterate_phdr() function allows an application to inquire at run
Which of course, runs off the right margin. That's the reason I think
SY should reduce the indentation if the first line after it would go
past the right margin. That's not ideal because non-first arguments
would still have the issue, but at least it reduces the number of cases
where something like this happens.
What do you think?
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
