lack of framework and pkg documentation (was: svn commit: r369281 - in head/dns: dnsmasq dnsmasq-devel)

[Matthias Andree]

Am 25.09.2014 um 20:33 schrieb Bryan Drewery:
> On 9/25/2014 1:27 PM, Matthias Andree wrote:
>> Author: mandree
>> Date: Thu Sep 25 18:27:56 2014
>> New Revision: 369281
>> URL: http://svnweb.freebsd.org/changeset/ports/369281
>> QAT: https://qat.redports.org/buildarchive/r369281/
>>
>> Log:
>>   Update to new upstream version 2.72, disabling dnsmasq-devel again.
>>   
>>   Remove @dir* stuff from pkg-plist.  @sample isn't documented properly
>>   and isn't up to handling files with non-.sample suffix, so stay
>>   away from that part of pkg-plist.
> 
> https://www.freebsd.org/doc/en/books/porters-handbook/plist-config.html
> https://www.freebsd.org/doc/en/books/porters-handbook/plist-keywords.html#plist-keywords-sample

yeah, quite explicitly states that if the file isn't named *.sample,
@sample does not work.

plist-keywords.html does not appear to suggest a way to have two
arguments for a keyword, or to use @sample(.example) to provide a
different extension...

The other issue I'm having with that is that the technical side of
Keywords/* - it's not documented or visible how these are actually used,
grep -ri keywords Mk comes up mostly empty, there's only the definition
- and it's a leftover from the times when we still had awk scripts to
wire this into pkg_create/pkg_install.

TODO(portmgr): please remove the leftover KEYWORDS?= from Mk/bsd.port.mk
near line 1370.

So it remains unclear if the Keywords stuff is rigged in by the
framework, is hardwired into pkg, or thereabouts.

grepping pkg sources reveals this:

> $ grep -r Keywords /var/tmp/usr/ports.svn/ports-mgmt/pkg/work/ 
> work/pkg-1.3.8/libpkg/pkg_ports.c:	    "%s/Keywords/%s.yaml", keyword_dir, keyword);
> work/pkg-1.3.8/libpkg/pkg_ports.c:	    "%s/Keywords/%s.ucl", keyword_dir, keyword);

But then pkg info -l pkg | zgrep -ri keywords on the installed files
comes up empty.

So again, missing documentation. :-(

TODO(pkg maintainers, portmgr): We really need to have documentation and
specification in place and reviewed
*before someone starts implementing*
code in a publicly released package.

And I mean documentation (for the user) *and* specification.