Re: makemandb errors from pkgsrc

[Aleksej Saushev <asau%inbox.ru@localhost>]

Dave Huang <khym%azeotrope.org@localhost> writes:

> On Mar 5, 2012, at 5:38 PM, Joerg Sonnenberger wrote:
>> The same argument has been used to complain about compiler warnings.
>> Guess what -- often enough they point out real issues. The major reason
>> why so many man page have smaller or bigger markup bugs is that it
>> always was way too easy to ignore the warnings groff throws. The
>> messages are parse errors. They signify that the markup or content is
>> broken in a way that the document isn't indexed. As such it is the
>> perfect example of what should not be silenced.
>
> Yes, maybe there are real issues with the manpage. And what are the 
> consequences?

I think that Joerg explained what the consequences are.

> If you ignore a compiler warning, maybe the program will dump core or have a 
> security vulnerability.

If documentation is rendered incorrectly this may lead to security 
vulnerability as well.

> If you ignore a manpage indexing error, maybe apropos will only show you a 
> one-line summary,
> as it did in NetBSD 5.x and earlier. Certainly not ideal, but not too bad...
> *nix has been working like that for decades.

This argument sounds as (in plain words) "we have lived with this for decades, 
why change it then?"
The reason to change is that we want to live in a better world than we lived in 
for decades.
Why do you not think that we lived this way for decades not because we didn't 
want it?
Perhaps, we lived that way because we, for one reason or another, could not.
We had not enough machine resources or just hands and time to implement it or 
both or anything else.

> And what's an end user supposed to do with these manpage errors?

End user should consider them. These errors indicate which man pages are
not indexed by documentation system, and possibly are not rendered or
even rendered incorrectly. Since these warnings affect end user they are
(to some extent) even more important than compiler warnings.

> Compiler warnings are seen by the developers writing the code, and
> when they see the warning, they can/should do something to fix it.
> makemandb's errors are seen by end-users of the manpages, most of whom
> did not write the manpage, and can't do anything to fix it. The issue
> is that makemandb is showing me errors that I can't do anything about.

What do you do when your operating system shows you errors?
Can you fix all of them?

> Manpage authors should lint their pages, and pkgsrc package
> maintainers should lint their package's pages--but end users shouldn't
> get daily reminders of manpage authors' failure to do so.

Some developers do, some don't. There's a lot of software around you
that is written in ignorance of compiler warnings. In part, because those
are not emitted in the first place, you have to turn them on explicitly.


-- 
HE CE3OH...