Re: [DOCS] TODO list - Mailing list pgsql-docs

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

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

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