New docs available

From: "Thomas G(dot) Lockhart" <lockhart(at)alumni(dot)caltech(dot)edu>
To: Bruce Momjian <maillist(at)candle(dot)pha(dot)pa(dot)us>, Postgres Documentation List <docs(at)postgresql(dot)org>
Cc: PostgreSQL-development <hackers(at)postgresql(dot)org>
Subject: New docs available
Date: 1998-03-01 22:33:07
Message-ID: 34F9E223.F658ED34@alumni.caltech.edu
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

> Somehow, I don't think pgsql/doc/postgres.tar.gz should be there. It
> looks big.

Well, _I_ thought it was supposed to be there :) Discussed below...

OK, the new docs are now committed. Can people with access to the CVSup tree
look through them for any obvious, hopefully minor, problems?

There is a Makefile in the doc/ directory; "make install" will unpack the
html directories directly underneath doc, or will unpack them under $PGDOCS
if that is defined in your Makefile.custom in the source area.

So, there are 4 documents available in both hardcopy and html:

admin - disk and user management, installation instructions, etc.
user - all user-oriented topics _not_ requiring programming
programmer - programming topics for application- and postgres-developers
tutorial - the sql newbie introduction. no installation instructions

There is a 5th html package, "postgres", which contains all of the others as
"parts of a book". That way, you can click around the entire document set
without having to jump to a new URL. Was not useful for hardcopy imo but
seemed possibly more convenient in html.

It adds bulk to the distribution, but I thought it would be useful. I hope
that there will be lots of discussion on the right way to do this, and we
can make adjustments along the way.

fyi, it takes ~5 minutes or less on my machine to completely regenerate all
5 html documents from the source. Each hardcopy took an hour or so to clean
up (e.g. fixing a few page breaks, updating the ToC, inserting figures,
etc).

There is lots of ugliness scattered through the docs, but I've accomplished
my main goal for v6.3 (at least I hope I have):

The minimum time investment for someone to make a meaningful contribution to
the non-ascii documentation is now measured in minutes. Small typos and
paragraphs can be fixed trivially, and larger content can be modified or
inserted easily. It can all be redone in hardcopy for each release with a
minimum of effort, and html can be updated immediately if you have the tools
installed. I hope to get postgresql.org set up to be able to do this, so we
can get fresh html generated between releases.

- Tom

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Bruce Momjian 1998-03-01 22:37:41 Re: New docs available
Previous Message Brett McCormick 1998-03-01 21:51:09 Re: [HACKERS] sequences