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

[Michael Mol]

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.

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