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

[Mathieu Arnold]

+--On 26 septembre 2014 08:31:43 +0200 Matthias Andree
<mandree at FreeBSD.org> wrote:
| 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.htm
|> l#plist-keywords-sample
| 
| yeah, quite explicitly states that if the file isn't named *.sample,
| @sample does not work.

It states that the sample file have to be named .sample, so that it's
consistent across every package.

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

It also states, in a *big* gray box, that if for historical reasons
(meaning it's always been there and it can't be changed) you can use bla
bla bla.

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

All keywords are documented. How to use one, how to write one.

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

Like I said, it *is* documented, but it is true that if you don't even
bother to look for the documentation, you won't find it.

-- 
Mathieu Arnold