On Sun, 12 Apr 2015 23:03:17 +0200 Ingo Schwarze <schwa...@usta.de> wrote: > Hi, > > dan mclaughlin wrote on Sun, Apr 12, 2015 at 04:43:31PM -0400: > > > it seems that /usr/ports/infrastructure/man is not searched by default, > > Correct. The reason is that that directory does not even exist > in a default OpenBSD installation.
makes perfect sense, i figured as much. > > > and there is no example in man.conf for it. > > Correct, too. I'm not opposed to adding that example. > Your patch, as it stands, is NOT OK though, because the example > file shows the default settings. So at least, the line needs > to be commented out, and a comment explaining its purpose > might be in order, too. i did think of that later. i was in a rush, and my intent was just to give an example. i was expecting feedback anyway so that i better understood what was going on. > > > given that some pages like dpb(1) are there, and referenced > > thruout a number of pages (eg bsd.port.mk), this seems an oversight. > > Actually, the reason why i didn't mention it in the example file > is that it seemed so trivial to me that i didn't expect that this > particular example might help some people. If it does - fair enough. well, i was surprised not to find the manpage at first, especially when devs kept mentioning it, but didn't look into it at the time. i finally had a need for it, and went digging further. i found where the command was in the faq, and made a guess where the manpages were, but i don't think it would be that obvious to everybody. other aspect of the ports system are in the man tarball, such as bsd.port.mk, so at first i didn't think that there may be a special manpath for the ports system. plus, it seems like the perfect non-standard use case to have as an example. > > > on a releated note, it also seems that ports/infrastructure/man/mandoc.db > > is also not created by default. > > There is no reasonable way to include that file. The ports tarball > is a *source* tarball, and mandoc.db is not a source file. > Either running "makewhatis /usr/ports/infrastructure/man" or > adding it to man.conf(5) and running "makewhatis" is required. > i figured it was something like this, which is why i mentioned it as something of an aside. > > the diff below adds a manpath to man.conf, but that still doesn't fix the > > issue of ports/infrastructure/man not being searched. perhaps this should > > be taken out of examples? > > No. It was specifically decided not long ago that > /usr/ports/infrastructure/man will not be searched by default. If > you want it, you have to add it manually. fair enough, i didn't expect this was the most acceptable solition, i was just listing the possibilities. there should be a hint though. > > > or at least some note should be made in ports(7) or the FAQ that > > one should add this? > > Something like that is probably useful. i think i found the perfect places for this in both ports(7) and the FAQ. i'm sure the wording can be improved, but diffs below. > > Yours, > Ingo > --- etc/examples/man.conf Fri Mar 27 17:17:16 2015 +++ etc/examples/man.conf.new Mon Apr 13 00:53:42 2015 @@ -8,6 +8,9 @@ manpath /usr/share/man manpath /usr/X11R6/man manpath /usr/local/man +#users of the ports system may find this useful for certain ports-only commands +#manpath /usr/ports/infrastructure/man + # Options for terminal output. output width 78 output indent 5 even if you don't want the mention in the intro, the listing under FILES should be kept. --- share/man/man7/ports.7 Sat Mar 7 07:21:55 2015 +++ share/man/man7/ports.7.new Mon Apr 13 00:45:29 2015 @@ -72,6 +72,11 @@ Porter's Handbook .Pp For a detailed description of the build process, see .Xr bsd.port.mk 5 . +.Pp +Additional manual pages for the ports system can be located in +.Pa /usr/ports/infrastructure/man +(users may want to add this to their +.Pa /etc/man.conf ) . .Sh PORTS MASTER MAKEFILE The ports master Makefile, normally located in .Pa /usr/ports/Makefile @@ -727,6 +732,8 @@ Local network configuration. Filter list for systrace. .It Pa /usr/ports/infrastructure/db/user.list List of users and groups created by ports. +.It Pa /usr/ports/infrastructure/man +Path for addition ports system manual pages. .El .Sh SEE ALSO .Xr dpb 1 , --- faq15.html Mon Apr 13 00:21:35 2015 +++ faq15.html.new Mon Apr 13 00:28:12 2015 @@ -754,6 +754,7 @@ the use of flavors and subpackages and some other opti <li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=bsd.port.mk&sektion=5";>bsd.port.mk(5)</a> - in depth information about all the make targets, variables, the fake (installation directory) framework, etc. +<li>the directory /usr/ports/infrastructure/man/ also contains additional manual pages (users may want to add this to man.conf). </ul> <h3 id="PortsFetch">15.3.2 - Fetching the ports tree</h3>
