On Fri, Aug 22, 2025 at 03:39:16PM +0200, Ingo Schwarze wrote: > Hello Alejandro,
Hello Ingo, > Alejandro Colomar wrote on Thu, Aug 21, 2025 at 09:45:25PM +0200: > > > I somehow understand you. I've seen a lot of low-quality pages. I've > > had to improve the quality of the sources I maintain a lot, even though > > they were already above average. > > > > On the other hand, it's sad that I can't get many of mandoc(1)'s > > diagnostics. I'm really interested in several of them, as we've > > discussed in the past. > > > > Would you consider a knob for pedantic people like me that want the > > quality of their sources to be on par with mdoc(7) documents, if not > > higher? Like maybe -Wpedantic or -Weverything? > > An *additional* knob? No, not really. Too many knobs is what makes > message systems unusable. Agree. > The mandoc message system has been designed > very carefully to have the following properties: > > 1. It is one-dimensional, or expressed more mathematically, the > warning options form a totally ordered set. That improves > usability by making sure it is always trivial to figure > out how to get more messages (crank the level up by one) > or fewer messages (push the level down by one). The user > never has to wonder in which of more than two directions > to change the message settings or which message > class/group/category/option/whatever to enable or disable. > There are also very deliberately no additional message flags of > any kind that are in any way orthogonal to the main -W setting, > thus avoiding any kind of complication. Makes sense. > > 2. Each level has a well-defined meaning that relates to the > qualitative severity of the potential consequences of the > issue. These meanings are the same for all supported > languages - mdoc(7), man(7), tbl(7), eqn(7), roff(7) - > so users do not need to learn language-specific quirks. > > 3. The number of levels is intentionally very small: > base, style, warning, error, unsupp. > See: https://man.openbsd.org/mandoc#DIAGNOSTICS > Adding another level is not really an option: > What would be the logical significance of such a level? > > > However, i should likely reconsider my stance of man(7) leaning more > to the silent side than mdoc(7), for four reasons. Thanks! > a) It never aligned very well with design principle 2 above. > For example, if something is bad style, logically, it ought > to cause a style message, even if the particular style issue > is widespread in practice. > > b) Even leaning towards terseness, mandoc -T lint gets quite > chatty on typical man(7) corpusses anyway. For example, in > OpenBSD-current base: > > $ mandoc -T lint /usr/share/man/man3p/*.3p | wc -l > 9097 > > Adding a few more is not going to create any serious practical > problem, at least none that isn't already there. > Even i am rarely linting the whole OpenBSD manual tree at > once these days, and certainly not including the legacy > man(7) pages it still contains. > > c) People who use mandoc a lot (for example, *BSD users) tend > to use man(7) rarely, and mandoc -man -T lint even less > because they don't maintain their own docs in man(7), and > why would they lint other people's stuff? > So making -man -T lint a bit more chatty is unlikely to > impact many people negatively. > > d) And most importantly, one thing has changed compaged to > fifteen years ago, when the decision to make -man -T lint > more silent was made. Back then, basically nobody at all > cared about man(7) code quality. Now, there are at least > two people actively working on the subject (Branden and you). > > Making the feature more useful for those who actually want it > without substantially impacting anyone who doesn't care sounds > like a win overall. > > I just committed the "blank line in fill mode" warning for man(7), > see the committed patch below. Great! Now I'll be waiting for your next release, to try the new toy. :-) > When you feel specific other warnings are missing, please speak up, > even if you already brought them up in the past and got rejected: > maybe they are acceptable with the now modified policy of > warning in man(7) where it logically makes sense, even when > the issue is still widespread in low-quality manuals. By reading mandoc(1), here's what I think I'd like to see changed: - Please remove: lower case character in document title - Maybe add to man(7): possible typo in section name referenced manual not found trailing delimiter verbatim "--", maybe consider using \(em function name without markup first section is not NAME (But please accept Name) bad NAME section content (If \- is missing or one side is empty) missing comma before name duplicate section title - I'm not sure: no blank before trailing delimiter sections out of conventional order unexpected section (I'll continue researching the list. I need to hit send before the train arrives at the destination.) > > In many cases, adding a warning is not particularly difficult. > > Yours, > Ingo > > > CVSROOT: /cvs > Module name: src > Changes by: schwa...@cvs.openbsd.org 2025/08/22 07:08:21 > > Modified files: > usr.bin/mandoc : man.c mandoc.1 > regress/usr.bin/mandoc/roff/cond: close.out_lint if.out_lint > regress/usr.bin/mandoc/man/blank: line.out_lint > > Log message: > Warn about blank lines in man(7) just like it is already done in mdoc(7). > Feature suggested by Alejandro Colomar <a...@kernel.org> on <groff@gnu.org>. Thanks! Have a lovely day! Alex > > > Index: usr.bin/mandoc/man.c > =================================================================== > RCS file: /cvs/src/usr.bin/mandoc/man.c,v > diff -u -p -r1.137 man.c > --- usr.bin/mandoc/man.c 16 Aug 2022 22:59:48 -0000 1.137 > +++ usr.bin/mandoc/man.c 22 Aug 2025 13:04:07 -0000 > @@ -132,6 +132,7 @@ man_ptext(struct roff_man *man, int line > *ep = '\0'; > return 1; > } > + mandoc_msg(MANDOCERR_FI_BLANK, line, i, NULL); > roff_elem_alloc(man, line, offs, ROFF_sp); > man->next = ROFF_NEXT_SIBLING; > return 1; > Index: usr.bin/mandoc/mandoc.1 > =================================================================== > RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v > diff -u -p -r1.198 mandoc.1 > --- usr.bin/mandoc/mandoc.1 9 Jul 2025 13:45:15 -0000 1.198 > +++ usr.bin/mandoc/mandoc.1 22 Aug 2025 13:04:07 -0000 > @@ -1002,14 +1002,14 @@ macro that could be represented using > or > .Ic \&Dx . > .It Sy "errnos out of order" > -.Pq mdoc, Nx > +.Pq mdoc , Nx > The > .Ic \&Er > items in a > .Ic \&Bl > list are not in alphabetical order. > .It Sy "duplicate errno" > -.Pq mdoc, Nx > +.Pq mdoc , Nx > A > .Ic \&Bl > list contains two consecutive > @@ -1150,7 +1150,7 @@ The > argument is used as provided anyway. > Consider checking whether the file name or the argument need a correction. > .It Sy "missing date, using \(dq\(dq" > -.Pq mdoc, man > +.Pq mdoc , man > The document was parsed as > .Xr mdoc 7 > and it has no > @@ -1732,7 +1732,7 @@ or > macro contains an opening or closing parenthesis; that's probably wrong, > parentheses are added automatically. > .It Sy "unknown library name" > -.Pq mdoc, not on Ox > +.Pq mdoc , not on Ox > An > .Ic \&Lb > macro has an unknown name argument and will be rendered as > @@ -1790,7 +1790,7 @@ The last character is mapped to the blan > .Ss "Warnings related to plain text" > .Bl -ohang > .It Sy "blank line in fill mode, using .sp" > -.Pq mdoc > +.Pq mdoc , man > The meaning of blank input lines is only well-defined in non-fill mode: > In fill mode, line breaks of text input lines are not supposed to be > significant. > @@ -1800,6 +1800,8 @@ are formatted like > requests. > To request a paragraph break, use > .Ic \&Pp > +or > +.Ic \&PP > instead of a blank line. > .It Sy "tab in filled text" > .Pq mdoc , man > Index: regress/usr.bin/mandoc/roff/cond/close.out_lint > =================================================================== > RCS file: /cvs/src/regress/usr.bin/mandoc/roff/cond/close.out_lint,v > diff -u -p -r1.8 close.out_lint > --- regress/usr.bin/mandoc/roff/cond/close.out_lint 3 Aug 2020 10:52:39 > -0000 1.8 > +++ regress/usr.bin/mandoc/roff/cond/close.out_lint 22 Aug 2025 13:04:07 > -0000 > @@ -1,3 +1,5 @@ > +mandoc: close.in:42:9: WARNING: blank line in fill mode, using .sp > mandoc: close.in:65:1: ERROR: escaped character not allowed in a name: BR\& > +mandoc: close.in:68:9: WARNING: blank line in fill mode, using .sp > mandoc: close.in:68:2: ERROR: appending missing end of block: if > mandoc: close.in:68:9: WARNING: skipping paragraph macro: sp after PP > Index: regress/usr.bin/mandoc/roff/cond/if.out_lint > =================================================================== > RCS file: /cvs/src/regress/usr.bin/mandoc/roff/cond/if.out_lint,v > diff -u -p -r1.6 if.out_lint > --- regress/usr.bin/mandoc/roff/cond/if.out_lint 4 Dec 2018 02:53:45 > -0000 1.6 > +++ regress/usr.bin/mandoc/roff/cond/if.out_lint 22 Aug 2025 13:04:07 > -0000 > @@ -1,4 +1,7 @@ > +mandoc: if.in:8:6: WARNING: blank line in fill mode, using .sp > mandoc: if.in:15:2: WARNING: conditional request controls empty scope: if > mandoc: if.in:17:2: WARNING: conditional request controls empty scope: if > +mandoc: if.in:17:7: WARNING: blank line in fill mode, using .sp > +mandoc: if.in:43:9: WARNING: blank line in fill mode, using .sp > mandoc: if.in:42:2: WARNING: skipping paragraph macro: br before sp > mandoc: if.in:71:2: WARNING: skipping paragraph macro: br after br > Index: regress/usr.bin/mandoc/man/blank/line.out_lint > =================================================================== > RCS file: /cvs/src/regress/usr.bin/mandoc/man/blank/line.out_lint,v > diff -u -p -r1.7 line.out_lint > --- regress/usr.bin/mandoc/man/blank/line.out_lint 1 Jul 2025 20:17:13 > -0000 1.7 > +++ regress/usr.bin/mandoc/man/blank/line.out_lint 22 Aug 2025 13:04:07 > -0000 > @@ -1,3 +1,12 @@ > +mandoc: line.in:16:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:49:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:51:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:55:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:57:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:61:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:63:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:66:1: WARNING: blank line in fill mode, using .sp > +mandoc: line.in:67:1: WARNING: blank line in fill mode, using .sp > mandoc: line.in:2:2: WARNING: skipping paragraph macro: br before first SH > mandoc: line.in:19:2: WARNING: skipping paragraph macro: br after br > mandoc: line.in:25:2: WARNING: skipping paragraph macro: br after PP -- <https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
