lack of framework and pkg documentation

[Matthias Andree]

Am 26.09.2014 um 09:37 schrieb Mathieu Arnold:

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

No harm meant - and I usually appreciate your efforts, but this post was
a disservice to the project.

I complained quite explicitly that the hardwired link between pkg and
the ports framework is ONLY visible in the source code, and I showed how
I tried to find the information and how that failed.

Now if you would read my post before brushing it off, that would be
greatly appreciated.

If I read these diverse ways of wording "we have it documented you only
need to look" then I get the impression that neither bapt nor bdrewery
nor you care that we get a complete documentation in places where people
look, so that people get a chance of understanding the entire ports +
pkg framework without resorting to reading source code.

All three of you could derive two pieces of info from my posts to
improve our overall professional impression we're making, and to improve
framework transparency and documentation quality:

1. figure how and where people try to find information that are not
familiar with pkg's innards;

2. figure what bits of information need to be added for completeness.

And please don't pretend that

>      PLIST_KEYWORDS_DIR: string
>                   Directory containing definitions of plist keywords.
>                   Default: not set.

(from pkg.conf) were "complete" or correct - there are implicit defaults:
<https://github.com/freebsd/pkg/blob/1.3.8/libpkg/pkg_ports.c#L867>

Thank you.