[gentoo-dev] Re: Readme files for portage (was: A nice idea to improve portage)

[D. Tuinstra]

Michael Cummings wrote:

> On Wed, Jun 11, 2003 at 11:37:02AM +0100, MooktaKiNG wrote:
>> Another good reason to have a README is becuase sometimes people
>> want to know more about a program. Without having to install it.
>>
>> If they can learn about the program before they install. They are
>> more aware of how hard/easy the installtion is.
>
> I thought that was one of the reasons the source URL shows up in a
> search. It's how I've always checked to see what a package does.
> README files, imo, are great in theory but put additional
> maintenance strain on a dev. Just my two euros,
>
> Mike

As I see the original proposal, it was to give users essential
post-install information regarding any further steps they need to
take. This kind of information is different from pre-emerge info
that a user uses to decide the desirability of a package.

Pre-emerge info
---------------
Still, a small README could be valuable in some situations. For
example: "This package is included in portage for backwards
compatability for systems that have to interoperate with
MegaCruft's General Ledger FPS. If you don't have to do this you
may wish to consider <KDE-alternate> or <GNOME-alternate>. They
provide the same features within a modern UI, don't hog the CPU,
and don't require you to do manual post-emerge steps. And BTW, the
official site is a pathetic mass of marketing-speak, go to the
user-group page at <URL> instead." This shouldn't be too much of a
dev burden if it's optional and intended to communicate info that
wouldn't be found on an official web page.

A pre-emerge README feature runs the risk of encouraging
editorializing (as above :-), but hey, as long as its kept
reasonable that's part of the fun.

Post-emerge info
----------------
I'm all for it. My wish list: append each package's message to a
file named something like "emerge_messages_<timestamp>". These
would be stored in a standard location relative to the user running
emerge. At the end of the emerge, if the file is empty portage
deletes it and no mention is made of it. If the file is nonempty,
portage displays a standard message directing the user to read it.

Two new emerge commands: 'einfomsg' to write a string to the message
file; 'einfocat' to cat a file to it.

Messages written to the file should be no more than ~25 lines of
text each, with some standard header (e.g., line of dashes, ebuild
name, line of dashes). If 25 lines isn't enough room, the message
should direct the user to more instructions in
/usr/share/doc/<package>.

  --Dwight Tuinstra




--
gentoo-dev@g.o mailing list