On Fri, 26 Nov 2021 13:31:17 +0100, Marc Espie <[email protected]> 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
