doc/src/FAQ/FAQ.html changes

Greg Sabino Mullane writes:

I found an error in the FAQ ("IS NULLIS NOT NULL") while reading
it as 'more FAQ', so I took a look at doc/src/FAQ/FAQ.html and
found a few[1] more.

Bruce, don't we want to put the FAQ into DocBook, so half the formatting
and linking problems are gone?

* ?? 1.10: The link to the SQL tutorial at
http://w3.one.net/~jhoffman/sqltut.htm is dead. I found
another copy at
http://www.intermedia.net/support/sql/sqltut.shtm
an put that in: but perhaps we should mirror our own copy,
if the author agrees?

We have our own SQL tutorial actually.

* 2.1: Changed the ODBC hyperlink from
http://www.postgresql.org/devel-corner/docs/programmer/odbc.html
to:
http://developer.postgresql.org/docs/postgres/odbc.html

Not really a good idea.

* ?? Various: changed "indices" to "indexes". There were about an
even number of each, so I flipped a coin. Will this hot issue
ever get decided? :)

It's "indices" when talking about an array or field index, and it's
"indexes" when concerning the index at the end of a book or a database
index.

--
Peter Eisentraut peter_e@gmx.net

Wow, I was laughing all through this. You had so many good points I
started to think the FAQ was maintained by a monkey, and that monkey was
me. :-)

I agree with all your changes, except a few. Let me list those few:

---------------------------------------------------------------------------

* 1.9: Fixed the hyperlink for "TODO" to point to the
correct (?) place.

I used to run linkchecker on the FAQ but haven't since the web site
redesign. Nice catches.

* ?? 1.10: The link to the SQL tutorial at
http://w3.one.net/~jhoffman/sqltut.htm is dead. I found
another copy at
http://www.intermedia.net/support/sql/sqltut.shtm
an put that in: but perhaps we should mirror our own copy,
if the author agrees?

That old URL goes in and out of visibility. Let's keep the new one. I
don't think we can mirror it ourselves. Let's see if the new URL stays.

* Many places: fixed incorrect possessive apostrophes, including:
DBMS's
CPU's
fsync()'s
assert()'s
R-tree's
OID</SMALL>'s

Yes, I get that confused for some reason; don't know why I do it.

* 1.13 Replaced vague reference to a "bug-template" file
with a hyperlink to:
http://www.postgresql.org/bugs/bugs.php. Also removed
the mailto:bugs link to encourage people to read the
guidelines and use the online form. By the way, that
page needs to have <title> tags.

CC'ing webmaster --- Vince?

* ?? 3.5: Moved this paragraph:
<p>Inoperative semaphores can also cause crashes during heavy
database access.</p> to question 3.4. Is this where it goes?

Yes, copy-paste error.

* ?? 4.19: Can we not just say something similar to:
"use the SQL command 'select version();'"
as this is not a psql specific?

Well, it is just better to tell them exactly how to test it. They can
use other apps too.

* ?? 1.14: The page linked to:
http://openacs.org/why-not-mysql.html
which compares mySQL and postgreSQL, is almost 2 years old
now, and, as the disclaimer at the top states, is not really
fair to mySQL due to its age. Perhaps a newer comparison
could be found?

This is a jem that is frequently cited. Not sure we want to remove it.
Comments?

* ?? 2.2: The link to
http://www.phone.net/home/mwm/hotlist/
seems to be down as I write this, but I cannot determine if
this is temporary or permanent. If it is still down by the
time this is read, we may want to remove this link.

I will check with linkchecker later.

* ?? The text version seems to have a lot of blank lines which
I had to strip out to get it to match the outout of
lynx -dump -nolink FAQ.html. For example, the third line
of doc/FAQ has 40 blank lines. Why is this?

I don't see that here or in CVS.

* Put all tags in lowercase for xhtml compliance,
added new DOCTYPE and html tags.

Not sure that is a good idea. I don't want to go out in an advanced
direction with the FAQ, want to make it is simple to render as possible.

I auto-uppercased the tags again to match the HTML version of our docs.
I also found <br /> and <hr /> which htmllint didn't understand and I
have never seen; changed to <br> and <hr>.

* ?? Perhaps define DBMS somewhere?

* ?? 4.10 It says:
"In theory, R-trees can be extended to handle higher number
of dimensions. In practice, extending R-trees requires a bit
of work and we don't currently have any documentation on how
to do it"
Is this what they are working on here?:
http://rplustree.sourceforge.net/

That is a C version, quite different from doing it in a db.

---------------------------------------------------------------------------

Very nice improvments. You version is now installed as official.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@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

Peter Eisentraut wrote:

Greg Sabino Mullane writes:

I found an error in the FAQ ("IS NULLIS NOT NULL") while reading
it as 'more FAQ', so I took a look at doc/src/FAQ/FAQ.html and
found a few[1] more.

Bruce, don't we want to put the FAQ into DocBook, so half the formatting
and linking problems are gone?

I guess we could. I am no docbook fan and am concerned about
duplicating some of the stuff I do in HTML.

* 2.1: Changed the ODBC hyperlink from
http://www.postgresql.org/devel-corner/docs/programmer/odbc.html
to:
http://developer.postgresql.org/docs/postgres/odbc.html

Not really a good idea.

Old one put back.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@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

Bruce Momjian writes:

Bruce, don't we want to put the FAQ into DocBook, so half the formatting
and linking problems are gone?

I guess we could. I am no docbook fan and am concerned about
duplicating some of the stuff I do in HTML.

What stuff and why would you have to duplicate it?

--
Peter Eisentraut peter_e@gmx.net

Peter Eisentraut wrote:

Bruce Momjian writes:

Bruce, don't we want to put the FAQ into DocBook, so half the formatting
and linking problems are gone?

I guess we could. I am no docbook fan and am concerned about
duplicating some of the stuff I do in HTML.

What stuff and why would you have to duplicate it?

Well, I do things like smallcaps and some other stuff. With HTML I know
how it is going to be rendered, while with SGML, I am never sure ---
even simple stuff like <command> comes out in bold, as you already
observed.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@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

Bruce Momjian writes:

Well, I do things like smallcaps and some other stuff. With HTML I know
how it is going to be rendered, while with SGML, I am never sure ---
even simple stuff like <command> comes out in bold, as you already
observed.

It comes out the way you tell it to come out. But the advantage is that
if you mark up all commands as <command> then you can change it to bold,
small, green, or whatever with a single change in the stylesheet.

I wouldn't get hung up on the small caps. I would get hung up about
having to maintain correct numbering and links, and the formatting not
matching the PostgreSQL documentation or the web site.

--
Peter Eisentraut peter_e@gmx.net

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

* ?? The text version seems to have a lot of blank lines which
I had to strip out to get it to match the output of
lynx -dump -nolink FAQ.html. For example, the third line
of doc/FAQ has 40 blank lines. Why is this?

I don't see that here or in CVS.

I got that from using the web-based cvs:

wget http://developer.postgresql.org/cvsweb.cgi/~checkout~/pgsql/doc/FAQ?rev=1.133&amp;content-type=text/plain

[regarding xhtml tags]

Not sure that is a good idea. I don't want to go out in an
advanced direction with the FAQ, want to make it is simple to
render as possible. I auto-uppercased the tags again to match
the HTML version of our docs. I also found <br /> and <hr />
which htmllint didn't understand and I have never seen;
changed to <br> and <hr>.

They are a XHTML artifact: all tags are required to have a
matching closing tag. To maintain compatibility with older
browsers, the start and end tags are allowed to be combined
into one with the <br /> trick. I'm surprised htmllint
complained about that. The only other major difference is that
all tags must be lowercase. (which is very difficult for me:
after so many years, my fingers automatically type tags in
uppercase!). In the long run, XHTML/XML will actually
allow pages to be more widely accessible, but the world isn't
exactly rushing to embrace XML yet. It was last on my list
anyway. :)

* 2.1: Changed the ODBC hyperlink from
http://www.postgresql.org/devel-corner/docs/programmer/odbc.html&gt; > to:
http://developer.postgresql.org/docs/postgres/odbc.html&gt;

Not really a good idea. Old one put back.

So this link is now removed entirely?

It's "indices" when talking about an array or field index, and
it's "indexes" when concerning the index at the end of a book
or a database index.

Thanks for that.

[regarding a better "vs. mySQL" page]

I surfed a little, and here are some links I came up with. Be
careful when searching the web for similar pages: many
comparisons use v6 of postgreSQL :(. I don't know mySQL version
number well enough to know if they do the same, but I suspect
not.

First, a quote from someone on slashdot:

"If you want details of high performance testing, then you need
to visit www.tpc.org. Until I see Postgres up there then this
testing is useless to the business world."

I agree - it sure would be nice if postgreSQL could get included
in the tests. (paging RedHat...)

October 10, 2001
http://www.geocities.com/mailsoftware42/db/
I like this one

September 2001:
http://www.webtechniques.com/archives/2001/09/jepson/
Pretty new. Fairly good, if a little (IMO) apologetic about
some of mySQL's shortcomings at times:
"Although MySQL can't perform subqueries, its temporary tables
can help you mimic subqueries in SELECT statements..."

July 2000:
http://www.phpbuilder.com/columns/tim20000705.php3

May 2000:
http://openacs.org/philosophy/why-not-mysql.html
The one currently used, but it's old (and admits it in
bold at the top of the page) and has a huge flame war at
the bottom of the page. Maybe we can as the author to update
it and clean it up a bit?

"mySQL Benchmarks"
http://www.mysql.com/information/benchmarks.html
Lots of colorful graphs, and whining about not getting
vacuum to work reliably.

"Featurewise Comparison of MySQL and PostgreSQL"
http://www.mysql.com/doc/M/y/MySQL-PostgreSQL_features.html
mysql's take on why they are better. Very few are valid.
Matter of fact, they really seem to be reaching on some
of these.

Heh. At the bottom of the page, "Only transactional tables"
is listed as a "drawback" of PostgreSQL!

http://www.epinions.com/content_19552308868
Good user review. There are four others, one of which is
negative.

http://www.devx.com/dbzone/articles/renaker03/renaker03-1.asp
Not sure of the date of this.

And of course, there is the GreatBridge funded study that has
been analyzed to death. That's why something like tpc.org would
be nice.

Greg Sabino Mullane
greg@turnstep.com
PGP Key: 0x14964AC8 200201121119

-----BEGIN PGP SIGNATURE-----
Comment: http://www.turnstep.com/pgp.html

iQA/AwUBPEBjILybkGcUlkrIEQIV9gCg3wc9IP+wHNC6oZ42QeTe7+HLi6YAoPmT
O8Ocx8OUXzFn9LpCOHf8A57P
=FxzQ
-----END PGP SIGNATURE-----