From: Bruce Momjian <maillist@candle.pha.pa.us>
Message-Id: <199901051846.NAA12114@candle.pha.pa.us>
Subject: Re: [DOCS] TODO list
In-Reply-To: <3691AAAA.3A05F737@alumni.caltech.edu> from "Thomas G. Lockhart"
	at "Jan 5, 1999  6: 1:15 am"
To: lockhart@alumni.caltech.edu (Thomas G. Lockhart)
Date: Tue, 5 Jan 1999 13:46:52 -0500 (EST)
Cc: hal@enteract.com, docs@postgreSQL.org, scrappy@hub.org
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

> > Current.sgml is the list of changes that appear in the HISTORY file.
> > They used to appear at the bottom of the TODO list, so it makes sense
> > you had them confused.  It is gone from the TODO as of today.
> > It is now only at the top of the HISTORY file.  You had a narrative at
> > the top to highlight the new items in current.sgml too.  Because 
> > people are upgrading by often jumping several releases, from 6.3.1 to 
> > 6.4.2 for example, giving a list of the new features JUST in the 
> > current release is not really a good idea anymore.
> 
> ?? current.sgml and release.sgml go together, and together have all of
> the info in HISTORY, plus some notes on highlights. Please look at the
> current html docs generated from the sgml sources to see how it is laid
> out! I tried separating the most recent release info into current.sgml
> hoping that you could work with it more easily :( The chapter of release
> notes in the full docs has a section for every release we have had,
> including a few paragraphs on highlights. We should have more imho.

I think we should merge them into one file.

The big problem, which has existed since using sgml, is that I can't
generate the html and ASCII output I need when I change the sgml file.
This is also a problem with the man pages.

I can change to sgml, but I still need to generate an ASCII HISTORY file.

I looked at the html release output, and this really does look nice.

> 
> > Pointing them to the entire HISTORY file allows them to go backwards
> > until they hit the release they are currently running.
> > As I remember, you just include the HISTORY files's changes in the 
> > sgml output, without any formatting, so it appears we don't have to 
> > make any changes.
> 
> This isn't by my choice. Since you maintain HISTORY as a flat file, and
> update it very near to a release, that is the only way I can incorporate
> info into the sgml-based docs.

I have no way to generate the HISTORY file earlier in the release
process.  We are adding fixes up to the end.

> 
> > You just grab the current HISTORY contents when you package
> > the docs for the release.  Because the docs typically arn't updated
> > during minor releases, they should be looking at the HISTORY file
> > anyway.  In fact, that give a good argument not to include the HISTORY
> > file in the docs at all.
> 
> Ack! The docs (especially the html) can easily be updated for minor
> releases if we choose to do so. I have been hoping that we could switch
> to store this info in sgml at some point. I've had to write last minute
> highlights for the last couple of releases which would be much better if
> done earlier and brought along with the other info currently at the top
> of HISTORY or in a new version of current.sgml.
> 
> An example of info which should end up in release.sgml/current.sgml is
> the newly-revealed fact that v6.3 can not be dump/reloaded to v6.4.x,
> but that v6.3.1 and v6.3.2 can. That will be useful information long
> into the future, and can be presented from sgml-based docs more
> effectively, with cross-references etc.

Yep, but we need html/man/output from sgml.  Without this, we are going
to continue having problems.

Making changes in two places always causes problems.  I need a clear
description of what is sgml, and what gets generated from sgml, and
steps to do this, perhaps from the postgresql.org machine.

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