Re: reference pkg-readmes in manual pages
On Fri, Jan 24, 2020 at 03:25:42PM +0100, Ingo Schwarze wrote: > Hi, > > Claus Assmann wrote on Fri, Jan 24, 2020 at 09:25:27AM +0100: > > On Thu, Jan 23, 2020, Landry Breuil wrote: > > >> have a look at the pkg-readme provided by the package. > > > I didn't find a hint about pkg-readmes in the man pages :-( > >$ man -k any=pkg-readmes > update-plist(1) - create or update packing-list(s) for a given port > bsd.port.mk(5) - ports tree master Makefile fragment > packages(7) - overview of the binary package system > > Given that bsd.port.mk(5) and update-plist(1) are pages for porters > rather than for users, it indeed seems to me that references to > pkg-readmes are rather sparse. > > Also, the reference in packages(7) isn't all that prominent: > > https://man.openbsd.org/packages#Packages_install_to_/usr/local > > > (I also ran pkg_info to find out more about the firefox port). > > Indeed, i think pkg_add(1) and pkg_info(1) are among the first > pages users are likely to look at when searching for information > about packages. > > I think pkg_add(1) should list the most important directories > it modifies, and pkg-readmes are certainly among those. > And pkg_info(1) should list the most important directories > containing information about packages. Again, pkg-readmes is > among those, even though pkg_info(1) itself does not access it. > > I admit FILES sections tend to be slightly repetitive - not just > in this case but in general because the files are typically also > mentioned in the DESCRIPTION. But i still think listing them > concisely, with a one-line description each, is helpful. Just > like in this case, not all files are necessarily mentioned > elsewehere, and such a section provides a nice, quick overview. > > OK? > Ingo > > > > And since the installation was automated, I also missed the hint > > when firefox was installed -- my fault, thanks for pointing me to > > it - that solved the problem. > > > Index: pkg_add.1 > === > RCS file: /cvs/src/usr.sbin/pkg_add/pkg_add.1,v > retrieving revision 1.162 > diff -u -p -r1.162 pkg_add.1 > --- pkg_add.1 4 Jan 2020 15:13:54 - 1.162 > +++ pkg_add.1 24 Jan 2020 14:14:59 - > @@ -820,6 +820,22 @@ but it is searched before > .Ev PKG_PATH > and waives any kind of signature checking. > .El > +.Sh FILES > +.Bl -tag -width /etc/installurl > +.It Pa /etc/installurl > +default mirror server for package download > +.It Pa /etc/signify/*-pkg.pub > +public keys for package verification with > +.Xr signify 1 > +.It Pa /usr/local/ > +default file system to install packages in > +.It Pa /usr/local/share/doc/pkg-readmes/ > +.Ox Ns -specific > +information about individual packages > +.It Pa /var/db/pkg/ > +database of installed > +.Xr packages 7 > +.El > .Sh SEE ALSO > .Xr ftp 1 , > .Xr pkg_create 1 , > Index: pkg_info.1 > === > RCS file: /cvs/src/usr.sbin/pkg_add/pkg_info.1,v > retrieving revision 1.60 > diff -u -p -r1.60 pkg_info.1 > --- pkg_info.14 Jul 2019 15:25:16 - 1.60 > +++ pkg_info.124 Jan 2020 14:14:59 - > @@ -269,6 +269,15 @@ but it is searched before > .Ev PKG_PATH > and waives any kind of signature checking. > .El > +.Sh FILES > +.Bl -tag -width /var/db/pkg/ > +.It Pa /usr/local/share/doc/pkg-readmes/ > +.Ox Ns -specific > +information about individual packages > +.It Pa /var/db/pkg/ > +database of installed > +.Xr packages 7 > +.El > .Sh TECHNICAL DETAILS > Package info is either extracted from package files named on the > command line, or from already installed package information > I'm okay with this. Note that in actuality, pkg_add(1) itself tells you about pkg-readmes... :)
Re: reference pkg-readmes in manual pages
Hi, Claus Assmann wrote on Fri, Jan 24, 2020 at 05:18:14PM +0100: > On Fri, Jan 24, 2020, Ingo Schwarze wrote: >> Claus Assmann wrote on Fri, Jan 24, 2020 at 09:25:27AM +0100: >>> I didn't find a hint about pkg-readmes in the man pages :-( >>$ man -k any=pkg-readmes > I only tried > man -k pkg-readmes Right, the reason Nm,Nd= is the default with -k and not any= is that any= can be quite noisy (and in addition, there is tradition). The reason i used any= here anyway was that i wanted to check completeness of manual pages rather than merely read some. If you want to know what a file is that doesn't have its own manual page, try Pa=. Compare $ man -k Pa=words # explains /usr/share/dict/words $ man -k words # a small amount of random stuff $ man -k Nm,Nd=words# the same $ man -k any=words # lots of noise Yours, Ingo
Re: reference pkg-readmes in manual pages
On Fri, Jan 24, 2020, Ingo Schwarze wrote: > Claus Assmann wrote on Fri, Jan 24, 2020 at 09:25:27AM +0100: > > I didn't find a hint about pkg-readmes in the man pages :-( >$ man -k any=pkg-readmes Two mails to the openbsd lists and I learned three new things :-) I only tried man -k pkg-readmes Thanks a lot for the help and the enhancement of the documentation. -- Address is valid for this mailing list only, please do not reply to it direcly, but to the list.
Re: reference pkg-readmes in manual pages
On Fri, Jan 24, 2020 at 03:25:42PM +0100, Ingo Schwarze wrote: > Hi, > > Claus Assmann wrote on Fri, Jan 24, 2020 at 09:25:27AM +0100: > > On Thu, Jan 23, 2020, Landry Breuil wrote: > > >> have a look at the pkg-readme provided by the package. > > > I didn't find a hint about pkg-readmes in the man pages :-( > >$ man -k any=pkg-readmes > update-plist(1) - create or update packing-list(s) for a given port > bsd.port.mk(5) - ports tree master Makefile fragment > packages(7) - overview of the binary package system > > Given that bsd.port.mk(5) and update-plist(1) are pages for porters > rather than for users, it indeed seems to me that references to > pkg-readmes are rather sparse. > > Also, the reference in packages(7) isn't all that prominent: > > https://man.openbsd.org/packages#Packages_install_to_/usr/local > > > (I also ran pkg_info to find out more about the firefox port). > > Indeed, i think pkg_add(1) and pkg_info(1) are among the first > pages users are likely to look at when searching for information > about packages. > > I think pkg_add(1) should list the most important directories > it modifies, and pkg-readmes are certainly among those. > And pkg_info(1) should list the most important directories > containing information about packages. Again, pkg-readmes is > among those, even though pkg_info(1) itself does not access it. > > I admit FILES sections tend to be slightly repetitive - not just > in this case but in general because the files are typically also > mentioned in the DESCRIPTION. But i still think listing them > concisely, with a one-line description each, is helpful. Just > like in this case, not all files are necessarily mentioned > elsewehere, and such a section provides a nice, quick overview. > > OK? > Ingo > > > > And since the installation was automated, I also missed the hint > > when firefox was installed -- my fault, thanks for pointing me to > > it - that solved the problem. > > > Index: pkg_add.1 > === > RCS file: /cvs/src/usr.sbin/pkg_add/pkg_add.1,v > retrieving revision 1.162 > diff -u -p -r1.162 pkg_add.1 > --- pkg_add.1 4 Jan 2020 15:13:54 - 1.162 > +++ pkg_add.1 24 Jan 2020 14:14:59 - > @@ -820,6 +820,22 @@ but it is searched before > .Ev PKG_PATH > and waives any kind of signature checking. > .El > +.Sh FILES > +.Bl -tag -width /etc/installurl > +.It Pa /etc/installurl > +default mirror server for package download > +.It Pa /etc/signify/*-pkg.pub > +public keys for package verification with > +.Xr signify 1 > +.It Pa /usr/local/ > +default file system to install packages in > +.It Pa /usr/local/share/doc/pkg-readmes/ > +.Ox Ns -specific > +information about individual packages > +.It Pa /var/db/pkg/ > +database of installed > +.Xr packages 7 > +.El > .Sh SEE ALSO > .Xr ftp 1 , > .Xr pkg_create 1 , > Index: pkg_info.1 > === > RCS file: /cvs/src/usr.sbin/pkg_add/pkg_info.1,v > retrieving revision 1.60 > diff -u -p -r1.60 pkg_info.1 > --- pkg_info.14 Jul 2019 15:25:16 - 1.60 > +++ pkg_info.124 Jan 2020 14:14:59 - > @@ -269,6 +269,15 @@ but it is searched before > .Ev PKG_PATH > and waives any kind of signature checking. > .El > +.Sh FILES > +.Bl -tag -width /var/db/pkg/ > +.It Pa /usr/local/share/doc/pkg-readmes/ > +.Ox Ns -specific > +information about individual packages > +.It Pa /var/db/pkg/ > +database of installed > +.Xr packages 7 > +.El > .Sh TECHNICAL DETAILS > Package info is either extracted from package files named on the > command line, or from already installed package information > I'm fine with pkg_add and pkg_info patches, that should answer lot of frequent asked questions.
reference pkg-readmes in manual pages
Hi, Claus Assmann wrote on Fri, Jan 24, 2020 at 09:25:27AM +0100: > On Thu, Jan 23, 2020, Landry Breuil wrote: >> have a look at the pkg-readme provided by the package. > I didn't find a hint about pkg-readmes in the man pages :-( $ man -k any=pkg-readmes update-plist(1) - create or update packing-list(s) for a given port bsd.port.mk(5) - ports tree master Makefile fragment packages(7) - overview of the binary package system Given that bsd.port.mk(5) and update-plist(1) are pages for porters rather than for users, it indeed seems to me that references to pkg-readmes are rather sparse. Also, the reference in packages(7) isn't all that prominent: https://man.openbsd.org/packages#Packages_install_to_/usr/local > (I also ran pkg_info to find out more about the firefox port). Indeed, i think pkg_add(1) and pkg_info(1) are among the first pages users are likely to look at when searching for information about packages. I think pkg_add(1) should list the most important directories it modifies, and pkg-readmes are certainly among those. And pkg_info(1) should list the most important directories containing information about packages. Again, pkg-readmes is among those, even though pkg_info(1) itself does not access it. I admit FILES sections tend to be slightly repetitive - not just in this case but in general because the files are typically also mentioned in the DESCRIPTION. But i still think listing them concisely, with a one-line description each, is helpful. Just like in this case, not all files are necessarily mentioned elsewehere, and such a section provides a nice, quick overview. OK? Ingo > And since the installation was automated, I also missed the hint > when firefox was installed -- my fault, thanks for pointing me to > it - that solved the problem. Index: pkg_add.1 === RCS file: /cvs/src/usr.sbin/pkg_add/pkg_add.1,v retrieving revision 1.162 diff -u -p -r1.162 pkg_add.1 --- pkg_add.1 4 Jan 2020 15:13:54 - 1.162 +++ pkg_add.1 24 Jan 2020 14:14:59 - @@ -820,6 +820,22 @@ but it is searched before .Ev PKG_PATH and waives any kind of signature checking. .El +.Sh FILES +.Bl -tag -width /etc/installurl +.It Pa /etc/installurl +default mirror server for package download +.It Pa /etc/signify/*-pkg.pub +public keys for package verification with +.Xr signify 1 +.It Pa /usr/local/ +default file system to install packages in +.It Pa /usr/local/share/doc/pkg-readmes/ +.Ox Ns -specific +information about individual packages +.It Pa /var/db/pkg/ +database of installed +.Xr packages 7 +.El .Sh SEE ALSO .Xr ftp 1 , .Xr pkg_create 1 , Index: pkg_info.1 === RCS file: /cvs/src/usr.sbin/pkg_add/pkg_info.1,v retrieving revision 1.60 diff -u -p -r1.60 pkg_info.1 --- pkg_info.1 4 Jul 2019 15:25:16 - 1.60 +++ pkg_info.1 24 Jan 2020 14:14:59 - @@ -269,6 +269,15 @@ but it is searched before .Ev PKG_PATH and waives any kind of signature checking. .El +.Sh FILES +.Bl -tag -width /var/db/pkg/ +.It Pa /usr/local/share/doc/pkg-readmes/ +.Ox Ns -specific +information about individual packages +.It Pa /var/db/pkg/ +database of installed +.Xr packages 7 +.El .Sh TECHNICAL DETAILS Package info is either extracted from package files named on the command line, or from already installed package information
