Subject: pgsql-server/doc/src/sgml Makefile

From: [email-masked] (Bruce Momjian)
Date: Fri, 5 Mar 2004 15:48:03 -0400 (AST)

CVSROOT:	/cvsroot
Module name:	pgsql-server
Changes by:	[email-masked]	04/03/05 15:48:03

Modified files:
	doc/src/sgml   : Makefile 

Log message:
	Use '-' for stdin on lynx, my lynx version doesn't support -stdin.

---

From: Tom Lane <[email-masked]>
Date: Fri, 05 Mar 2004 15:07:30 -0500

> 	Use '-' for stdin on lynx, my lynx version doesn't support -stdin.

How old is your lynx?  I checked before making that patch, and -stdin
seemed to be in the oldest lynx I had handy (RHL 8.0).

BTW, I recently installed 2.8.5rel.1 here, and it generates very clean
text output --- no weird trailing spaces, proper justification of
headings, etc.  I'd suggest standardizing on that for building the
HISTORY file.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 5 Mar 2004 22:01:32 -0500 (EST)

> seemed to be in the oldest lynx I had handy (RHL 8.0).

I am using:

	Lynx Version 2.8.3rel.1 (23 Apr 2000)

I assume bsdi kept that version perhaps because newer versions had
troubles with some things.

In the old days, only I did HISTORY.  Now that others are doing it,
which is good, we should standardize to prevent CVS from recording
massive changes to HISTORY for different versions of lynx.

> headings, etc.  I'd suggest standardizing on that for building the

I see on postgresql.org:

	Lynx Version 2.8.5dev.16 (01 Jun 2003)

I used that to generate HISTORY, and I did a diff against the HISTORY I
generated, and the only difference is that it doesn't have spaces on
blank lines, which is even better output than mine.

In the future, I will use postgresql.org lynx.  If you find yours
generates similar output to that, you can keep using your local one.

I have changed the lynx flag back to -stdin, and regenerated HISTORY, so
you can run a comparison with CVS to see if yours is similar.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Tom Lane <[email-masked]>
Date: Sun, 07 Mar 2004 17:30:18 -0500

> generates similar output to that, you can keep using your local one.

Actually, mine generates better output than that one --- it aligns
headings better.  I'd suggest updating to the 2.8.5 release.

The HISTORY versions that I just committed were made with 2.8.5rel1
... feel free to compare.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 8 Mar 2004 17:35:33 -0500 (EST)

> ... feel free to compare.

I updated to that version of lynx but am still seeing the Migration
headings left-aligned, rather than centered.

I wonder if the cause is my version of the sgml tools, rather than lynx.

What do you see in your HISTORY.htlm file for "Migration":

><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN9"
>Migration to version 7.4.2</A

---

From: Tom Lane <[email-masked]>
Date: Mon, 08 Mar 2004 17:46:52 -0500

> >Migration to version 7.4.2</A

Hmm, I get

CLASS="SECT2"
><HR><H2
CLASS="SECT2"
NAME="AEN9"
></H2

so the discrepancy is evidently <H2> vs <H3>.  In my HISTORY.html,
"Release Notes" and "Release 7.4.2" are both <H1> and then the
Migration heading is <H2>.

So indeed it looks like the discrepancy is in the SGML stylesheet.
I'm not real sure whether the <H3> interpretation should be preferred
--- Peter, any comments?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 8 Mar 2004 18:57:30 -0500 (EST)

> I'm not real sure whether the <H3> interpretation should be preferred

Looking at the SGML, it seems the H3 interpretation is correct.  SGML
has:
	
	<appendix id="release">
	 <title>Release Notes</title>
	
	  <sect1 id="release-7-4-2">
	   <title>Release 7.4.2</title>
	
	   <note>
	   <title>Release date</title>
	   <simpara>2004-03-08</simpara>
	   </note>
	
	   <para>
	    This release contains a variety of fixes from 7.4.1.
	   </para>

	   <sect2>
	    <title>Migration to version 7.4.2</title>

Appendix/release should be H1, release-7-4-2 should be H2, and migration
H3.  I don't see any logic for appendix and sect1 be the same HTML
heading level because they don't seem to be the same level in SGML.

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 08:30:56 +0100

> massive changes to HISTORY for different versions of lynx.

A better approach for that would be to remove HISTORY from CVS and build 
it only when the release tarball is made.

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 08:32:19 +0100

> I'm not real sure whether the <H3> interpretation should be preferred

Check the version of your stylesheet.  It should be visible in the 
<META> headers of the generated HTML somewhere.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 02:42:32 -0500

> it only when the release tarball is made.

Given some standardization of the toolchain, that would be the way to
go.  Right now, though, we seem to have some doubts at both the SGML
and lynx levels.  Can we clear these up so people know what they will
get?

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 02:44:19 -0500

> <META> headers of the generated HTML somewhere.

Is this what you're looking for?

<TITLE
>Release Notes</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.59"></HEAD
><BODY

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 09:10:53 +0100

> CONTENT="Modular DocBook HTML Stylesheet Version 1.59"></HEAD

This qualifies as ancient.  Newer versions are available from

http://docbook.sourceforge.net/projects/dsssl/index.html

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 10:24:33 -0500

> http://docbook.sourceforge.net/projects/dsssl/index.html

Okay.  I see that both postgresql.org and Bruce are generating the docs
with
	Modular DocBook HTML Stylesheet Version 1.7
Shall we standardize on that and lynx 2.8.5 as the current "official"
versions to use for building the docs?

Also, I'm running openjade 1.3 on this machine, and as I recall it was
a serious pain in the arse to build.  Is it worth worrying about a newer
version of that?

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 17:07:12 +0100

Tom Lane wrote:
> Okay.  I see that both postgresql.org and Bruce are generating the
> docs with

There is no version "1.7".  This is in fact a bug; the correct version 
number of the latest version (which is in use at postgresql.org) is 
1.78.

> versions to use for building the docs?

Works for me.

> Also, I'm running openjade 1.3 on this machine, and as I recall it
> was a serious pain in the arse to build.  Is it worth worrying about
> a newer version of that?

Well, there is 1.3.2 now, but I can't tell you how easy or hard to build 
that one is.  There is also a 1.4 in the making, but the whole DSSSL 
toolchain is sort of dying.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 11:26:07 -0500

> toolchain is sort of dying.

Having re-read my notes about installing 1.3 from source, I won't shed a
tear if it dies.  Should I be thinking of installing something else
instead, and if so what?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 12:42:46 -0500 (EST)

> versions to use for building the docs?

2.8.5 is a development release of lynx, not a stable one:

Do we want to standardize on a development version of some tools?  It is
only converting to text, so I guess it is OK.

I downloaded the version of lynx Tom has just so I can generate the
newer output.  The only difference between my 2.8.3 lynx and 2.8.5 is
that 2.8.5 trips spaces on blank lines used between headings, which is
good.

I have also rebuilt the HISTORY file in CVS to match our official style
sheets.

> a serious pain in the arse to build.  Is it worth worrying about a newer

I can help you because I just installed new tools a few months ago. I
will phone you.

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 12:51:44 -0500 (EST)

> and lynx levels.  Can we clear these up so people know what they will

I think the only reason HISTORY and INSTALL are in CVS is because we
want people running CVS during beta to have changes docs and install
instructions that don't require them to pull down a new tarball each
time or read the docs via a web site.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 12:56:18 -0500

> 	Lynx Version 2.8.5dev.16 (01 Jun 2003)

2.8.5rel1 is a release version that has been out for some time.
If you're running a development version, that's not my problem.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 13:00:52 -0500

> time or read the docs via a web site.

That argument seems a bit silly for HISTORY, seeing that it's generally
not up-to-date during beta testing.  As for INSTALL, those instructions
don't change fast enough to surprise beta testers, so I'm not convinced
about it either.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 13:13:01 -0500 (EST)

> don't change fast enough to surprise beta testers, so I'm not convinced

Actually, recent releases had a current HISTORY before beta started. 
However, if they are downloading the beta tarballs, the HISTORY/INSTALL
files are already generated.  It would only be useful for CVS pulls
during beta though.

One idea would be to replace file content with a single URL that points
to the development docs, then when the tarball is built, it can
overwrite those files.

Marc?

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 13:16:58 -0500

> files are already generated.  It would only be useful for CVS pulls

The other point is: how plausible is it really that someone testing CVS
pulls would not find it convenient to read these docs from the website?
They've got to have net access to do the pull in the first place.

			regards, tom lane

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 14:30:26 -0400 (AST)

> to the development docs, then when the tarball is built, it can

Overwrite the files with ... ?  The contents of the URL itself, pulled
down with lynx?

if so, ya, that's easy enough ...

----
Marc G. Fournier           Hub.Org Networking Services (http://www.hub.org)
Email: [email-masked]           Yahoo!: yscrappy              ICQ: 7615664

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 13:53:42 -0500 (EST)

> if so, ya, that's easy enough ...

No, actually the URL points to an HTML.  You need to do 'gmake HISTORY'
in the sgml directory, and put that in /HISTORY.  Same for INSTALL.

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 13:57:37 -0500 (EST)

> If you're running a development version, that's not my problem.

Well, looking at:

	http://lynx.browser.org/

It mentions 2.8.3 as most current, and lists 2.8.5 under Development
Versions.

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 15:15:32 -0400 (AST)

> in the sgml directory, and put that in /HISTORY.  Same for INSTALL.

Ah, even easier ... stupid question, but the snapshot is still using the
7.4 docs ... is there a 'gmake' I should be using to build man.tar.gz,
like I do with postgres?

Based on the above, though, here are the steps for building the snapshot
that should be followed ... please confirm ...

/usr/bin/cvs -d /cvsroot -q export -rHEAD pgsql
cd pgsql
./configure
cd doc/src
gmake postgres.tar.gz
mv postgres.tar.gz ..
cp ~ftp/pub/dev/doc/postgres.tar.gz ~ftp/pub/dev/doc/man-7.4.tar.gz ../doc
cd sgml
gmake HISTORY INSTALL
cp HISTORY INSTALL ../../..
cd ../../..
gmake split-dist=yes VERSION=snapshot dist
gmake maintainer-clean

----

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 20:26:02 +0100

Bruce Momjian wrote:
> One idea would be to replace file content with a single URL that
> points to the development docs, then when the tarball is built, it
> can overwrite those files.

Please do not automatically overwrite files that are in CVS.  That will 
lead to trouble.  An alternative, which is actually in quite common 
use, is to simply provide a file README.cvs that explains various 
things about dealing with a CVS check out tree.  When you make a 
tarball, you simply delete the file.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 14:28:13 -0500

> It mentions 2.8.3 as most current, and lists 2.8.5 under Development

Why do you think that is authoritative?  Freshmeat shows lynx.isc.org
as the home site for lynx, and
http://lynx.isc.org/release/lynx2.8.5.tar.gz
as the current release.

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 14:33:06 -0500

> cp ~ftp/pub/dev/doc/postgres.tar.gz ~ftp/pub/dev/doc/man-7.4.tar.gz ../doc

That doesn't look right; for one thing you just made a postgres.tar.gz,
why would you overwrite it?  Also see the business about whether
man.tar.gz has a version number.

> cp HISTORY INSTALL ../../..

This gmake will leave some crud files that you don't want in the distro.
Instead of 'cp' I'd suggest
	mv -f HISTORY INSTALL ../../..
	gmake clean

Not sure if there are any other issues.

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 20:42:08 +0100

Tom Lane wrote:
> This gmake will leave some crud files that you don't want in the
> distro. Instead of 'cp' I'd suggest

The "make dist" step will do its own cleaning.

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 15:42:28 -0400 (AST)

> man.tar.gz has a version number.

k, both of those are fixed ...

> Not sure if there are any other issues.

Changed ...

----

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 9 Mar 2004 20:46:12 +0100

Marc G. Fournier wrote:
> cp ~ftp/pub/dev/doc/postgres.tar.gz ~ftp/pub/dev/doc/man-7.4.tar.gz
> ../doc cd sgml
> gmake HISTORY INSTALL

This looks mostly correct (modulo the other comments), but it seems 
there is still a lot of room for automation in there.

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 16:07:00 -0400 (AST)

> there is still a lot of room for automation in there.

Definitely open to suggestions on changing it ... I'm down to:

/usr/bin/cvs -d /cvsroot -q export -rHEAD pgsql
cd pgsql
./configure
cd doc/src
gmake postgres.tar.gz
mv postgres.tar.gz ..
cp ~ftp/pub/dev/doc/man-7.4.tar.gz ../doc/man.tar.gz
cd sgml
gmake HISTORY INSTALL
mv -f HISTORY INSTALL ../../..
cd ../../..
gmake split-dist=yes VERSION=snapshot dist
gmake maintainer-clean

You tell me what else I should add here ... :)

----

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 15:08:18 -0500 (EST)

> The "make dist" step will do its own cleaning.

Actually only as of yesterday.  There was no clean target for HISTORY
and INSTALL before.

I just added the clean target to 7.4.X too.

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 15:15:13 -0500

> cp ~ftp/pub/dev/doc/man-7.4.tar.gz ../doc/man.tar.gz

On second look, isn't that copying the man tarball to the wrong
directory?  Looks like it'll try to put it in doc/doc ...

			regards, tom lane

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 16:17:37 -0400 (AST)

> I just added the clean target to 7.4.X too.

'k, and I've removed it from the script ...

----

---

From: "Marc G. Fournier" <[email-masked]>
Date: Tue, 9 Mar 2004 16:18:37 -0400 (AST)

> directory?  Looks like it'll try to put it in doc/doc ...

Fixed ... does nobody ever download teh nsapshots? :)  that script hasn't
been touched in *months* now ...

----

---

From: Bruno Wolff III <[email-masked]>
Date: Tue, 9 Mar 2004 14:26:30 -0600

On Tue, Mar 09, 2004 at 12:42:46 -0500,
> that 2.8.5 trips spaces on blank lines used between headings, which is

I think the major advantage of 2.8.5 is https support. That isn't needed
for what you are doing, but is a good reason for someone to use it
as their browser in preference to earlier versions. I am using
2.8.5dev.9 and it seems to work reasonably well. The new scroll bar
function has an issue (copying text accross the scroll bar doesn't
work) so I don't use that feature.

---

From: Bruno Wolff III <[email-masked]>
Date: Tue, 9 Mar 2004 14:30:39 -0600

On Tue, Mar 09, 2004 at 13:16:58 -0500,
> They've got to have net access to do the pull in the first place.

I started using 7.4 early in the development cycle and was using the
developer doc pages fairly often. I was having trouble with jade back
then though. I can now make the html version of the documentation
and do that when I get new versions of 7.4 STABLE from CVS.

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 9 Mar 2004 19:29:55 -0500 (EST)

> tarball, you simply delete the file.

OK, I have removed HISTORY and INSTALL from CVS, and added a README.CVS
which contains URL's to that content.

Marc, would you modify your tar build script to remove README.CVS from
the tar file?

---

From: Tom Lane <[email-masked]>
Date: Tue, 09 Mar 2004 23:41:28 -0500

> Marc, would you modify your tar build script to remove README.CVS from

Sounds good, but are we all on the same page here?  Does this apply only
to CVS HEAD, or also in the 7.4 and 7.3 branches?  (I assume we are not
planning any further releases before 7.3.)

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 10 Mar 2004 11:44:23 -0500 (EST)

> planning any further releases before 7.3.)

I have done this for 7.4.X and HEAD.  I didn't touch 7.3.

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 11 Mar 2004 16:03:45 +0100

> Definitely open to suggestions on changing it ... I'm down to:

The reason this is all so complicated in the first place is that in the 
past we wanted to defend ourselves against broken documentation sources 
when building snapshots.  As of now this doesn't work anymore, so we 
might as well automate the whole process including the documentation 
build and be done with these games.  Comments?

---

From: Tom Lane <[email-masked]>
Date: Thu, 11 Mar 2004 11:39:18 -0500

> build and be done with these games.  Comments?

Making the man pages is still non-automatable, no?  Folding the HTML
document build into "make dist" is probably reasonable, but I don't
see that it will make for any big gain in the reliability of the
process...

			regards, tom lane