Re: All caps .TH page title

[Alejandro Colomar]

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

[...]

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