Thread: doc/src/FAQ/FAQ.html changes
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
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. I've ordered them in rough order of
importance, from glaring typos all the way down to proposed
XHTML compliance. Specific questions I have are denoted
with a "* ??". Rather than attaching the whole file, I'll
just give a URL and attach a finalized version if required
later. Feel free to ask me for a subset of the below changes
if need be.
http://www.gtsm.com/postgres/FAQ.html
* 4.14: Fixed typo in answer (IS NULLIS NOT NULL).
* 4.24: Changed href="#4.25" to "name=4.25" in the answer.
* 2.2: Replaced "use" with "using" so the Q & A match.
* 5.4: Changed hyperlink text to 5.4 from 5.3
* 1.9: Fixed the hyperlink for "TODO" to point to the
correct (?) place.
* ?? 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?
* 3.9: Added double quotes so the Q & A match.
* 4.3, 4.6, 4.18, 4.19, 4.20, 4.21, 4.22, 4.23:
Removed <BR> from answer, before </H4>
* 4.15.2: Changed "$newSerialID" to "new_id" to match example
above it.
* replaced <H6> with <P><STRONG>
* 4.15.2: Stripped the "to to" from the paragraph. :)
* 4.5: Changed wording of question a little.
* 3.9: Better phrasing of the question.
* 4.19: Reworded to a single question, quoted error message,
moved puncuation outside HTML.
* 1.2: Changed copyright from 2001 to 2002
* 1.4: Hyperlinked "MS Windows FAQ" to
http://www.postgresql.org/docs/faq-mswin.html
* Many places: fixed incorrect possessive apostrophes, including:
DBMS's
CPU's
fsync()'s
assert()'s
R-tree's
OID</SMALL>'s
* </P> tag added where missing: 1.15 (x4), 4.12
* 1.1: Added "how is it pronounced?" to the question itself.
Moved pronounciation answer to the top of the answer section.
* 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.
* 1.2: Expanded contraction of what's.
* Changed references to "the postmaster" to simply "postmaster",
since we are emphasizing that this is a program in italics,
such as psql. Perhaps change to "the <I>postmaster</I> program"
if the "the" is really desired.
* 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
* 2.2: Changed the link regarding "Database-backed Web pages"
from
http://www.webtools.com
to:
http://www.webreview.com
as the former simply refreshes to the latter with a meta
directive.
* ?? 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?
* ?? 3.3 Hyperlinked the words "PostgreSQL Administrator's Guide" to:
http://www.postgresql.org/idocs/index.php?kernel-resources.html
Is there a preferred non-interactive version?
* Various: made "unix" consistently "Unix" (also "non-Unix")
* ?? 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? :)
* 4.15.1: Removed strange link to Bruce's book:
<p><a href=
"http://www.PostgreSQL.org/docs/aw_pgsql_book">Numbering
Rows.</a></p>
* Replaced deprecated CENTER tag with align="center"
* Make "web site" capitalization consistent.
* 4.15.2: Separated non-command word "after" from italics.
* 1.6,1.8,1.15: Moved "href" to its own line, this helps the
display of plain text (e.g. using 'more FAQ')
* 3.1: Moved question mark outside html
* 3.7,3.8: Moved 's' outside html
* (14 places): Moved comma outside html
* 4.18: Moved colon outside html
* (13 places): Moved period outside html
* 4.15.1 Separated possesive apostrophe from html
* 4.19: Removed extra space
* 4.16: Changed Tids to T<small>ID</small>s to match the first
one in the paragraph.
* ?? 4.19: Can we not just say something similar to:
"use the SQL command 'select version();'"
as this is not a psql specific?
* 1.14: Expanded "don't" and "doesn't", added link to section 1.6
* Fixed some line wrapping differences in questions and answers
* 1.4: Put "psql" inside italics
* 4.12: Fixed spacing difference between question and answer.
* ?? 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?
* 1.11: Added spaces before "AD" and "BC"
* 3.7: expanded "you've"
* ?? 1.15: Changed "five years" to "six years" in honor of the
new year. Is this accurate?
* 4.5: Put spaces before "TB" and "GB" as needed.
* 3.3, 4.6: Added space before MB.
* 2.1: Changed "Questions to x" to "Please send questions to x"
* 3.7: Changed "a lot of" to "many." Added a comma after "Also".
Changed "ie, " to "i.e. "
* 1.12: high-quality does not need a hyphen to emphasis the
relationship (changed to "high quality")
* ?? 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.
* ?? 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?
* ?? 2.3 capitalizes 'pgaccess' at the start of a sentence,
while 'psql' is not in 1.8. Removed caps from 2.3, but
not sure if this is correct. I leaned towards having the
exact spelling overriding the sentence capitalization.
* Put all tags in lowercase for xhtml compliance,
added new DOCTYPE and html tags.
* ?? 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/
[1] Okay, maybe more than a few. I was on a roll...
Greg Sabino Mullane
greg@turnstep.com
PGP Key: 0x14964AC8 200201101539
-----BEGIN PGP SIGNATURE-----
Comment: http://www.turnstep.com/pgp.html
iQA/AwUBPD4Bo7ybkGcUlkrIEQIfugCeP8znypOpFK+qly1QulcaO3AQ1uwAn2+/
wUMx/OjImYuZKwZn+jPjwCbr
=El26
-----END PGP SIGNATURE-----
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
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: > > 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
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&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> > to: > > http://developer.postgresql.org/docs/postgres/odbc.html> > > 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-----