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.

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