Hi Ingo, On Wed, Jun 04, 2025 at 08:35:48PM +0200, Alejandro Colomar wrote: > > * .P is not used in its semantical function here (there is no > > paragraph of text), but abused as a presentational hack > > to insert vertical spacing, similar to the .sp request, > > which means that .SY fails at adequately controlling > > vertical spacing. > > In some (most) cases, I want function prototypes to not insert blanks > before them. See man-pages(7), as written by Michael:
Talking about this, I've now finished my changes, and was trying to
pass the usual linters. mandoc(1) is complaining:
alx@devuan:~/tmp$ cat pp.man
.TH A 7 2025-06-06 f
.SH g
foo
.P
.SY foo
bar
baz
.YS
alx@devuan:~/tmp$ mandoc -Tlint -man pp.man
mandoc: pp.man:4:2: WARNING: skipping paragraph macro: PP empty
I'm considering the following commit:
commit a2524028e0cb358356f6c8574a4e8d3ded451a72
Author: Alejandro Colomar <a...@kernel.org>
Date: Fri Jun 6 01:11:06 2025 +0200
share/mk/lint/man/mandoc.ignore.grep: Ignore false positive
It seems mandoc(1) considers a paragraph that consists solely of
SY/YS
to be empty. It is not empty. Let's ignore mandoc(1).
Cc: Ingo Schwarze <schwa...@openbsd.org>
Signed-off-by: Alejandro Colomar <a...@kernel.org>
diff --git a/share/mk/lint/man/mandoc.ignore.grep
b/share/mk/lint/man/mandoc.ignore.grep
index a51f6f5c9..e4fc6eb9a 100644
--- a/share/mk/lint/man/mandoc.ignore.grep
+++ b/share/mk/lint/man/mandoc.ignore.grep
@@ -6,5 +6,6 @@ STYLE: referenced manual not found: Xr
UNSUPP: ignoring macro in table:
WARNING: empty block: UR
WARNING: missing date, using "": TH
+WARNING: skipping paragraph macro: PP empty
WARNING: undefined escape, printing literally: \\\\
WARNING: cross reference to self: Xr
Do you have any comments?
Have a lovely night!
Alex
>
> SYNOPSIS
> Wrap the function prototype(s) in a .nf/.fi pair to prevent fill‐
> ing.
>
> In general, where more than one function prototype is shown in the
> SYNOPSIS, the prototypes should not be separated by blank lines.
> However, blank lines (achieved using .P) may be added in the fol‐
> lowing cases:
>
> • to separate long lists of function prototypes into related
> groups (see for example list(3));
>
> • in other cases that may improve readability.
>
> In the SYNOPSIS, a long function prototype may need to be contin‐
> ued over to the next line. The continuation line is indented ac‐
> cording to the following rules:
>
> (1) If there is a single such prototype that needs to be contin‐
> ued, then align the continuation line so that when the page
> is rendered on a fixed‐width font device (e.g., on an xterm)
> the continuation line starts just below the start of the ar‐
> gument list in the line above. (Exception: the indentation
> may be adjusted if necessary to prevent a very long continua‐
> tion line or a further continuation line where the function
> prototype is very long.) As an example:
>
> int tcsetattr(int fd, int optional_actions,
> const struct termios *termios_p);
>
> (2) But, where multiple functions in the SYNOPSIS require contin‐
> uation lines, and the function names have different lengths,
> then align all continuation lines to start in the same col‐
> umn. This provides a nicer rendering in PDF output (because
> the SYNOPSIS uses a variable width font where spaces render
> narrower than most characters). As an example:
>
> int getopt(int argc, char * const argv[],
> const char *optstring);
> int getopt_long(int argc, char * const argv[],
> const char *optstring,
> const struct option *longopts, int *longindex);
>
>
> Michael and I agreed on those formatting conventions without much
> discussion.
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
