Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2) - Mailing list pgsql-docs

From Bruce Momjian
Subject Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)
Date
Msg-id 199909221645.MAA08069@candle.pha.pa.us
Whole thread Raw
In response to Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)  (Thomas Lockhart <lockhart@alumni.caltech.edu>)
List pgsql-docs
> > > 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
 


pgsql-docs by date:

Previous
From: Thomas Lockhart
Date:
Subject: Re: [DOCS] INSTALL file (was Re: [HACKERS] Re: HISTORY for 6.5.2)
Next
From: Bruce Momjian
Date:
Subject: Re: [GENERAL] Multi-threading on PostgreSQL?