Hi Michael, Michael Reed wrote on Sat, Sep 12, 2015 at 06:02:36PM -0400:
> This patch consists of three small changes and one large one. Hum, mixing small and large changes is not a very good idea. When proposing a large change, it is best to send one self-contained patch doing nothing but that large change. And before spending a lot of time on a large patch, it may be useful to ask beforehand whether it's wanted (preferably directly to the developer in charge of the area, not on tech@, including a small patch just demonstrating the idea). Regarding manuals, you can also ping me if you fail to get feedback otherwise or simply need general guidance; usually (not always) i come round to answering such queries. When i don't and it's important, try again after about ten days. > The small changes are as follows: > > - In two places, replaced `...' style quoting with Sq, which is used > throughout the manual. > - added missing comma after `e.g.' > - fixed spelling of `licencing' -> `licensing' Committed. > The large change is converting the list in DIAGNOSTICS from this: > > .Bl -diag > .It ... > ... > > to this: > > .Bl -ohang > .It Sy ... > ... > > The old style resulted in item bodies starting on the same line as the > title, while the new style doesn't. This idea was taken from mandoc.1, > and I find it more readable, but I'll drop the change if people don't > agree. I think it looks a bit better, but what we have isn't wrong either, and not even unusual. If ports people agree, i'm fine with changing it, but nobody spoke up so far and i won't commit that part just like this, without any feedback from ports people. By the way, bsd.port.mk(5) is one of the relatively few pages where general markup quality is far below OpenBSD standards. Yours, Ingo > Index: bsd.port.mk.5 > =================================================================== > RCS file: /cvs/src/share/man/man5/bsd.port.mk.5,v > retrieving revision 1.418 > diff -u -p -r1.418 bsd.port.mk.5 > --- bsd.port.mk.5 30 Jul 2015 08:03:50 -0000 1.418 > +++ bsd.port.mk.5 12 Sep 2015 21:42:03 -0000 > @@ -216,9 +216,11 @@ or > .Va package , > clean subpackages as well. > .It Va packages > -Shorthand for `sub package'. > +Shorthand for > +.Sq sub package . > .It Va all > -Shorthand for `work flavors packages plist'. > +Shorthand for > +.Sq work flavors packages plist . > .El > .It Ar clean-depends > Shorthand for make clean=depends. > @@ -858,7 +860,7 @@ may not handle flavor and multi-packages > .It Ar verbose-show > Similar to > .Ar show , > -except that it prefixes each value with the variable name, e.g. > +except that it prefixes each value with the variable name, e.g., > .Li VAR=value . > Also note that it does not show undefined variables, contrary to > .Ar show > @@ -3095,23 +3097,23 @@ Note that some of these messages are act > commands, but grouped here for convenience: easier to look for in > .Xr dpb 1 Ns 's > logs. > -.Bl -diag > -.It "Discovered old directory in ..." > +.Bl -ohang > +.It Sy "Discovered old directory in ..." > This message comes from > .Xr make-plist 1 . > A directory was found in the PLIST that used to be needed but is no longer, > because it's now accounted for through dependencies. > Indicates the old directory has been removed. > -.It "Error: change in plist between ..." > +.It Sy "Error: change in plist between ..." > Error message comes from > .Xr register-plist 1 . > -.It "Error: duplicate item in packing-list" > +.It Sy "Error: duplicate item in packing-list" > Error message comes from > .Xr pkg_create 1 , > and will result from incorrect packing-lists, such as including several > fragments with the same file, or having incorrect > .Ev PKG_ARGS-sub . > -.It "Error: Libraries in packing-lists...and libraries from installed > packages don't match" > +.It Sy "Error: Libraries in packing-lists...and libraries from installed > packages don't match" > The ports tree and the installed packages are out-of-sync. > Mixing library information from both sources might produce packages that > can't > be installed elsewhere. > @@ -3121,18 +3123,18 @@ Developers may use > .Ev PKG_CREATE_NO_CHECKS > instead, assuming they understand the implications. > See print-package-args (wantlib-args) for details. > -.It "Fatal: can't flavor a SUBDIR" > +.It Sy "Fatal: can't flavor a SUBDIR" > A dependency mentions top_subdir,flavor. > Flavor would then be ignored, as it is only applied to individual ports. > -.It "Fatal: can't subpackage a SUBDIR" > +.It Sy "Fatal: can't subpackage a SUBDIR" > A dependency mentions top_subdir,-sub. > Subpackage would then be ignored, as it is only applied to individual ports. > -.It "Fatal: flavor should never start with a digit" > +.It Sy "Fatal: flavor should never start with a digit" > This would utterly confuse > .Xr pkg_add 1 . > See > .Xr packages-specs 7 . > -.It "Fatal: inclusion of <file> from <file>" > +.It Sy "Fatal: inclusion of <file> from <file>" > .Pa bsd.port.mk > or > .Pa bsd.port.subdir.mk > @@ -3144,7 +3146,7 @@ resulting in a double inclusion. > This would lead to weird results, such as > .Ev PKG_ARGS > being defined twice. > -.It "Fatal: SUBPACKAGES should always begin with -: <offending list>" > +.It Sy "Fatal: SUBPACKAGES should always begin with -: <offending list>" > That is the only way to differentiate between > .Ev FLAVOR > and > @@ -3152,33 +3154,33 @@ and > in > .Xr pkgpath 7 > specifications. > -.It "Fatal: building ports requires correctly installed X11" > +.It Sy "Fatal: building ports requires correctly installed X11" > All file sets of the base OS, including xenocara, must be installed > before building ports. > -.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink" > +.It Sy "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink" > /usr/local/lib/X11/app-defaults is distributed as a symlink in the > xshare*.tgz file set. > If xenocara was not fully installed before packages were added, it may > have been created as a directory instead. > -.It "Fatal: the licencing info for <pkgname> is incomplete..." > +.It Sy "Fatal: the licensing info for <pkgname> is incomplete..." > Every port must have explicit defines of all > .Ev PERMIT_* > values. > -.It "Fatal: Use 'env FLAVOR=flavor make' instead" > +.It Sy "Fatal: Use 'env FLAVOR=flavor make' instead" > Arguments specified after > .Xr make 1 > are hardcoded for all recursive sub-makes, and very difficult to override. > Thus, > .Ev FLAVOR > must be specified in the environment instead. > -.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead" > +.It Sy "Fatal: Use 'env SUBPACKAGE=-sub make' instead" > Arguments specified after > .Xr make 1 > are hardcoded for all recursive sub-makes, and very difficult to override. > Thus, > .Ev SUBPACKAGE > must be specified in the environment instead. > -.It "ldconfig: <dir>: No such file or directory" > +.It Sy "ldconfig: <dir>: No such file or directory" > Usually produced by > .Xr pkg_add 1 > running > @@ -3194,7 +3196,7 @@ will later complain after the directory > The bogus tool should be fixed to conform to > .Ox > usage. > -.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH> > +.It Sy LIB_DEPENDS <spec> not needed for <FULLPKGPATH> > There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS. > Thus, the LIB_DEPENDS won't turn into a @depends line in the created package. > This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS: > @@ -3206,14 +3208,14 @@ Also, will happen for multi-packages, wh > a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE). > .Pp > See print-package-args (lib-depends-args) for details. > -.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub" > +.It Sy "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub" > .Ev FULLPKGNAME-sub > has been explicitly defined by the port, instead of relying on the default, > but no value of > .Ev FULLPKGPATH-sub > has been given. > This is often an error. > -.It "Warning: symlink(s) point to non existent file." > +.It Sy "Warning: symlink(s) point to non existent file." > Warning message comes from > .Xr pkg_create 1 . > The symlink resides in the fake area, under > @@ -3224,7 +3226,7 @@ which obviously won't exist under > at the time > .Li make package > is run. > -.It "Warning: @option no-default-conflict with no @conflict" > +.It Sy "Warning: @option no-default-conflict with no @conflict" > Warning message comes from > .Xr pkg_create 1 . > Most packages that waive "default-conflict" will have explicit conflict > markers > @@ -3238,7 +3240,7 @@ Any other version or > won't conflict. > This is generally an error, apart from very few ports like > .Pa devel/autoconf/* . > -.It "groff produced empty result for <manpage>..." > +.It Sy "groff produced empty result for <manpage>..." > Warning message comes from > .Xr pkg_create 1 . > Manpages are automatically formatted with >
