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

[oford]

On Wed, 2003-06-11 at 08:24, D. Tuinstra wrote:
> 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>.

It should also state which ebuild it belongs to in a very prominent
place.  I know it sounds obvious but that kind of detail is important :)

-- 
Owen Ford <oford@×××.net>