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

On Fri, 26 Nov 2021 13:31:17 +0100, Marc Espie <espie@nerim.net> wrote:

> I think it's also covered in the FAQ somewhat, but the manpages
> should at least give a headstart for new users.

I think it's indeed nice to document these pieces! Some comments inline.

>
> 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
[...]
> +.It ports-readmes-dancer
> +a simple local webserver that interfaces with that database to
> display information. +.Po
> +There is a copy of that server hosted on

I would say "a running instance" instead. "copy" sounds static and I
would read that like openports.pl is distributing the tar.gz.

> +.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.

"still" weakens "deprecated". I would not add it.

> .Bl -tag -width configure
> .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
> +.Pa databases/pkglocatedb

Given the man is (i.e. with more context than the diff offers):
95 All static index generating information has now been superseded by the
96 .Pa sqlports ,
97 .Pa portslist
98 or
99 .Pa pkglocatedb
100 packages, which contain
101 similar information to the old INDEX file, but are more frequently updated.

I feel it would mention them twice. Wouldn't it be better to update the
current .Pa, and add the

> +and
> +.Xr pkg_mklocatedb 1

there?

Also, this whole section begins with "All static index generating
information has now been superseded" which implies "it used to be
different" and I think it would be good to reword that part (as another
diff or whatever).

> +for details.
> .Sh SELECTING A SET OF PORTS
> One can define
> .Ev SUBDIRLIST
>

Cheers,
Daniel