Re: Discrepancy in mansearch and fs_lookup behavior

["Sören Tempel" <soeren@soeren-tempel.net>]

Ingo Schwarze <schwarze@usta.de> wrote:
> Hi Soeren,

Hello Ingo,

> Hold on a second; if there are mandoc bugs or misfeatures in this area,
> uprooting major areas of manual page forests in a particular operating
> system may not be the best option for dealing with that.

Indeed, I would also prefer not move the Alpine man page. It was just
unclear to me whether mandoc intended to support lookup for section
which do not have their own subdirectory in MANDIR from reading the
fs_lookup code it seemed to me that this was not supported, thus my
initial idea was to move the pages.

> Do you mean, "with mandoc"?

Yes.

> In the following, let us keep the discussion of makewhatis(8),
> mansearch() and fs_search() strictly separate.  This is the order
> of decreasing importance.

In the following I will perform all tests with the open(3p) and the
open(3pm) man page installed as follows in MANDIR:

	/usr/share/man/man3/open.3pm.gz
	/usr/share/man/man3/open.3p.gz

>   === PAGES ===
>   page name # [fh1t]open # [t]openat 
>   page sect # 3 # 3P # 3p 
>   page desc # open file 
>   page file src # man3/open.3p 
>   page name # [fh1t]open 
>   page sect # 3 # 3p # 3pm 
>   page desc # perl pragma to set default PerlIO layers for input and output 
>   page file src # man3/open.3pm 
>   === END OF PAGES ===
> 
> That looks reasonable to me.  In particular, it has the "3" from
> the directory name, the 3P/3p from the file content, and the 3p/3pm
> from the file name.

The dbm_dump output for these two pages looks as follows on a standard
Alpine Linux Edge installation with a mandoc.db generated with
makewhatis(8) from mandoc-1.14.5:

	page name # [fh1t]open # [t]openat
	page sect # 3 # 3P # 3p
	page desc # open file
	page file src # man3/open.3p.gz
	page name # [fh1t]open
	page sect # 3 # 3pm
	page desc # perl pragma to set default PerlIO layers for input and output
	page file src # man3/open.3pm.gz

This does look similar to your output. The only difference seems to be
that my man pages are gzip compressed.

> Next up, regarding mansearch().
> 
>   man -M Test open      -> Perl; random choice because bits, sec, name,
>                                  and arch all compare equal
>   man -M Test 3 open    -> Perl; dto. and both file extensions mismatch
>   man -M Test 3p open   -> POSIX; preferred due to exact file extension match

If I try to duplicate your mansearch() tests I get the following results:

	man open    -> open(2) Linux man page (/usr/share/man/man2/open.2.gz)
	man 3 open  -> open(3pm) Perl man page
	man 3p open -> open(3pm) Perl man page

I get these results with both mandoc-1.14.5 and mandoc from current CVS.
Only for `man 3pm open` these two mandoc versions seem to return
different results:

	man 3pm open:
		CVS version:   open(3pm) Perl man page
		mandoc-1.14.5: open(2) Linux man page

For `man 3p open` I briefly stepped through the mansearch() code with
gdb on the mandoc CVS version. What happens here is that mansearch()
returns the following results:

	(gdb) p resnsz
	$1 = 2
	(gdb) p resn[0]
	$2 = {
		file = 0x7ffff7ffe8e0 "/usr/share/man/man3/open.3pm.gz",
		names = 0x7ffff7ffed20 "open(3, 3pm)",
		output = 0x7ffff7f60b00 "perl pragma to set default PerlIO layers for input and output",
		bits = 30,
		ipath = 0,
		sec = 3,
		form = FORM_SRC
	}
	(gdb) p resn[1]
	$3 = {
		file = 0x7ffff7ffe8b0 "/usr/share/man/man3/open.3p.gz",
		names = 0x7ffff7ffed00 "open, openat(3, 3P, 3p)",
		output = 0x7ffff7f608f0 "open file",
		bits = 30,
		ipath = 0,
		sec = 3,
		form = FORM_SRC
	}
	
mandoc then searches for the best match according to priority. In this
case both resn[0] and resn[1] get a priority of 35. However, since it
iterates over resn[0] first and the comparison with best_prio is a
greater than or equal comparison [1], resn[0] is the one that gets
selected. Maybe this is a problem with the .gz file extension?

	if (search.sec != NULL &&
	    (strlen(sec) <= ssz  + 3 ||
	     strcmp(sec + strlen(sec) - ssz,
	      search.sec) != 0))
	   prio += 20; /* Wrong file ext. */

The above code is where I would expect the two man pages to differ since
search.sec is 3p and as such should cause the open(3p) man page to get the
better priority. Unfortunately, this does not work correctly since the file
extension extracted here is gz, not 3p. This would also explain why we get
different mansearch() results.

Regarding fs_search(): I tested the patch from your other reply. This
patch work entirely fine for me and does what it is supposed to do. I
applied this patch on top of the CVS version. With mandoc.db removed, I
get the following results:

	man 3 open    -> open(3p) POSIX man page
	man 3p open   -> open(3p) POSIX man page
	man 3pm open  -> open(3pm) Perl man page

So yes, your patch does seem to improve the fs_search() behaviour, thanks a
lot! This is what I would expect the mansearch() to also return.

> > With this setup `man 3p open` will always open the Perl man page and
> > there seems to be no way to open the POSIX man page.
> 
> I can't reproduce, see above.  Are you sure?  Is this with or without
> mandoc.db?  Are you using the latest mandoc from CVS?

I tried to clarify this above. There presently does seem to be no way to
access open(3p) on Alpine with mansearch() neither with the CVS version
nor with 1.14.5.

Greetings,
Sören

[1]: https://github.com/openbsd/src/blob/2207c4325726fdc5c4bcd0011af0fdf7d3dab137/usr.bin/mandoc/main.c#L519-L520
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv