Skip site navigation (1) Skip section navigation (2)

Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)

From: Bruce Momjian <maillist(at)candle(dot)pha(dot)pa(dot)us>
To: Thomas Lockhart <lockhart(at)alumni(dot)caltech(dot)edu>
Cc: Peter Eisentraut <peter_e(at)gmx(dot)net>, Vince Vielhaber <vev(at)michvhf(dot)com>, The Hermit Hacker <scrappy(at)hub(dot)org>, docs(at)postgreSQL(dot)org
Subject: Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)
Date: 1999-09-22 16:45:49
Message-ID: 199909221645.MAA08069@candle.pha.pa.us (view raw or flat)
Thread:
Lists: pgsql-docspgsql-hackers
> > > 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(at)candle(dot)pha(dot)pa(dot)us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

In response to

pgsql-docs by date

Next:From: Bruce MomjianDate: 1999-09-23 17:36:42
Subject: Re: [GENERAL] Multi-threading on PostgreSQL?
Previous:From: Thomas LockhartDate: 1999-09-22 15:48:29
Subject: Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)

pgsql-hackers by date

Next:From: Bruce MomjianDate: 1999-09-22 20:16:28
Subject: Compile timing
Previous:From: Bruce MomjianDate: 1999-09-22 16:39:14
Subject: Re: [HACKERS] postmaster disappears

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group