From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id D7B9F138354 for ; Tue, 8 Jan 2013 01:36:23 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 4B90621C122; Tue, 8 Jan 2013 01:36:13 +0000 (UTC) Received: from mail-oa0-f51.google.com (mail-oa0-f51.google.com [209.85.219.51]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id A5D4021C133 for ; Tue, 8 Jan 2013 01:35:24 +0000 (UTC) Received: by mail-oa0-f51.google.com with SMTP id n12so18583606oag.24 for ; Mon, 07 Jan 2013 17:35:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=7mv5bfsA3ESwHwo/kjGc87/Q4z7y3rSSTKdy77uCLeY=; b=DgNNc2fkJEkNWsPapw8OApd08LluOnVYui+wARVmKI84fNNz2FZqgIHlGqLaA37Vah pCsIWjh/1uGcB3oIHdnTF7b1DJz7O2UkabrC+XVlZV+8ql+p56KZ8QgvLfue8QHBczpq Jy7N6hN+/M4UeEu50ohzp9ZSZnwHFpfwfw6VzlHY7OayX6zXEMk3UEmdgOFwxEzd+nTR 7+qRnAUa3f1aW1IqF+V7vS2ozp7uh3VLAKAFQWpUpZfnQ35hDDkc39S6WCVqg+cncI+B nhI3jtkqBYi+rtZ+6gUf8AnNTXU17SoLa0U2JzZK7imSUV+Bbsy7wXMJTlFRmoIBvQyL jnFQ== Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 Received: by 10.182.130.38 with SMTP id ob6mr44816996obb.100.1357608923845; Mon, 07 Jan 2013 17:35:23 -0800 (PST) Received: by 10.76.20.243 with HTTP; Mon, 7 Jan 2013 17:35:23 -0800 (PST) In-Reply-To: <50EA2AE2.7010002@gentoo.org> References: <1356168400.2133.69.camel@belkin4> <20130105053459.GB9570@comet.hsd1.mn.comcast.net> <20130106100405.3c2e516e@sera-20.lan> <50EA2531.90804@gentoo.org> <50EA2AE2.7010002@gentoo.org> Date: Mon, 7 Jan 2013 20:35:23 -0500 Message-ID: Subject: Re: [gentoo-dev] About using a CONFIGURATION (or SETUP) file under /usr/share/doc for configuration information From: Michael Mol To: gentoo-dev@lists.gentoo.org Content-Type: text/plain; charset=UTF-8 X-Archives-Salt: 1c7ccfa2-9b4a-4e85-9459-f51abfebf094 X-Archives-Hash: 93a3df61565130c94dcc8ff8e9844852 On Sun, Jan 6, 2013 at 8:54 PM, Zac Medico wrote: > On 01/06/2013 05:36 PM, Michael Mol wrote: >> >> On Jan 6, 2013 8:32 PM, "Zac Medico" > > wrote: >>> >>> On 01/06/2013 01:04 AM, Ralph Sennhauser wrote: >>> > On Fri, 4 Jan 2013 23:34:59 -0600 >>> > Donnie Berkholz > >> wrote: >>> > >>> >> On 10:26 Sat 22 Dec , Pacho Ramos wrote: >>> >>> Hello >>> >>> >>> >>> After seeing: >>> >>> https://bugs.gentoo.org/show_bug.cgi?id=440214 >>> >>> >>> >>> Looking to a lot of its blockers shows that we are using "elog" >>> >>> messages for informing people about configuration (like pointing >>> >>> people to external links to get proper way of configuring things, >>> >>> tell them to add to some system groups...). I thought that maybe >>> >>> this kind of information could be simply included in a canonical >>> >>> file under /usr/share/doc/ package dir called, for example, >>> >>> CONFIGURATION or SETUP. We would them point people (now with a news >>> >>> item, for the long term provably a note to handbook to newcomers >>> >>> would be nice) to that file to configure their setups. The main >>> >>> advantages I see: >>> >>> - We will flood less summary.log ;) >>> >>> - The information to configure the package is always present while >>> >>> package is installed, now, if we remove merge produced logs, people >>> >>> will need to reemerge the package or read directly the ebuild >>> >>> >>> >>> What do you think? >>> >> >>> >> Bikeshedding ... would go with README.gentoo, because people are >>> >> already used to looking for README files. Every time we can eliminate >>> >> Gentoo-specific weirdness, we should. >>> >> >>> > >>> > See the documentation for README.Debian[1], most importantly the >>> > example. ;) >>> > >>> > I'd say we should handle it the same as Debian does. >>> >>> README.gentoo sounds good to me. >>> >>> > What could we possibly gain from doing it differently? >>> >>> Does Debian have a postinst message, like the proposed eclass would >>> generate? Do you agree that a postinst message is desirable feature? >>> >>> > [1] http://www.debian.org/doc/manuals/maint-guide/dother.en.html#readme >>> > >>> -- >>> Thanks, >>> Zac >>> >> >> If we had README.gentoo, I'd love it if Portage alerted me as those >> files changed. > > Even if it's just whitespace or formatting changes? Maybe it's better to > let the ebuild do version comparisons and decide whether to generate a > message based on that. I see two solutions to that: 1) Define a format for the file, so that substantive difference can be programmatically discerned from non-substantive differences. I don't have a good proposal for a particular format. 2) Make it so that an author of a README.gentoo file is well aware that any change he makes will potentially annoy all his users if the change isn't substantive. Frankly, (2) seems entirely reasonable. And at the same time, being able to look at version history for README.gentoo files would be extraordinarily enlightening. -- :wq