[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: All caps .TH page title

From: Alejandro Colomar
Subject: Re: All caps .TH page title
Date: Tue, 2 Aug 2022 18:16:38 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.1.0

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_t




Also, may I make you reconsider allowing one to disable specific

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
.B really?
did you need a table for this?
.SH Foo
I've got a nice URL:
.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 $?
$ 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 $?

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 :)




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

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]