Re: implement mandocdb -t

[Kristaps Dzonsons <kristaps@bsd.lv>]

Hi Ingo,

I have a few issues with this patch -- not the intent or code, but 
rather with the consistency of the verbosity and warnings.

First, for consistency, all warnings/errors should follow "CAUSE: 
REASON" -- including those in the getopt() switch.  Thus, "conflicting 
options" messages should be prefixed by the offending switch case and 
"Too many arguments" should begin with "-C".

Second, verbosity.  I think we should settle this now.  BSD.lv only has 
a single `-v' and I think this should stay as such ("%s: added to index" 
or "%s: removed from index" (or whatever the message is)).  This is 
completely clear and is also valuable to the user.  Noting keywords 
added or removed is unnecessary when you consider that mandocdb(8) isn't 
there to debug the keywords of individual manuals: it's there to index them.

Regarding errors, the existences of (and not reasons for) mandoc(3) 
parse errors are printed to stderr ("parse failed").  For catpages, I 
think it's unnecessary to print anything more than the same.  After all, 
it's not like the operator can do anything about the page, no?  Just 
give the same error regardless the reason.  Maybe an extra kick like 
"%s: parse failed (not a manpage?)".

Moving on to the warnings (wrong sections, architectures, etc.).  This 
shouldn't be a `-v', as this isn't a verbose message, it's a warning. 
Maybe we can pull in `-W' from mandoc(1)?  I don't think these should be 
printed by default, as they don't affect parse status.  An extra 
"warning" flag is both consistent with other utilities and doesn't 
confuse the utility of `-v'.

Another option is to print the warnings by default, but use `-q' to 
silence them.  But that's also confusing because one `-q' silences 
warnings, but `-qq' silences parse errors also?  Ugh...

If we follow this logic, then `-t' is much clearer, as it does nothing 
but run in `add' mode without changing the database.  (Isn't this 
usually termed `-n', as with make(1)?  Sigh.)  However, the `-W' flag 
(or whatever it becomes) could be turned on by default just like 
`-Tlint' turns on `-Wall' in mandoc(1).  `-v' would be unaffected and 
meaningless as no files are actually added or removed.

Thoughts?

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv