Re: ports(7) and packages(7) tweaks

On Fri, Nov 26, 2021 at 01:31:17PM +0100, Marc Espie wrote:
> I think it's also covered in the FAQ somewhat, but the manpages should at
> least give a headstart for new users.

I agree that manuals should have this.

> Okay ?

OK kn with comments addressed.

> Index: packages.7
> ===================================================================
> RCS file: /cvs/src/share/man/man7/packages.7,v
> retrieving revision 1.45
> diff -u -p -r1.45 packages.7
> --- packages.7 4 Dec 2019 11:07:58 -0000 1.45
> +++ packages.7 26 Nov 2021 12:30:14 -0000
> @@ -56,6 +56,24 @@ distribution
> .Pa compXX.tgz ...
> .Pc
> is not composed of such packages, but of plain tarballs.
> +.Sh FINDING PACKAGES
> +The official builds feature packages that will help with finding a given piece
> +of software:
> +.Bl -tag -width ports-readme-dancer1

Fix the "readme[s]" typo and your extra "1" can go to fix the spacing
issue you saw due to the typo.

> +.It pkglocatedb
> +a
> +.Xr locate 1
> +database of all files in the ports tree

Missing .

Even those it's not a full sentence, the other items as well as other
lists in this manual consistently use them.

> +.It sqlports
> +an sqlite database of all meta-info of each port, along with an index,
> +and a tool to trace dependencies chains.
> +.It ports-readmes-dancer
> +a simple local webserver that interfaces with that database to display information.

Longer than 80 chars. I don't care but `mandoc -T lint' does.

> +.Po
> +There is a copy of that server hosted on
> +.Lk https://openports.pl/
> +.Pc .
> +.El
> .Sh SECURITY CAVEAT
> The packages are not as thoroughly audited as the main
> .Ox
> Index: ports.7
> ===================================================================
> RCS file: /cvs/src/share/man/man7/ports.7,v
> retrieving revision 1.128
> diff -u -p -r1.128 ports.7
> --- ports.7 28 Apr 2020 13:11:32 -0000 1.128
> +++ ports.7 26 Nov 2021 12:30:14 -0000
> @@ -72,10 +72,12 @@ The ports master Makefile, normally loca
> (but see
> .Ev PORTSDIR
> below)
> -offers a few useful targets.
> +still offers a few deprecated targets.
> .Bl -tag -width configure

The width should be "print-index" so as to avoid the line break.
"configure" doesn't exist in this list anymore.

> .It Cm print-index
> -display the contents of the index in a user-friendly way,
> +display the contents of the index in a
> +.Sq user-friendly
> +way,
> .It Cm search
> invoked with a key, e.g.,
> .Ic make search key=foo ,
> @@ -98,7 +100,13 @@ All static index generating information
> or
> .Pa pkglocatedb
> packages, which contain
> -similar information to the old INDEX file, but are more frequently updated.
> +similar information to the old INDEX file, but are frequently updated.
> +See
> +.Pa databases/sqlports

missing ,

> +.Pa databases/pkglocatedb
> +and
> +.Xr pkg_mklocatedb 1
> +for details.
> .Sh SELECTING A SET OF PORTS
> One can define
> .Ev SUBDIRLIST
>