Hi Raf,
Raf Czlonka wrote on Thu, Dec 20, 2018 at 02:59:23PM +0000:
> Recently, I've noticed an odd-looking output from weekly(8):
>
> Rebuilding whatis databases:
> makewhatis: man7/cmake-properties.7: ERROR: No such file or directory
You are right, there are a number of bugs here.
I feel tempted to call it a cloud of mosquitoes.
Thanks for the analysis.
1. The line number is missing, even though it is relevant.
2. Mentioning the .so request would be useful.
3. Mentining the file that was not found would be useful.
4. Most importantly, makewhatis(8) is not supposed
to print mandoc(1) errors in this manner.
The MANDOCERR_FILE enum item gets special handling in the code in
several ways, but the effects are less than pretty. I think i have
to revisit how this error item is generated and handled.
> "Strange", I thought, especially since
> /usr/local/man/man7/cmake-properties.7 is "alive" and well:
>
> $ ls -l /usr/local/man/man7/cmake-properties.7
> -rw-r--r-- 1 root bin 202877 Dec 20 14:00
> /usr/local/man/man7/cmake-properties.7
In general, the file name at the beginning of a mandoc(1) message is
the name of the *input* file in which the error occurred, not the name
of a file which mandoc tried to use. Here is bug number 5:
That wasn't clearly stated in the manual page below:
https://man.openbsd.org/mandoc#DIAGNOSTICS
That's the first thing i fixed following your report,
see the commit below.
> I've rebuilt the mandoc.db
I guess you mean "with makewhatis -D"?
> and got an output which was stranger still:
>
> makewhatis: man7/cmake-properties.7: ERROR: No such file or directory
> /usr/local/man//man7/cmake-properties.7: Adding to database
>
> Huh!?
Right, makewhatis is indexing the file even though the content of
the file is buggy. But that's OK as far as it goes.
> Time for 'mandoc -Tlint':
Excellent idea.
> $ mandoc -Tlint /usr/local/man/man7/cmake-properties.7 | head
> mandoc: /usr/local/man/man7/cmake-properties.7:1131:2: WARNING: .so is
> fragile, better use ln(1): so libraries.
> mandoc: /usr/local/man/man7/cmake-properties.7: ERROR: No such file or
> directory
> mandoc: /usr/local/man/man7/cmake-properties.7:1131:15: ERROR: .so
> request failed: .so libraries.
> [...]
Bug number 6: duoplicate reporting, two messages about the same problem
in the input file, both with incomplete information. Not sure i can fix
that one, but i shall try.
> OK, let's see what on that line:
>
> $ sed -n 1131p /usr/local/man/man7/cmake-properties.7
> .so libraries.
>
> and including preceding line:
>
> Set the Android property that specifies directories to search for the
> .so libraries.
>
> Right, so '.so' (unintentional pun) is treated as a macro here -
No, not as a macro, as a roff(7) request - but that isn't what the
author intended, either.
> moving it to the line above, fixes the issue:
>
> Set the Android property that specifies directories to search for the
> .so
> libraries.
>
> Upstream uses reStructuredText but I hope this[0] does the trick.
>
> [0] https://gitlab.kitware.com/cmake/cmake/merge_requests/2756
That's not a fix but merely a workaround for a bug in reStructuredText.
It is more important to report the bug to reStructuredText than to work
around it in each and every project using reStructuredText.
The reStructuredText program ought to emit
Set the Android property that specifies directories to search for the
\&.so libraries.
for the input in question.
> Anyway, thought this might be of interest.
Indeed, thank you for reporting.
Ingo
Log Message:
-----------
Explain what the fields in mandoc messages mean,
rather than merely specifying the message syntax.
Gap in documentation found while looking at a bug
report from Raf Czlonka <rczlonka at gmail dot com>.
Modified Files:
--------------
mandoc:
mandoc.1
Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.232
retrieving revision 1.233
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.232 -r1.233
--- mandoc.1
+++ mandoc.1
@@ -714,13 +714,29 @@ Messages displayed by
follow this format:
.Bd -ragged -offset indent
.Nm :
-.Ar file : Ns Ar line : Ns Ar column : level : message : macro args
+.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments
.Pq Ar os
.Ed
.Pp
-Line and column numbers start at 1.
+The first three fields identify the
+.Ar file
+name,
+.Ar line
+number, and
+.Ar column
+number of the input file where the message was triggered.
+The line and column numbers start at 1.
Both are omitted for messages referring to an input file as a whole.
-Macro names and arguments are omitted where meaningless.
+All
+.Ar level
+and
+.Ar message
+strings are explained below.
+The name of the
+.Ar macro
+triggering the message and its
+.Ar arguments
+are omitted where meaningless.
The
.Ar os
operating system specifier is omitted for messages that are relevant
