Hi Ingo, On 8/2/22 14:55, Ingo Schwarze wrote:
Hi Alejandro,Alejandro Colomar wrote on Tue, Aug 02, 2022 at 12:58:41AM +0200:Would you mind disabling the following warning?: mandoc: man3type/regex_t.3type:7:5: STYLE: lower case character in document title: TH regex_tYes.
[...] Good.
Also, may I make you reconsider allowing one to disable specific warnings?I still seriously dislike that idea. A mechanism to control individual diagnostic messages seems easy enough on first sight, but in practice, i have seen it turn into one of the inroads eventually causing excessive complexity. Execessive complexity in message systems usually does not result from one single giant design mistake, but instead from accumulating multiple small features that, each regarded in isolation, all seem inoccuous and simple at first - until they start to accumulate and interact. To cite a groff example currently being discussed in parallel: it's similar to already having a classicification system, but still adding add-hoc controls (variable + if) for a single message that doesn't seem to fit anywhere - instead of making the system more usable and systematic without making it more complex. :-/ Over the years, i have spent considerable amounts of work to make the mandoc message system simple and systematic (in a certain early phase, it did suffer from large numbers of small misdesigns, as indeed the message systems of most projects do). I do not want to have all that work wasted.
Well, as you're going to fix my main concerns about mandoc(1)'s -Tlint, I won't need to silence any warnings in the future. So no need to do this at all :)
There are a lot of empty UR blocks in the Linux man-pages, and I don't consider that a wrong thing.Upon reconsideration, i came to the conclusion that you are right about that point and fixed it with the commit appended below. If you want to apply it locally, applying the man_validate.c part only is obviously sufficient.
Thanks! One less thing I need to ignore.
Also, we use macros in tables, which mandoc(1) doesn't support (yet? never?),It is on the TODO list, but among the most difficult entries on the TODO list. During the last few years, i estimate that about two thirds of what needs to be done for that end has been achieved, but the last third of the work still isn't easy.
This is the only other big issue I need to ignore. Knowing it is in a TODO list is enough for me. I can live with some workarounds for now.
but that's not a big issue to the man-pages I maintain.I'm still unsure what to do about that warning. Just deleting it is not an option because we clearly *do* want to tell people about features unsupported by mandoc.
No, don't delete it. If you weren't going to implement tbl(1) support some day, I would ask you to do something about it, but since you plan to support it, it's fine.
Yet I want to lint the pages with mandoc(1) for other interetsting warnings.One workaround you might possibly consider is treating the exit status 4 from mandoc(1) as "success" (see the mandoc(1) manual page for details). Exit status 2, 3, and 5 and higher are clearly errors, but 4 means that the most severe issue found was "unsupported by mandoc", which might possibly make sense to ignore for your purpose. Then again, the downside of treating 4 as success is that it will hide other errors and warnings the same page may contain, and also that there may be some features that are unsupported by mandoc and that you do want to avoid.
$ cat broken.7
.TH Title 7 2022-08-02 alx experiments
.SH Table with macros
.TS
l.
T{
.B really?
did you need a table for this?
T}
.TE
.SH Foo
I've got a nice URL:
.UR http://example.org
.UE
.SH Bar
And also some broken code with SP SP TAB:
foo bar baz
in filled text!
$ mandoc -Tlint -Wstop broken.7
mandoc: broken.7:6:2: UNSUPP: ignoring macro in table: B really?
$ echo $?
4
$ mandoc -Tlint broken.7
mandoc: broken.7:6:2: UNSUPP: ignoring macro in table: B really?
mandoc: broken.7:1:6: STYLE: lower case character in document title: TH
Title
mandoc: broken.7:12:2: WARNING: empty block: UR mandoc: broken.7:16:6: WARNING: tab in filled text mandoc: broken.7:16:12: WARNING: tab in filled text $ echo $? 4 Taking 4 as if it were 0 would be like using make(1)'s -i, but worse.I prefer using `make -i lint-man-mandoc | grep -v ...` and knowing I can only run it once (then touch all pages to run it again).
Another way out might be to define "-W linux" just like we already define "-W openbsd" and "-W netbsd" (again, see the mandoc(1) manual page for details) and let this level suppress the UNSUPP message about macros inside tables. I'm not yet sure whether that would be a good idea.
No, I don't like this idea:It's like allowing to ignore messages, but only if you're in a VIP group. I prefer either allowing one to cherry-pick their coding style (by ignoring some warnings), or not allowing it at all. And for the Linux man-pages, as said, you're planning to implement support for tbl and remove other unwanted warnings, so it's all good.
For the current pages, I already went through all of them with a few workarounds, so I shouldn't need to run `make lint-man-mandoc` in a long time.
Is that too hard to implement?Difficulty of implementation isn't the only reason for rejecting a feature - if you add every feature that seems easy to implement, you eventually die a painful death from featuritis.
As said, I don't need that feature anymore :) Cheers, Alex
Yours, Ingo Log Message: ----------- If the body of a man(7) .MT or .UR block is empty, do not emit a warning. Leaving the body empty is legitimate in this case if the author only wants to display a mail address or URI without providing a link text. Output modules already handle this correctly: terminal output shows just the URI without an accompanying text, HTML output uses the URI for *both* the href= attribute and as the content of the <a> element. The documentation was also wrong and claimed that an .MT or .UR block with an empty body would produce no output. As explained above, this isn't true. Bogus warning reported by Alejandro Colomar <alx dot manpages at gmail dot com>.
:-) -- Alejandro Colomar <http://www.alejandro-colomar.es/>
OpenPGP_signature
Description: OpenPGP digital signature
