Re: [gentoo-dev] About using a CONFIGURATION (or SETUP) file under /usr/share/doc for configuration information

[Zac Medico]

On 01/07/2013 05:35 PM, Michael Mol wrote:
> On Sun, Jan 6, 2013 at 8:54 PM, Zac Medico <zmedico@g.o> wrote:
>> On 01/06/2013 05:36 PM, Michael Mol wrote:
>>>
>>> On Jan 6, 2013 8:32 PM, "Zac Medico" <zmedico@g.o
>>> <mailto:zmedico@g.o>> wrote:
>>>>
>>>> On 01/06/2013 01:04 AM, Ralph Sennhauser wrote:
>>>>> On Fri, 4 Jan 2013 23:34:59 -0600
>>>>> Donnie Berkholz <dberkholz@g.o <mailto:dberkholz@g.o>>
>>> 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.

A version header that the package manager can parse, should do the trick.

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

Frequent trivial modification should probably be avoided. OTOH, the
maintainer should not be ashamed of making occasion small modifications,
in order to improve the content quality.

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


-- 
Thanks,
Zac