From owner-freebsd-ports@FreeBSD.ORG Fri Sep 26 07:03:07 2014 Return-Path: Delivered-To: freebsd-ports@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E887B309; Fri, 26 Sep 2014 07:03:07 +0000 (UTC) Received: from mout.gmx.net (mout.gmx.net [212.227.15.19]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mout.gmx.net", Issuer "TeleSec ServerPass DE-1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 7F7547BB; Fri, 26 Sep 2014 07:03:07 +0000 (UTC) Received: from mandree.no-ip.org ([78.48.210.9]) by mail.gmx.com (mrgmx001) with ESMTPSA (Nemesis) id 0LlDb4-1Y6Bo822ZK-00b4hw; Fri, 26 Sep 2014 09:03:02 +0200 Received: from [IPv6:::1] (localhost6.localdomain6 [IPv6:::1]) by apollo.emma.line.org (Postfix) with ESMTP id 1072A23D35C; Fri, 26 Sep 2014 09:03:01 +0200 (CEST) Message-ID: <54250FA5.7080403@gmx.de> Date: Fri, 26 Sep 2014 09:03:01 +0200 From: Matthias Andree User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.1.2 MIME-Version: 1.0 To: Mathieu Arnold , Matthias Andree , ports-committers@freebsd.org Subject: Re: lack of framework and pkg documentation References: <201409251827.s8PIRur9020228@svn.freebsd.org> <54246002.2080408@FreeBSD.org> <5425084F.9020205@FreeBSD.org> <725C3E552E769ADCC3E4E150@atuin.in.mat.cc> In-Reply-To: <725C3E552E769ADCC3E4E150@atuin.in.mat.cc> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:j+7LGJ/LMpYBjuepgxhyVBshl6jWL9ZNesPPqIhJ7eGTvyXCX+W IOHTqv2weYDQ+25r0lic+uIYOIk1QeoU4q2U090SfNXp09zppYjCGTLekL53YUvz3799O28 POIt1vXfkkuOm2BUtVIQ/zMxrddbYXo4+bzuMJYHAAzmas2w+gBnuR0lriXsGNVuerV/rq7 ZSDheXECzIjirkf2IWJTw== X-UI-Out-Filterresults: notjunk:1; Cc: freebsd-ports@FreeBSD.org, portmgr@FreeBSD.org X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 26 Sep 2014 07:03:08 -0000 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: Thank you.