Обсуждение: INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)

От:
Peter Eisentraut
Дата:

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 - 
http://yi.org/peter-e

От:
Vince Vielhaber
Дата:

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:    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
==========================================================================




От:
Thomas Lockhart
Дата:

> > 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                
South Pasadena, California


От:
Bruce Momjian
Дата:

> > > 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             |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026
 


От:
Bruce Momjian
Дата:

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 - 
> http://yi.org/peter-e
Content-Description: New INSTALL file?

[Attachment, skipping...]


--  Bruce Momjian                        |  http://www.op.net/~candle             |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026
 


От:
Bruce Momjian
Дата:

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 - 
> http://yi.org/peter-e
Content-Description: New INSTALL file?

[Attachment, skipping...]


--  Bruce Momjian                        |  http://www.op.net/~candle             |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026
 


От:
Vince Vielhaber
Дата:

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 - 
>> http://yi.org/peter-e
> Content-Description: New INSTALL file?
> 
> [Attachment, skipping...]
> 
> 
> -- 
>   Bruce Momjian                        |  http://www.op.net/~candle
>               |  (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:    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
 
==========================================================================




От:
Bruce Momjian
Дата:

> 
> 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             |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026