Re: All caps .TH page title

[Ingo Schwarze]

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

Yes.  Deleting that style recommendation is definitely one of the
steps that will be needed soon.  That needs coordination with at
least Jason McIntyre though because it might possibly disrupt his
work if it is deleted too early.

Eventually, a style recommendation might appear if the case of .Dt
disagress with the manual page name.  But not before all pages in
the base system have been fixed, obviously.


> 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.


> 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.


> 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.

> 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.

> 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.

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.

> 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.

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>.

Modified Files:
--------------
    mandoc:
        man_validate.c
        mandoc.1
    mandoc/regress/man/MT:
        args.out_lint
    mandoc/regress/man/UR:
        args.out_lint

Revision Data
-------------
Index: args.out_lint
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/MT/args.out_lint,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lregress/man/MT/args.out_lint -Lregress/man/MT/args.out_lint -u -p -r1.3 
-r1.4
--- regress/man/MT/args.out_lint
+++ regress/man/MT/args.out_lint
@@ -1,5 +1,3 @@
 mandoc: args.in:28:11: ERROR: skipping excess arguments: MT ... second
 mandoc: args.in:33:11: ERROR: skipping excess arguments: MT ... second
-mandoc: args.in:19:2: WARNING: empty block: MT
 mandoc: args.in:23:2: WARNING: missing resource identifier, using "": MT
-mandoc: args.in:33:2: WARNING: empty block: MT
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.262
retrieving revision 1.263
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.262 -r1.263
--- mandoc.1
+++ mandoc.1
@@ -1473,10 +1473,8 @@ A
 .Ic \&Bl ,
 .Ic \&D1 ,
 .Ic \&Dl ,
-.Ic \&MT ,
-.Ic \&RS ,
 or
-.Ic \&UR
+.Ic \&RS
 block contains nothing in its body and will produce no output.
 .It Sy "empty argument, using 0n"
 .Pq mdoc
Index: man_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_validate.c,v
retrieving revision 1.156
retrieving revision 1.157
diff -Lman_validate.c -Lman_validate.c -u -p -r1.156 -r1.157
--- man_validate.c
+++ man_validate.c
@@ -373,13 +373,11 @@ post_UR(CHKARGS)
        if (n->type == ROFFT_HEAD && n->child == NULL)
                mandoc_msg(MANDOCERR_UR_NOHEAD, n->line, n->pos,
                    "%s", roff_name[n->tok]);
-       check_part(man, n);
 }
 
 static void
 check_part(CHKARGS)
 {
-
        if (n->type == ROFFT_BODY && n->child == NULL)
                mandoc_msg(MANDOCERR_BLK_EMPTY, n->line, n->pos,
                    "%s", roff_name[n->tok]);
Index: args.out_lint
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/UR/args.out_lint,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lregress/man/UR/args.out_lint -Lregress/man/UR/args.out_lint -u -p -r1.5 
-r1.6
--- regress/man/UR/args.out_lint
+++ regress/man/UR/args.out_lint
@@ -1,5 +1,3 @@
 mandoc: args.in:28:11: ERROR: skipping excess arguments: UR ... second
 mandoc: args.in:33:11: ERROR: skipping excess arguments: UR ... second
-mandoc: args.in:19:2: WARNING: empty block: UR
 mandoc: args.in:23:2: WARNING: missing resource identifier, using "": UR
-mandoc: args.in:33:2: WARNING: empty block: UR