Обсуждение: INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)
On Sep 20, Bruce Momjian mentioned: > I agree our INSTALL is very large. Is there some way we can simplify > the install process? On the one hand a database server is probably not your everyday ./configure && make && make install program you get from freshmeat and you do want to put some time into a proper installation. On the other hand the INSTALL file is really way too long and makes for unpleasant reading. Here are a couple of ideas. * Chapter 2 "Ports" should be moved to the README file (has nothing to do with the actual installation). * Move the gory details of item 5 (flex) to a separate file (README.flex). * Move the locale stuff into a separate file. * Same with Kerberos * Move the release notes at the end to CHANGELOG. That should make the file somewhat smaller, then also it is really to verbose at times and is formatted really oddly, at least on my system. Okay, now I really went out of my way and redid the whole thing. You'll find the result attached. This is merely an idea of what I would consider simpler. I removed some inconsistencies, things that were unnecessary, too complicated, etc. Okay, I removed a lot of stuff, but most of the stuff people can really figure out themselves if they need them in the first place. And I shrunk the thing to 25%. Perhaps there should be a separate Install FAQ of the sort "My shell said 'export: Command not found.'" or "What's a shared library?" to move the really annoying stuff out of people's ways. Comments? -- Peter Eisentraut - peter_e@gmx.net http://yi.org/peter-e
On 21-Sep-99 Peter Eisentraut wrote:
> On Sep 20, Bruce Momjian mentioned:
>
>> I agree our INSTALL is very large. Is there some way we can simplify
>> the install process?
>
> On the one hand a database server is probably not your everyday
> ./configure && make && make install program you get from freshmeat and you
> do want to put some time into a proper installation.
I disagree. When you remove the 'change to this user, install from this
directory' stuff and get down to the actual install, it is just as simple
as ./configure && make && make install. That's how I've done it the last
few times. And each time I've enabled different features.
Vince.
--
==========================================================================
Vince Vielhaber -- KA8CSH email: vev@michvhf.com flame-mail: /dev/null # include <std/disclaimers.h>
TEAM-OS2 Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore
http://www.cloudninegifts.com
==========================================================================
> > I agree our INSTALL is very large. Is there some way we can simplify
> > the install process?
> On the one hand a database server is probably not your everyday
> ./configure && make && make install program you get from freshmeat and you
> do want to put some time into a proper installation. On the other hand the
> INSTALL file is really way too long and makes for unpleasant reading.
> Here are a couple of ideas.
> That should make the file somewhat smaller, then also it is really to
> verbose at times and is formatted really oddly, at least on my system.
Formatted oddly, eh? ;)
We actually generate this file from files in doc/src/sgml/. We
generate RTF from the sgml sources, and then format to ascii text
using ApplixWare or <insert your favorite word processor here>. The
formatting options at that point are fairly limited afaik.
> Okay, now I really went out of my way and redid the whole thing. You'll
> find the result attached. This is merely an idea of what I would consider
> simpler. I removed some inconsistencies, things that were unnecessary, too
> complicated, etc. Okay, I removed a lot of stuff, but most of the stuff
> people can really figure out themselves if they need them in the first
> place. And I shrunk the thing to 25%.
Sounds great, except for the "people can figure it out for themselves"
part. But as long as the info is available somewhere in the docs, and
as long as people can get to them somehow if they need, then there is
probably no need for them to be in the INSTALL file.
> Perhaps there should be a separate Install FAQ of the sort "My shell said
> 'export: Command not found.'" or "What's a shared library?" to move the
> really annoying stuff out of people's ways.
And afaik once people have gotten to that point, the *real* docs will
have already been installed, so we can have that info there. I haven't
had a chance to look at your specific suggestions/changes, but I'm
sure they are a step forward.
- Thomas
--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California
> > > I agree our INSTALL is very large. Is there some way we can simplify > > > the install process? > > On the one hand a database server is probably not your everyday > > ./configure && make && make install program you get from freshmeat and you > > do want to put some time into a proper installation. On the other hand the > > INSTALL file is really way too long and makes for unpleasant reading. > > Here are a couple of ideas. > > That should make the file somewhat smaller, then also it is really to > > verbose at times and is formatted really oddly, at least on my system. > > Formatted oddly, eh? ;) > > We actually generate this file from files in doc/src/sgml/. We > generate RTF from the sgml sources, and then format to ascii text > using ApplixWare or <insert your favorite word processor here>. The > formatting options at that point are fairly limited afaik. My recommendation is to output HTML, and use lynx to output ASCII. I use: lynx -force_html -dump -hiddenlinks=ignore -nolist "$@" You would be surprised how much better it looks, assuming the HTML is good. > > Okay, now I really went out of my way and redid the whole thing. You'll > > find the result attached. This is merely an idea of what I would consider > > simpler. I removed some inconsistencies, things that were unnecessary, too > > complicated, etc. Okay, I removed a lot of stuff, but most of the stuff > > people can really figure out themselves if they need them in the first > > place. And I shrunk the thing to 25%. > > Sounds great, except for the "people can figure it out for themselves" > part. But as long as the info is available somewhere in the docs, and > as long as people can get to them somehow if they need, then there is > probably no need for them to be in the INSTALL file. > Our big problem with the ASCII file is that we can't nest text, like we can in HTML. In HTML, we can say "Do this, and if it doesn't work, click HERE", and have a page to describe known problems. This allows us to be brief, but give additional detail. Footnotes in a book have a similar purpose. Maybe we can implement footnotes in the ASCII file. That is how I would do it in LyX. > > Perhaps there should be a separate Install FAQ of the sort "My shell said > > 'export: Command not found.'" or "What's a shared library?" to move the > > really annoying stuff out of people's ways. > > And afaik once people have gotten to that point, the *real* docs will > have already been installed, so we can have that info there. I haven't > had a chance to look at your specific suggestions/changes, but I'm > sure they are a step forward. Interesting idea, but you would have to point them to the exact spot. That may be tough. -- Bruce Momjian | http://www.op.net/~candle maillist@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026
Thomas, can you comment on this. I think he has a good point. Can we move some of the stuff to footnotes at the end of the file? Can you try converting to HTML first, then to text to see if it formats better: lynx -force_html -dump -hiddenlinks=ignore -nolist "$@" > On Sep 20, Bruce Momjian mentioned: > > > I agree our INSTALL is very large. Is there some way we can simplify > > the install process? > > On the one hand a database server is probably not your everyday > ./configure && make && make install program you get from freshmeat and you > do want to put some time into a proper installation. On the other hand the > INSTALL file is really way too long and makes for unpleasant reading. > > Here are a couple of ideas. > > * Chapter 2 "Ports" should be moved to the README file (has nothing to do > with the actual installation). > > * Move the gory details of item 5 (flex) to a separate file (README.flex). > > * Move the locale stuff into a separate file. > > * Same with Kerberos > > * Move the release notes at the end to CHANGELOG. > > That should make the file somewhat smaller, then also it is really to > verbose at times and is formatted really oddly, at least on my system. > > Okay, now I really went out of my way and redid the whole thing. You'll > find the result attached. This is merely an idea of what I would consider > simpler. I removed some inconsistencies, things that were unnecessary, too > complicated, etc. Okay, I removed a lot of stuff, but most of the stuff > people can really figure out themselves if they need them in the first > place. And I shrunk the thing to 25%. > > Perhaps there should be a separate Install FAQ of the sort "My shell said > 'export: Command not found.'" or "What's a shared library?" to move the > really annoying stuff out of people's ways. > > Comments? > > -- > Peter Eisentraut - peter_e@gmx.net > http://yi.org/peter-e Content-Description: New INSTALL file? [Attachment, skipping...] -- Bruce Momjian | http://www.op.net/~candle maillist@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026
I hope we can get everyone with ideas together before 7.0 is released. > On Sep 20, Bruce Momjian mentioned: > > > I agree our INSTALL is very large. Is there some way we can simplify > > the install process? > > On the one hand a database server is probably not your everyday > ./configure && make && make install program you get from freshmeat and you > do want to put some time into a proper installation. On the other hand the > INSTALL file is really way too long and makes for unpleasant reading. > > Here are a couple of ideas. > > * Chapter 2 "Ports" should be moved to the README file (has nothing to do > with the actual installation). > > * Move the gory details of item 5 (flex) to a separate file (README.flex). > > * Move the locale stuff into a separate file. > > * Same with Kerberos > > * Move the release notes at the end to CHANGELOG. > > That should make the file somewhat smaller, then also it is really to > verbose at times and is formatted really oddly, at least on my system. > > Okay, now I really went out of my way and redid the whole thing. You'll > find the result attached. This is merely an idea of what I would consider > simpler. I removed some inconsistencies, things that were unnecessary, too > complicated, etc. Okay, I removed a lot of stuff, but most of the stuff > people can really figure out themselves if they need them in the first > place. And I shrunk the thing to 25%. > > Perhaps there should be a separate Install FAQ of the sort "My shell said > 'export: Command not found.'" or "What's a shared library?" to move the > really annoying stuff out of people's ways. > > Comments? > > -- > Peter Eisentraut - peter_e@gmx.net > http://yi.org/peter-e Content-Description: New INSTALL file? [Attachment, skipping...] -- Bruce Momjian | http://www.op.net/~candle maillist@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026
On 29-Nov-99 Bruce Momjian wrote: > > I hope we can get everyone with ideas together before 7.0 is released. It can be greatly simplified but will require changes to configure which I don't think I can do. I haven't really gotten to know autoconf yet and I think Peter said he's tied up till after the first of the year but he still wants to dig into it. Is after the first too late? Vince. > > >> On Sep 20, Bruce Momjian mentioned: >> >> > I agree our INSTALL is very large. Is there some way we can simplify >> > the install process? >> >> On the one hand a database server is probably not your everyday >> ./configure && make && make install program you get from freshmeat and you >> do want to put some time into a proper installation. On the other hand the >> INSTALL file is really way too long and makes for unpleasant reading. >> >> Here are a couple of ideas. >> >> * Chapter 2 "Ports" should be moved to the README file (has nothing to do >> with the actual installation). >> >> * Move the gory details of item 5 (flex) to a separate file (README.flex). >> >> * Move the locale stuff into a separate file. >> >> * Same with Kerberos >> >> * Move the release notes at the end to CHANGELOG. >> >> That should make the file somewhat smaller, then also it is really to >> verbose at times and is formatted really oddly, at least on my system. >> >> Okay, now I really went out of my way and redid the whole thing. You'll >> find the result attached. This is merely an idea of what I would consider >> simpler. I removed some inconsistencies, things that were unnecessary, too >> complicated, etc. Okay, I removed a lot of stuff, but most of the stuff >> people can really figure out themselves if they need them in the first >> place. And I shrunk the thing to 25%. >> >> Perhaps there should be a separate Install FAQ of the sort "My shell said >> 'export: Command not found.'" or "What's a shared library?" to move the >> really annoying stuff out of people's ways. >> >> Comments? >> >> -- >> Peter Eisentraut - peter_e@gmx.net >> http://yi.org/peter-e > Content-Description: New INSTALL file? > > [Attachment, skipping...] > > > -- > Bruce Momjian | http://www.op.net/~candle > maillist@candle.pha.pa.us | (610) 853-3000 > + If your life is a hard drive, | 830 Blythe Avenue > + Christ can be your backup. | Drexel Hill, Pennsylvania 19026 -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com flame-mail: /dev/null # include <std/disclaimers.h> Have you seenhttp://www.pop4.net? Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> > On 29-Nov-99 Bruce Momjian wrote: > > > > I hope we can get everyone with ideas together before 7.0 is released. > > It can be greatly simplified but will require changes to configure which > I don't think I can do. I haven't really gotten to know autoconf yet and > I think Peter said he's tied up till after the first of the year but he > still wants to dig into it. Is after the first too late? No, I don't think so. -- Bruce Momjian | http://www.op.net/~candle maillist@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026