[gentoo-dev] Re: readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable

[Duncan <1i5t5.duncan@cox.net>]

Dan Douglas posted on Thu, 31 Jan 2013 09:22:04 -0600 as excerpted:

> On Sunday, January 27, 2013 03:00:21 PM Pacho Ramos wrote:
>> [Discussion of DOC_CONTENTS var]
>> 
> Why does this eclass even exist? Everything that it does can be done
> directly in an ebuild in a couple lines of code, except in a much less
> ugly manner. It doesn't help to generalize anything. If you want to copy
> a file and call dodoc then just do it, don't write a pointless wrapper
> that people then have to go and look up what it does in order to read
> your ebuilds.

You appear to be missing the point.  The goal of the eclass isn't to copy 
a file; as you say, that's covered.  Instead, the current problem is the 
common PKG_POSTINST messages that appear time and time again as people 
upgrade, that are important the first time and for reference, but after 
the first time, they're mostly just noise that users learn to ignore as 
they've seen them many times before.  Of course, ignoring such messages 
becomes a problem when an ebuild actually prints something new and 
useful, and VERY important (like reconfigure before you reboot or your 
reboot won't go well!), as the maintainer now has no way to get THOSE 
messages across.

So we get solutions like enews, and PKG_PRETEND, and ebuilds requiring 
I_KNOW_WHAT_I_AM_DOING vars, etc, so they don't end up with unbootable 
systems because they ignored the one important new message in all the 
"noise" of messages they'd read a dozen times over, already.

But arguably, those are solutions to different problems.  The real 
problem here is that we repeat the same messages every time a package is 
installed, until they're just "noise" that many users eventually simply 
ignore, leaving package maintainers without a /reasonable/ way to 
communicate the really important stuff.

That's the problem this eclass is trying to solve, providing a(n eclass 
standardized) way for maintainers to print important messages the first 
time they apply, but also to log them to a common location for reference 
purposes so a user can go back and look them up a year and several 
updates later, if for example they mistakenly restored an old copy from 
backup, and end up needing to redo whatever once again.

Basically, a better elog.

It seems to have generally been agreed that such functionality would be 
useful and should be standardized in an eclass (or new EAPI, but an eclass 
is faster to deploy if it does the job).  Now the discussion is centering 
around getting it right.  Formatting the messages handed to it by default 
or not.  Cleaning up the proposed code.  Tweaking for corner cases not 
yet covered but easily covered with a small change now before there's 200 
packages calling it that must be changed if the way it's called changes 
slightly to accommodate that corner-case.  Etc.

> Funnily, looking at the implementation of elog, it appears to already
> mangle its input by a pass of `echo -e', pointlessly reading lines and
> joining them back together again repeatedly. This is just horrible! I
> don't even...

So you saw the comparison to elog, handling a message given it, and 
/still/ missed that the eclass was to create a NEW file in a standardized 
location, putting into it the content passed in, not simply copy an 
existing file?  Missed the forest for all the trees. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman