public inbox for [email protected]
help / color / mirror / Atom feedCognitive dissonance
38+ messages / 20 participants
[nested] [flat]
* Cognitive dissonance
@ 2010-06-08 09:04 John Gage <[email protected]>
0 siblings, 5 replies; 38+ messages in thread
From: John Gage @ 2010-06-08 09:04 UTC (permalink / raw)
To: PostgreSQL - General <[email protected]>
Unix is a text-based operating system with unbelievably helpful text
manipulation tools.
Postgres is a creature of Unix which happens to have unbelievable text
searching and manipulation tools.
Yet, the only one file edition of the Postgres documentation is
in...pdf format. Huh?
I know. I know. I have already brought this up. And various ways of
creating a one file text edition of the documentation have been
proposed to me. I know.
But either I am a visitor from the Crab Nebula, or there is someone
else out there who would like to have a text file of the entire
documentation.
Two examples from other applications.
I use Vim. Vim's documentation is as easy to access as any
documentation on earth...as long as you know exactly what you are
looking for. Otherwise, it is a tremendous pain.
I also use the National Library of Medicine's MeSH subject headings.
25,000 descriptors with definitions, synonyms and a lot of other
things. They give it to you in single files either as text, xml, or
other ways. Big files. Hundreds of megabytes. That makes it so that
you can do just about anything with it you want. It is one of the
seven wonders of the world.
I do suggest that a plain text file of the entire documentation be
made part of the documentation armamentarium.
Respectfully,
John Gage
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 12:07 Lew <[email protected]>
parent: John Gage <[email protected]>
4 siblings, 0 replies; 38+ messages in thread
From: Lew @ 2010-06-08 12:07 UTC (permalink / raw)
To: [email protected]
John Gage wrote:
> I also use the National Library of Medicine's MeSH subject headings.
> 25,000 descriptors with definitions, synonyms and a lot of other things.
> They give it to you in single files either as text, xml, or other ways.
> Big files. Hundreds of megabytes. That makes it so that you can do just
> about anything with it you want. It is one of the seven wonders of the
> world.
>
> I do suggest that a plain text file of the entire documentation be made
> part of the documentation armamentarium.
From <http://www.postgresql.org/docs/manuals/;:
"The DocBook SGML source for the manuals is available as part of the
PostgreSQL source download available in the FTP area."
--
Lew
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 14:23 Peter Hunsberger <[email protected]>
parent: John Gage <[email protected]>
4 siblings, 1 reply; 38+ messages in thread
From: Peter Hunsberger @ 2010-06-08 14:23 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
On Tue, Jun 8, 2010 at 4:04 AM, John Gage <[email protected]> wrote:
> Unix is a text-based operating system with unbelievably helpful text
> manipulation tools.
>
> Postgres is a creature of Unix which happens to have unbelievable text
> searching and manipulation tools.
>
> Yet, the only one file edition of the Postgres documentation is in...pdf
> format. Huh?
>
I suppose the next thing you'll be suggesting is that, because
Postgres is a database, the documentation should be stored as some
form of searchable table within the database itself....?
<runs and hides/>
--
Peter Hunsberger
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 15:01 Stephen Frost <[email protected]>
parent: John Gage <[email protected]>
4 siblings, 1 reply; 38+ messages in thread
From: Stephen Frost @ 2010-06-08 15:01 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
* John Gage ([email protected]) wrote:
> But either I am a visitor from the Crab Nebula, or there is someone else
> out there who would like to have a text file of the entire
> documentation.
Soo.. there are quite a few man pages, and in-psql's help is also
pretty nice (\h <command> and \?). That's certainly what I typically
use. I admit that we don't include the full command description in the
\h (just the syntax), but that's still extremely useful.
Would a \h+ that gave you the text from the web-page be useful..? That,
plus the various man pages, would cover an awful lot of what's in SGML..
Thanks,
Stephen
Attachments:
[application/pgp-signature] signature.asc (197B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 15:36 Justin Graf <[email protected]>
parent: Peter Hunsberger <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Justin Graf @ 2010-06-08 15:36 UTC (permalink / raw)
To: Peter Hunsberger <[email protected]>; +Cc: John Gage <[email protected]>; PostgreSQL - General <[email protected]>
On 6/8/2010 9:23 AM, Peter Hunsberger wrote:
> On Tue, Jun 8, 2010 at 4:04 AM, John Gage<[email protected]> wrote:
>
>> Unix is a text-based operating system with unbelievably helpful text
>> manipulation tools.
>>
>> Postgres is a creature of Unix which happens to have unbelievable text
>> searching and manipulation tools.
>>
>> Yet, the only one file edition of the Postgres documentation is in...pdf
>> format. Huh?
>>
>>
> I suppose the next thing you'll be suggesting is that, because
> Postgres is a database, the documentation should be stored as some
> form of searchable table within the database itself....?
>
> <runs and hides/>
>
>
Its also available in chm windows help file format. Which i find allot
more useful
http://www.postgresql.org/docs/manuals/
you could print chm to a text file.
also it not hard to dump a PDF document into a text file.
All legitimate Magwerks Corporation quotations are sent in a .PDF file attachment with a unique ID number generated by our proprietary quotation system. Quotations received via any other form of communication will not be honored.
CONFIDENTIALITY NOTICE: This e-mail, including attachments, may contain legally privileged, confidential or other information proprietary to Magwerks Corporation and is intended solely for the use of the individual to whom it addresses. If the reader of this e-mail is not the intended recipient or authorized agent, the reader is hereby notified that any unauthorized viewing, dissemination, distribution or copying of this e-mail is strictly prohibited. If you have received this e-mail in error, please notify the sender by replying to this message and destroy all occurrences of this e-mail immediately.
Thank you.
Attachments:
[text/x-vcard] justin.vcf (258B, 2-justin.vcf)
download | inline:
begin:vcard
fn:Justin Graf
n:Graf;Justin
org:Magwerks Corp
adr:;;501 Commerce Drive;Danville ;IN;46122;USA
email;internet:[email protected]
tel;work:317-241-8011 ext 703
tel;fax:317-241-8015
x-mozilla-html:FALSE
url:www.magwerks.com
version:2.1
end:vcard
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 16:29 Chris Browne <[email protected]>
parent: Justin Graf <[email protected]>
0 siblings, 0 replies; 38+ messages in thread
From: Chris Browne @ 2010-06-08 16:29 UTC (permalink / raw)
To: [email protected]
[email protected] (Justin Graf) writes:
> Its also available in chm windows help file format. Which i find allot
> more useful
> http://www.postgresql.org/docs/manuals/
> you could print chm to a text file.
>
> also it not hard to dump a PDF document into a text file.
I wish I could find a converter that would generate one of the common
eBook formats (epub, mobi).
There do exist CHM readers on mobile platforms such as Android, but
they're much clumsier to work with than the rather more heavily used
eBook readers.
I have poked around for conversions; nothing particularly suitable has
emerged :-(.
--
select 'cbbrowne' || '@' || 'cbbrowne.com';
http://cbbrowne.com/info/internet.html
"MS apparently now has a team dedicated to tracking problems with
Linux and publicizing them. I guess eventually they'll figure out
this back fires... ;)" -- William Burrow <[email protected]>
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 16:42 John Gage <[email protected]>
parent: Stephen Frost <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: John Gage @ 2010-06-08 16:42 UTC (permalink / raw)
To: PostgreSQL - General <[email protected]>
Thank you all for your suggestions. Thank you very much.
John
1) I suppose the next thing you'll be suggesting is that, because
Postgres is a database, the documentation should be stored as some
form of searchable table within the database itself....?
<runs and hides/>
------Well, that is exactly what I have done with the MeSH subject
headings. And it works like a charm.
2) Its also available in chm windows help file format. Which i find
allot
more useful
http://www.postgresql.org/docs/manuals/
you could print chm to a text file.
------I'll have to boot over to XP, ugh. Will do.
3) also it not hard to dump a PDF document into a text file.
------I would print out what the dump looks like, but this is a family
program
4) Would a \h+ that gave you the text from the web-page be useful..?
That,
plus the various man pages, would cover an awful lot of what's in SGML..
From <http://www.postgresql.org/docs/manuals/;:
"The DocBook SGML source for the manuals is available as part of the
PostgreSQL source download available in the FTP area."
-----I'm headed there. It's just that given the incredibly good
documentation and the fact that it's available in just about every
format except a text file, I was sort of hoping for a policy change on
the part of the powers that be.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 18:21 Justin Graf <[email protected]>
parent: John Gage <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Justin Graf @ 2010-06-08 18:21 UTC (permalink / raw)
To: [email protected]
***SNIP***
> 2) Its also available in chm windows help file format. Which i find
> allot
> more useful
> http://www.postgresql.org/docs/manuals/
> you could print chm to a text file.
>
> ------I'll have to boot over to XP, ugh. Will do.
There are linux chm readers
http://www.linux.com/news/software/applications/8209-chm-viewers-for-linux
and one for firefox
https://addons.mozilla.org/en-US/firefox/addon/3235/
All legitimate Magwerks Corporation quotations are sent in a .PDF file attachment with a unique ID number generated by our proprietary quotation system. Quotations received via any other form of communication will not be honored.
CONFIDENTIALITY NOTICE: This e-mail, including attachments, may contain legally privileged, confidential or other information proprietary to Magwerks Corporation and is intended solely for the use of the individual to whom it addresses. If the reader of this e-mail is not the intended recipient or authorized agent, the reader is hereby notified that any unauthorized viewing, dissemination, distribution or copying of this e-mail is strictly prohibited. If you have received this e-mail in error, please notify the sender by replying to this message and destroy all occurrences of this e-mail immediately.
Thank you.
Attachments:
[text/x-vcard] justin.vcf (258B, 2-justin.vcf)
download | inline:
begin:vcard
fn:Justin Graf
n:Graf;Justin
org:Magwerks Corp
adr:;;501 Commerce Drive;Danville ;IN;46122;USA
email;internet:[email protected]
tel;work:317-241-8011 ext 703
tel;fax:317-241-8015
x-mozilla-html:FALSE
url:www.magwerks.com
version:2.1
end:vcard
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 18:30 John R Pierce <[email protected]>
parent: Justin Graf <[email protected]>
0 siblings, 0 replies; 38+ messages in thread
From: John R Pierce @ 2010-06-08 18:30 UTC (permalink / raw)
To: [email protected]
Justin Graf wrote:
> There are linux chm readers
>
...
Note that even Microsoft deprecated CHM back in 2003 after it was
realized it was full of potential security exploits that couldn't
readily be abated.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-08 19:56 Josh Kupershmidt <[email protected]>
parent: John Gage <[email protected]>
4 siblings, 1 reply; 38+ messages in thread
From: Josh Kupershmidt @ 2010-06-08 19:56 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
On Tue, Jun 8, 2010 at 5:04 AM, John Gage <[email protected]> wrote:
> I do suggest that a plain text file of the entire documentation be made part
> of the documentation armamentarium.
Not that I see a whole lot of utility in this endeavor, but it's
possible to do a decent PDF to plain text conversion. I tried some of
the online tools that do this and found <http://www.pdftextonline.com;
to do the best job with the Postgres manual. I didn't bother trying
any client-side applications which do the same job.
Attached is a short snippet of a text export of the PDF manual.
Josh
Preface
This book is the official documentation of PostgreSQL. It has been written by the PostgreSQL develop-
ers and other volunteers in parallel to the development of the PostgreSQL software. It describes all the
functionality that the current version of PostgreSQL officially supports.
To make the large amount of information about PostgreSQL manageable, this book has been organized
in several parts. Each part is targeted at a different class of users, or at users in different stages of their
PostgreSQL experience:
· Part I is an informal introduction for new users.
· Part II documents the SQL query language environment, including data types and functions, as well as
user-level performance tuning. Every PostgreSQL user should read this.
· Part III describes the installation and administration of the server. Everyone who runs a PostgreSQL
server, be it for private use or for others, should read this part.
· Part IV describes the programming interfaces for PostgreSQL client programs.
· Part V contains information for advanced users about the extensibility capabilities of the server. Topics
include user-defined data types and functions.
· Part VI contains reference information about SQL commands, client and server programs. This part
supports the other parts with structured information sorted by command or program.
· Part VII contains assorted information that might be of use to PostgreSQL developers.
1. What is PostgreSQL?
PostgreSQL is an object-relational database management system (ORDBMS) based on POSTGRES,
Version 4.21, developed at the University of California at Berkeley Computer Science Department. POST-
GRES pioneered many concepts that only became available in some commercial database systems much
later.
PostgreSQL is an open-source descendant of this original Berkeley code. It supports a large part of the
SQL standard and offers many modern features:
· complex queries
· foreign keys
· triggers
· views
· transactional integrity
· multiversion concurrency control
Also, PostgreSQL can be extended by the user in many ways, for example by adding new
· data types
1. http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html
xlix
Preface
· functions
· operators
· aggregate functions
· index methods
· procedural languages
And because of the liberal license, PostgreSQL can be used, modified, and distributed by anyone free of
charge for any purpose, be it private, commercial, or academic.
2. A Brief History of PostgreSQL
The object-relational database management system now known as PostgreSQL is derived from the POST-
GRES package written at the University of California at Berkeley. With over two decades of development
behind it, PostgreSQL is now the most advanced open-source database available anywhere.
2.1. The Berkeley POSTGRES Project
The POSTGRES project, led by Professor Michael Stonebraker, was sponsored by the Defense Advanced
Research Projects Agency (DARPA), the Army Research Office (ARO), the National Science Foundation
(NSF), and ESL, Inc. The implementation of POSTGRES began in 1986. The initial concepts for the
system were presented in The design of POSTGRES , and the definition of the initial data model appeared
in The POSTGRES data model . The design of the rule system at that time was described in The design
of the POSTGRES rules system. The rationale and architecture of the storage manager were detailed in
The design of the POSTGRES storage system .
POSTGRES has undergone several major releases since then. The first “demoware” system became op-
erational in 1987 and was shown at the 1988 ACM-SIGMOD Conference. Version 1, described in The
implementation of POSTGRES , was released to a few external users in June 1989. In response to a critique
of the first rule system ( A commentary on the POSTGRES rules system ), the rule system was redesigned
( On Rules, Procedures, Caching and Views in Database Systems ), and Version 2 was released in June
1990 with the new rule system. Version 3 appeared in 1991 and added support for multiple storage man-
agers, an improved query executor, and a rewritten rule system. For the most part, subsequent releases
until Postgres95 (see below) focused on portability and reliability.
POSTGRES has been used to implement many different research and production applications. These in-
clude: a financial data analysis system, a jet engine performance monitoring package, an asteroid tracking
database, a medical information database, and several geographic information systems. POSTGRES has
also been used as an educational tool at several universities. Finally, Illustra Information Technologies
(later merged into Informix2, which is now owned by IBM3) picked up the code and commercialized it.
In late 1992, POSTGRES became the primary data manager for the Sequoia 2000 scientific computing
project4.
The size of the external user community nearly doubled during 1993. It became increasingly obvious that
maintenance of the prototype code and support was taking up large amounts of time that should have been
2. http://www.informix.com/
3. http://www.ibm.com/
4. http://meteora.ucsd.edu/s2k/s2k_home.html
l
Preface
devoted to database research. In an effort to reduce this support burden, the Berkeley POSTGRES project
officially ended with Version 4.2.
2.2. Postgres95
In 1994, Andrew Yu and Jolly Chen added an SQL language interpreter to POSTGRES. Under a new
name, Postgres95 was subsequently released to the web to find its own way in the world as an open-
source descendant of the original POSTGRES Berkeley code.
Postgres95 code was completely ANSI C and trimmed in size by 25%. Many internal changes improved
performance and maintainability. Postgres95 release 1.0.x ran about 30-50% faster on the Wisconsin
Benchmark compared to POSTGRES, Version 4.2. Apart from bug fixes, the following were the major
enhancements:
· The query language PostQUEL was replaced with SQL (implemented in the server). Subqueries were
not supported until PostgreSQL (see below), but they could be imitated in Postgres95 with user-defined
SQL functions. Aggregate functions were re-implemented. Support for the GROUP BY query clause was
also added.
· A new program (psql) was provided for interactive SQL queries, which used GNU Readline. This
largely superseded the old monitor program.
· A new front-end library, libpgtcl, supported Tcl-based clients. A sample shell, pgtclsh, provided
new Tcl commands to interface Tcl programs with the Postgres95 server.
· The large-object interface was overhauled. The inversion large objects were the only mechanism for
storing large objects. (The inversion file system was removed.)
· The instance-level rule system was removed. Rules were still available as rewrite rules.
· A short tutorial introducing regular SQL features as well as those of Postgres95 was distributed with
the source code
· GNU make (instead of BSD make) was used for the build. Also, Postgres95 could be compiled with an
unpatched GCC (data alignment of doubles was fixed).
2.3. PostgreSQL
By 1996, it became clear that the name “Postgres95” would not stand the test of time. We chose a new
name, PostgreSQL, to reflect the relationship between the original POSTGRES and the more recent ver-
sions with SQL capability. At the same time, we set the version numbering to start at 6.0, putting the
numbers back into the sequence originally begun by the Berkeley POSTGRES project.
Many people continue to refer to PostgreSQL as “Postgres” (now rarely in all capital letters) because of
tradition or because it is easier to pronounce. This usage is widely accepted as a nickname or alias.
The emphasis during development of Postgres95 was on identifying and understanding existing problems
in the server code. With PostgreSQL, the emphasis has shifted to augmenting features and capabilities,
although work continues in all areas.
li
Preface
Details about what has happened in PostgreSQL since then can be found in Appendix E.
3. Conventions
This book uses the following typographical conventions to mark certain portions of text: new terms,
foreign phrases, and other important passages are emphasized in italics. Everything that represents in-
put or output of the computer, in particular commands, program code, and screen output, is shown in a
monospaced font (example). Within such passages, italics (example) indicate placeholders; you must
insert an actual value instead of the placeholder. On occasion, parts of program code are emphasized in
bold face (example), if they have been added or changed since the preceding example.
The following conventions are used in the synopsis of a command: brackets ([ and ]) indicate optional
parts. (In the synopsis of a Tcl command, question marks (?) are used instead, as is usual in Tcl.) Braces
({ and }) and vertical lines (|) indicate that you must choose one alternative. Dots (...) mean that the
preceding element can be repeated.
Where it enhances the clarity, SQL commands are preceded by the prompt =>, and shell commands are
preceded by the prompt $. Normally, prompts are not shown, though.
An administrator is generally a person who is in charge of installing and running the server. A user
could be anyone who is using, or wants to use, any part of the PostgreSQL system. These terms should
not be interpreted too narrowly; this book does not have fixed presumptions about system administration
procedures.
Attachments:
[text/plain] snippet_pdf_to_text.txt (11.5K, 2-snippet_pdf_to_text.txt)
download | inline:
Preface
This book is the official documentation of PostgreSQL. It has been written by the PostgreSQL develop-
ers and other volunteers in parallel to the development of the PostgreSQL software. It describes all the
functionality that the current version of PostgreSQL officially supports.
To make the large amount of information about PostgreSQL manageable, this book has been organized
in several parts. Each part is targeted at a different class of users, or at users in different stages of their
PostgreSQL experience:
· Part I is an informal introduction for new users.
· Part II documents the SQL query language environment, including data types and functions, as well as
user-level performance tuning. Every PostgreSQL user should read this.
· Part III describes the installation and administration of the server. Everyone who runs a PostgreSQL
server, be it for private use or for others, should read this part.
· Part IV describes the programming interfaces for PostgreSQL client programs.
· Part V contains information for advanced users about the extensibility capabilities of the server. Topics
include user-defined data types and functions.
· Part VI contains reference information about SQL commands, client and server programs. This part
supports the other parts with structured information sorted by command or program.
· Part VII contains assorted information that might be of use to PostgreSQL developers.
1. What is PostgreSQL?
PostgreSQL is an object-relational database management system (ORDBMS) based on POSTGRES,
Version 4.21, developed at the University of California at Berkeley Computer Science Department. POST-
GRES pioneered many concepts that only became available in some commercial database systems much
later.
PostgreSQL is an open-source descendant of this original Berkeley code. It supports a large part of the
SQL standard and offers many modern features:
· complex queries
· foreign keys
· triggers
· views
· transactional integrity
· multiversion concurrency control
Also, PostgreSQL can be extended by the user in many ways, for example by adding new
· data types
1. http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html
xlix
Preface
· functions
· operators
· aggregate functions
· index methods
· procedural languages
And because of the liberal license, PostgreSQL can be used, modified, and distributed by anyone free of
charge for any purpose, be it private, commercial, or academic.
2. A Brief History of PostgreSQL
The object-relational database management system now known as PostgreSQL is derived from the POST-
GRES package written at the University of California at Berkeley. With over two decades of development
behind it, PostgreSQL is now the most advanced open-source database available anywhere.
2.1. The Berkeley POSTGRES Project
The POSTGRES project, led by Professor Michael Stonebraker, was sponsored by the Defense Advanced
Research Projects Agency (DARPA), the Army Research Office (ARO), the National Science Foundation
(NSF), and ESL, Inc. The implementation of POSTGRES began in 1986. The initial concepts for the
system were presented in The design of POSTGRES , and the definition of the initial data model appeared
in The POSTGRES data model . The design of the rule system at that time was described in The design
of the POSTGRES rules system. The rationale and architecture of the storage manager were detailed in
The design of the POSTGRES storage system .
POSTGRES has undergone several major releases since then. The first “demoware” system became op-
erational in 1987 and was shown at the 1988 ACM-SIGMOD Conference. Version 1, described in The
implementation of POSTGRES , was released to a few external users in June 1989. In response to a critique
of the first rule system ( A commentary on the POSTGRES rules system ), the rule system was redesigned
( On Rules, Procedures, Caching and Views in Database Systems ), and Version 2 was released in June
1990 with the new rule system. Version 3 appeared in 1991 and added support for multiple storage man-
agers, an improved query executor, and a rewritten rule system. For the most part, subsequent releases
until Postgres95 (see below) focused on portability and reliability.
POSTGRES has been used to implement many different research and production applications. These in-
clude: a financial data analysis system, a jet engine performance monitoring package, an asteroid tracking
database, a medical information database, and several geographic information systems. POSTGRES has
also been used as an educational tool at several universities. Finally, Illustra Information Technologies
(later merged into Informix2, which is now owned by IBM3) picked up the code and commercialized it.
In late 1992, POSTGRES became the primary data manager for the Sequoia 2000 scientific computing
project4.
The size of the external user community nearly doubled during 1993. It became increasingly obvious that
maintenance of the prototype code and support was taking up large amounts of time that should have been
2. http://www.informix.com/
3. http://www.ibm.com/
4. http://meteora.ucsd.edu/s2k/s2k_home.html
l
Preface
devoted to database research. In an effort to reduce this support burden, the Berkeley POSTGRES project
officially ended with Version 4.2.
2.2. Postgres95
In 1994, Andrew Yu and Jolly Chen added an SQL language interpreter to POSTGRES. Under a new
name, Postgres95 was subsequently released to the web to find its own way in the world as an open-
source descendant of the original POSTGRES Berkeley code.
Postgres95 code was completely ANSI C and trimmed in size by 25%. Many internal changes improved
performance and maintainability. Postgres95 release 1.0.x ran about 30-50% faster on the Wisconsin
Benchmark compared to POSTGRES, Version 4.2. Apart from bug fixes, the following were the major
enhancements:
· The query language PostQUEL was replaced with SQL (implemented in the server). Subqueries were
not supported until PostgreSQL (see below), but they could be imitated in Postgres95 with user-defined
SQL functions. Aggregate functions were re-implemented. Support for the GROUP BY query clause was
also added.
· A new program (psql) was provided for interactive SQL queries, which used GNU Readline. This
largely superseded the old monitor program.
· A new front-end library, libpgtcl, supported Tcl-based clients. A sample shell, pgtclsh, provided
new Tcl commands to interface Tcl programs with the Postgres95 server.
· The large-object interface was overhauled. The inversion large objects were the only mechanism for
storing large objects. (The inversion file system was removed.)
· The instance-level rule system was removed. Rules were still available as rewrite rules.
· A short tutorial introducing regular SQL features as well as those of Postgres95 was distributed with
the source code
· GNU make (instead of BSD make) was used for the build. Also, Postgres95 could be compiled with an
unpatched GCC (data alignment of doubles was fixed).
2.3. PostgreSQL
By 1996, it became clear that the name “Postgres95” would not stand the test of time. We chose a new
name, PostgreSQL, to reflect the relationship between the original POSTGRES and the more recent ver-
sions with SQL capability. At the same time, we set the version numbering to start at 6.0, putting the
numbers back into the sequence originally begun by the Berkeley POSTGRES project.
Many people continue to refer to PostgreSQL as “Postgres” (now rarely in all capital letters) because of
tradition or because it is easier to pronounce. This usage is widely accepted as a nickname or alias.
The emphasis during development of Postgres95 was on identifying and understanding existing problems
in the server code. With PostgreSQL, the emphasis has shifted to augmenting features and capabilities,
although work continues in all areas.
li
Preface
Details about what has happened in PostgreSQL since then can be found in Appendix E.
3. Conventions
This book uses the following typographical conventions to mark certain portions of text: new terms,
foreign phrases, and other important passages are emphasized in italics. Everything that represents in-
put or output of the computer, in particular commands, program code, and screen output, is shown in a
monospaced font (example). Within such passages, italics (example) indicate placeholders; you must
insert an actual value instead of the placeholder. On occasion, parts of program code are emphasized in
bold face (example), if they have been added or changed since the preceding example.
The following conventions are used in the synopsis of a command: brackets ([ and ]) indicate optional
parts. (In the synopsis of a Tcl command, question marks (?) are used instead, as is usual in Tcl.) Braces
({ and }) and vertical lines (|) indicate that you must choose one alternative. Dots (...) mean that the
preceding element can be repeated.
Where it enhances the clarity, SQL commands are preceded by the prompt =>, and shell commands are
preceded by the prompt $. Normally, prompts are not shown, though.
An administrator is generally a person who is in charge of installing and running the server. A user
could be anyone who is using, or wants to use, any part of the PostgreSQL system. These terms should
not be interpreted too narrowly; this book does not have fixed presumptions about system administration
procedures.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 05:28 John Gage <[email protected]>
parent: Josh Kupershmidt <[email protected]>
0 siblings, 3 replies; 38+ messages in thread
From: John Gage @ 2010-06-09 05:28 UTC (permalink / raw)
To: PostgreSQL - General <[email protected]>
1) On a list that howls with complaints when posts are in html, it is
surprising that there is resistance to the idea of documentation in
plain text.
2) Posters are correctly referred to the documentation as frequently
as possible. In fact, very frequently. The frequency might decrease
if the documentation were in plain text. It is easier to search a
single plain text file than any other source, except perhaps the
database itself.
3) Postgres is getting pushed off the map at the low end by MySQL, now
owned by Oracle. If Postgres ceased to exist, Ellison would be
thrilled. I chose A2 Hosting (with whom I am very happy) for my
website because they support Postgres. I'm writing cgi scripts in
perl. I had to install the postgres driver for dbi. It was not pre-
installed. There are about four buttons for MySQL on the cPanel and
two farther over on the right for Postgres.
An anecdote. I discovered the tsvector functionality a while back. I
have used it to create indices for my text files and several other
tasks. I recently was re-looking at my files and saw
"tsvector::text". I had forgotten that the double colon is one way to
cast a type. Double colon is not in the html index of the
documentation. I found it by searching my plain text version of the
pdf file. In my opinion, the html documentation is useful for reading
it like a novel or referencing it in these lists.
On Jun 8, 2010, at 9:56 PM, Josh Kupershmidt wrote:
> Not that I see a whole lot of utility in this endeavor
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 06:24 Greg Smith <[email protected]>
parent: John Gage <[email protected]>
2 siblings, 0 replies; 38+ messages in thread
From: Greg Smith @ 2010-06-09 06:24 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
John Gage wrote:
> Posters are correctly referred to the documentation as frequently as
> possible. In fact, very frequently. The frequency might decrease if
> the documentation were in plain text. It is easier to search a single
> plain text file than any other source, except perhaps the database
> itself.
In reality searches are being done on the web, which combines the HTML
version of the official documentation with blog posts, presentation
materials, the wiki, and similar other resources. This is why I don't
actually care about a text version of the docs; I've just gotten used to
using Google to search the PostgreSQL documentation. The occasional
time when I know I just want to search the manual instead, I can search
the PDF version. Neither of those are great solutions, but they're good
enough that it's not worth fighting to build a text version over as I
see it. I'd use it if it were around, but there's little motivation for
most of us to work on it.
> Postgres is getting pushed off the map at the low end by MySQL, now
> owned by Oracle.
The dynamics are much more complicated than that. Big MySQL sites are
switching to NoSQL; medium sized MySQL sites are switching to PostgreSQL
to get rid of scaling and reliability issues (I personally have been
seeing a lot of this from Rails installs lately); small to medium size
Oracle shops are switching to PostgreSQL to lower licensing costs.
The idea that plain-text documentation for the database would be a
significant driver in any of these trends would be greatly exaggerating
the significance of a technical detail important to a pretty small
number of people. On my personal list of "things that could be improved
in the documentation", good plain text format is there, but there's a
whole lot of things above it.
--
Greg Smith 2ndQuadrant US Baltimore, MD
PostgreSQL Training, Services and Support
[email protected] www.2ndQuadrant.us
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 06:59 Brian Modra <[email protected]>
parent: John Gage <[email protected]>
2 siblings, 2 replies; 38+ messages in thread
From: Brian Modra @ 2010-06-09 06:59 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
On 09/06/2010, John Gage <[email protected]> wrote:
> 1) On a list that howls with complaints when posts are in html, it is
> surprising that there is resistance to the idea of documentation in
> plain text.
>
> 2) Posters are correctly referred to the documentation as frequently
> as possible. In fact, very frequently. The frequency might decrease
> if the documentation were in plain text. It is easier to search a
> single plain text file than any other source, except perhaps the
> database itself.
>
> 3) Postgres is getting pushed off the map at the low end by MySQL, now
> owned by Oracle. If Postgres ceased to exist, Ellison would be
> thrilled. I chose A2 Hosting (with whom I am very happy) for my
> website because they support Postgres. I'm writing cgi scripts in
> perl. I had to install the postgres driver for dbi. It was not pre-
> installed. There are about four buttons for MySQL on the cPanel and
> two farther over on the right for Postgres.
>
> An anecdote. I discovered the tsvector functionality a while back. I
> have used it to create indices for my text files and several other
> tasks. I recently was re-looking at my files and saw
> "tsvector::text". I had forgotten that the double colon is one way to
> cast a type. Double colon is not in the html index of the
> documentation. I found it by searching my plain text version of the
> pdf file. In my opinion, the html documentation is useful for reading
> it like a novel or referencing it in these lists.
>
>
> On Jun 8, 2010, at 9:56 PM, Josh Kupershmidt wrote:
>
>> Not that I see a whole lot of utility in this endeavor
Personally I like to use html docs, and it would be good if the
documentation were downloadable from the postgresql website in other
formats, for convenience...
But, what I use is this, which works pretty well:
(e.g. to get the 8.1 dosc)
mkdir postgresql
cd postgresql
wget -r -nH -l 10 -k -np
http://www.postgresql.org/docs/8.1/interactive/index.html
... then after it all downloads:
open the file docs/8.1/interactive/index.html
in your web browser.
e.g.
links docs/8.1/interactive/index.html
HTML is "text", so you can search using grep e.g.
grep -r "ALTER TABLE .* ADD COLUMN" docs/8.1
>
>
> --
> Sent via pgsql-general mailing list ([email protected])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-general
>
--
Brian Modra Land line: +27 23 5411 462
Mobile: +27 79 69 77 082
5 Jan Louw Str, Prince Albert, 6930
Postal: P.O. Box 2, Prince Albert 6930
South Africa
http://www.zwartberg.com/
Fax: +27865510467
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 07:44 Torsten Zühlsdorff <[email protected]>
parent: Brian Modra <[email protected]>
1 sibling, 1 reply; 38+ messages in thread
From: Torsten Zühlsdorff @ 2010-06-09 07:44 UTC (permalink / raw)
To: [email protected]
Brian Modra schrieb:
> Personally I like to use html docs, and it would be good if the
> documentation were downloadable from the postgresql website in other
> formats, for convenience...
>
> But, what I use is this, which works pretty well:
>
> (e.g. to get the 8.1 dosc)
>
> mkdir postgresql
> cd postgresql
> wget -r -nH -l 10 -k -np
> http://www.postgresql.org/docs/8.1/interactive/index.html
>
> ... then after it all downloads:
>
> open the file docs/8.1/interactive/index.html
> in your web browser.
>
> e.g.
> links docs/8.1/interactive/index.html
>
>
> HTML is "text", so you can search using grep e.g.
> grep -r "ALTER TABLE .* ADD COLUMN" docs/8.1
Thats the way i do too. A huge pdf is often not very helpful. In my
personal case i programm often in a train, using my laptop. Searching a
PDF with more than 1.000 pages really hits my battery. With html-files i
could preselect the items to search.
Also it's possible to import the html-files in a postgres-db and using
fulltext-search. ;)
Greetings,
Torsten
--
http://www.dddbl.de - ein Datenbank-Layer, der die Arbeit mit 8
verschiedenen Datenbanksystemen abstrahiert,
Queries von Applikationen trennt und automatisch die Query-Ergebnisse
auswerten kann.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 08:24 Dave Coventry <[email protected]>
parent: Torsten Zühlsdorff <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Dave Coventry @ 2010-06-09 08:24 UTC (permalink / raw)
To: ; +Cc: [email protected]
My tupp'th:
Formatted text, whether PDF, HTML or (heaven forbid!) Word Documents,
is easier to read than unformatted plain text, and those of us without
the OP's very admirable proficiency in vi remain at the mercy of the
various readers and their associated search functions.
However, I sure that it's not too arduous a task to extract the text
in these documents and strip them of their formatting?
Or am I missing something?
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 09:38 Dimitri Fontaine <[email protected]>
parent: Dave Coventry <[email protected]>
0 siblings, 0 replies; 38+ messages in thread
From: Dimitri Fontaine @ 2010-06-09 09:38 UTC (permalink / raw)
To: Dave Coventry <[email protected]>; +Cc: [email protected]
Dave Coventry <[email protected]> writes:
> Formatted text, whether PDF, HTML or (heaven forbid!) Word Documents,
> is easier to read than unformatted plain text, and those of us without
> the OP's very admirable proficiency in vi remain at the mercy of the
> various readers and their associated search functions.
>
> However, I sure that it's not too arduous a task to extract the text
> in these documents and strip them of their formatting?
>
> Or am I missing something?
Info documentation format. Text based, super user aware, easy to
browse and search, has an index.
You can even produce postgres.info today, it's just not optimised to be
very friendly, it's missing mainly convenient table support and
index.
Regards,
--
dim
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-09 16:46 Alvaro Herrera <[email protected]>
parent: John Gage <[email protected]>
2 siblings, 0 replies; 38+ messages in thread
From: Alvaro Herrera @ 2010-06-09 16:46 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
Excerpts from John Gage's message of mié jun 09 01:28:54 -0400 2010:
> I recently was re-looking at my files and saw
> "tsvector::text". I had forgotten that the double colon is one way to
> cast a type. Double colon is not in the html index of the
> documentation.
I just added an index entry for ::, thanks for pointing out that it was
missing.
If you notice other missing index entries, do not hesitate to point it
out in this mailing list or pgsql-docs.
--
Álvaro Herrera <[email protected]>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 00:18 Lew <[email protected]>
parent: Brian Modra <[email protected]>
1 sibling, 0 replies; 38+ messages in thread
From: Lew @ 2010-06-10 00:18 UTC (permalink / raw)
To: [email protected]
Brian Modra wrote:
> Personally I like to use html docs, and it would be good if the
> documentation were downloadable from the postgresql website in other
> formats, for convenience...
Good thing it is, then, albeit not in the most convenient format, i.e.,
DocBook. But then, from there you can generate pretty much any format you
want, right?
--
Lew
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 06:50 Peter Eisentraut <[email protected]>
parent: John Gage <[email protected]>
4 siblings, 1 reply; 38+ messages in thread
From: Peter Eisentraut @ 2010-06-10 06:50 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>
On tis, 2010-06-08 at 11:04 +0200, John Gage wrote:
>
> Yet, the only one file edition of the Postgres documentation is
> in...pdf format. Huh?
>
> I know. I know. I have already brought this up. And various ways
> of
> creating a one file text edition of the documentation have been
> proposed to me. I know.
>
> But either I am a visitor from the Crab Nebula, or there is someone
> else out there who would like to have a text file of the entire
> documentation.
As I said back then, doing this is straightforward, but we kind of need
more than one user who asks for it before we make it part of a regular
service, which comes with maintenance costs.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 15:16 Alvaro Herrera <[email protected]>
parent: Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Alvaro Herrera @ 2010-06-10 15:16 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: John Gage <[email protected]>; PostgreSQL - General <[email protected]>
Excerpts from Peter Eisentraut's message of jue jun 10 02:50:14 -0400 2010:
> On tis, 2010-06-08 at 11:04 +0200, John Gage wrote:
> >
> > Yet, the only one file edition of the Postgres documentation is
> > in...pdf format. Huh?
> >
> > I know. I know. I have already brought this up. And various ways
> > of
> > creating a one file text edition of the documentation have been
> > proposed to me. I know.
> >
> > But either I am a visitor from the Crab Nebula, or there is someone
> > else out there who would like to have a text file of the entire
> > documentation.
>
> As I said back then, doing this is straightforward, but we kind of need
> more than one user who asks for it before we make it part of a regular
> service, which comes with maintenance costs.
Hey, count me as another interested person in a single-file plain-text
doc output format.
--
Álvaro Herrera <[email protected]>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 15:24 Tom Lane <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Tom Lane @ 2010-06-10 15:24 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; John Gage <[email protected]>; PostgreSQL - General <[email protected]>
Alvaro Herrera <[email protected]> writes:
> Excerpts from Peter Eisentraut's message of jue jun 10 02:50:14 -0400 2010:
>> As I said back then, doing this is straightforward, but we kind of need
>> more than one user who asks for it before we make it part of a regular
>> service, which comes with maintenance costs.
> Hey, count me as another interested person in a single-file plain-text
> doc output format.
Well, there are two separate things here:
* providing a Makefile target to build plain-text output.
* shipping prebuilt plain text docs in standard distributions.
I am for #1, not so much for #2, mainly on the grounds of size. But
given #1 it would be possible for packagers to make their own choices
about whether to include plain-text docs.
regards, tom lane
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 15:33 Leif Biberg Kristensen <[email protected]>
parent: Tom Lane <[email protected]>
0 siblings, 2 replies; 38+ messages in thread
From: Leif Biberg Kristensen @ 2010-06-10 15:33 UTC (permalink / raw)
To: [email protected]
On Thursday 10. June 2010 17.24.00 Tom Lane wrote:
> Alvaro Herrera <[email protected]> writes:
> > Excerpts from Peter Eisentraut's message of jue jun 10 02:50:14 -0400
2010:
> >> As I said back then, doing this is straightforward, but we kind of need
> >> more than one user who asks for it before we make it part of a regular
> >> service, which comes with maintenance costs.
>
> > Hey, count me as another interested person in a single-file plain-text
> > doc output format.
>
> Well, there are two separate things here:
>
> * providing a Makefile target to build plain-text output.
>
> * shipping prebuilt plain text docs in standard distributions.
>
> I am for #1, not so much for #2, mainly on the grounds of size. But
> given #1 it would be possible for packagers to make their own choices
> about whether to include plain-text docs.
Wouldn't it suffice to make it downloadable, like the pdf doc?
regards,
--
Leif Biberg Kristensen
http://solumslekt.org/blog/
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-10 20:57 John Gage <[email protected]>
parent: Leif Biberg Kristensen <[email protected]>
1 sibling, 0 replies; 38+ messages in thread
From: John Gage @ 2010-06-10 20:57 UTC (permalink / raw)
To: PostgreSQL - General <[email protected]>
Like all visitors from the Crab Nebula (except our leaders who are
genetically separate) I qualify as a novice when it comes to
Postgres. What is more, the people (humans, that is) who need the
documentation the most are those who, well, need the documentation the
most.
Hence, if this were to be made available, it would be great if it was
novice speed.
Thanks everyone for even contemplating it.
John
>> Well, there are two separate things here:
>>
>> * providing a Makefile target to build plain-text output.
>>
>> * shipping prebuilt plain text docs in standard distributions.
>>
>> I am for #1, not so much for #2, mainly on the grounds of size. But
>> given #1 it would be possible for packagers to make their own choices
>> about whether to include plain-text docs.
>
> Wouldn't it suffice to make it downloadable, like the pdf doc?
>
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-11 12:41 Robert Gravsjö <[email protected]>
parent: Leif Biberg Kristensen <[email protected]>
1 sibling, 1 reply; 38+ messages in thread
From: Robert Gravsjö @ 2010-06-11 12:41 UTC (permalink / raw)
To: [email protected]
Leif Biberg Kristensen skrev 2010-06-10 17.33:
> On Thursday 10. June 2010 17.24.00 Tom Lane wrote:
>> Alvaro Herrera<[email protected]> writes:
>>> Excerpts from Peter Eisentraut's message of jue jun 10 02:50:14 -0400
> 2010:
>>>> As I said back then, doing this is straightforward, but we kind of need
>>>> more than one user who asks for it before we make it part of a regular
>>>> service, which comes with maintenance costs.
>>
>>> Hey, count me as another interested person in a single-file plain-text
>>> doc output format.
>>
>> Well, there are two separate things here:
>>
>> * providing a Makefile target to build plain-text output.
>>
>> * shipping prebuilt plain text docs in standard distributions.
>>
>> I am for #1, not so much for #2, mainly on the grounds of size. But
>> given #1 it would be possible for packagers to make their own choices
>> about whether to include plain-text docs.
>
> Wouldn't it suffice to make it downloadable, like the pdf doc?
And/or make the HTML version downloadable side by side with the PDF.
There are good reasons for wanting access to the complete document when
being offline. PDF is not such a bad format but it do have some
limitations as have been previously mentioned.
As for building the docs I don't think everyone, not even all
developers, has the tool chain installed (or even wants to).
Regards,
roppert
>
> regards,
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 01:20 Bruce Momjian <[email protected]>
parent: Robert Gravsjö <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Bruce Momjian @ 2010-06-12 01:20 UTC (permalink / raw)
To: Robert Gravsjö <[email protected]>; +Cc: [email protected]
Robert Gravsjö wrote:
> >> I am for #1, not so much for #2, mainly on the grounds of size. But
> >> given #1 it would be possible for packagers to make their own choices
> >> about whether to include plain-text docs.
> >
> > Wouldn't it suffice to make it downloadable, like the pdf doc?
>
> And/or make the HTML version downloadable side by side with the PDF.
That might be easy to do. We already build the HTML, and requiring
people to recursively use wget is not user-friendly.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ None of us is going to be here forever. +
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 09:18 John Gage <[email protected]>
parent: Bruce Momjian <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: John Gage @ 2010-06-12 09:18 UTC (permalink / raw)
To: PostgreSQL - General <[email protected]>; +Cc: Robert Gravsjö <[email protected]>; Bruce Momjian <[email protected]>
A one file html version would be a godsend.
On Jun 12, 2010, at 3:20 AM, Bruce Momjian wrote:
> Robert Gravsjö wrote:
>>>> I am for #1, not so much for #2, mainly on the grounds of size.
>>>> But
>>>> given #1 it would be possible for packagers to make their own
>>>> choices
>>>> about whether to include plain-text docs.
>>>
>>> Wouldn't it suffice to make it downloadable, like the pdf doc?
>>
>> And/or make the HTML version downloadable side by side with the PDF.
>
> That might be easy to do. We already build the HTML, and requiring
> people to recursively use wget is not user-friendly.
>
> --
> Bruce Momjian <[email protected]> http://momjian.us
> EnterpriseDB http://enterprisedb.com
>
> + None of us is going to be here forever. +
>
> --
> Sent via pgsql-general mailing list ([email protected])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-general
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 09:56 Peter Eisentraut <[email protected]>
parent: John Gage <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Peter Eisentraut @ 2010-06-12 09:56 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>; Bruce Momjian <[email protected]>
On lör, 2010-06-12 at 11:18 +0200, John Gage wrote:
> A one file html version would be a godsend.
I've committed a build target for that now. Use 'make postgres.html' in
doc/src/sgml/.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 13:10 Tom Lane <[email protected]>
parent: Peter Eisentraut <[email protected]>
0 siblings, 4 replies; 38+ messages in thread
From: Tom Lane @ 2010-06-12 13:10 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: John Gage <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>; Bruce Momjian <[email protected]>
Peter Eisentraut <[email protected]> writes:
> On lör, 2010-06-12 at 11:18 +0200, John Gage wrote:
>> A one file html version would be a godsend.
> I've committed a build target for that now. Use 'make postgres.html' in
> doc/src/sgml/.
Huh, is that actually worth anything? How many browsers will open it
without crashing, or will navigate the page with decent performance
if they do manage to open it?
(Not that I object to providing this Make target. But I thought the
discussion was about plain-text output.)
regards, tom lane
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 14:34 John Gage <[email protected]>
parent: Tom Lane <[email protected]>
3 siblings, 0 replies; 38+ messages in thread
From: John Gage @ 2010-06-12 14:34 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: PostgreSQL - General <[email protected]>; Bruce Momjian <[email protected]>
It was. But if the compromise is single file html, that is a vast
improvement over the current system imho.
What I want is the thing that is maximally amenable to being searched
conveniently using all the tools at our disposal especially regular
expressons. The point has been made that Google is the best system to
search for Postgres documentation/knowledge/etc. Frankly, I don't
necessarily agree with that, particularly for the novice. The
documentation is where it is at, and it is the documentation that is
referenced the most in these posts.
But there are no dichotomies here. It is not either or. It is a
balance between what is easiest to produce and maintain and what is
most productive to use.
And the background for my request is my respect for the extraordinary
power and elegance of postgres.
John
On Jun 12, 2010, at 3:10 PM, Tom Lane wrote:
> Peter Eisentraut <[email protected]> writes:
>> On lör, 2010-06-12 at 11:18 +0200, John Gage wrote:
>>> A one file html version would be a godsend.
>
>> I've committed a build target for that now. Use 'make
>> postgres.html' in
>> doc/src/sgml/.
>
> Huh, is that actually worth anything? How many browsers will open it
> without crashing, or will navigate the page with decent performance
> if they do manage to open it?
>
> (Not that I object to providing this Make target. But I thought the
> discussion was about plain-text output.)
>
> regards, tom lane
>
> --
> Sent via pgsql-general mailing list ([email protected])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-general
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 14:35 Stephen Frost <[email protected]>
parent: Tom Lane <[email protected]>
3 siblings, 0 replies; 38+ messages in thread
From: Stephen Frost @ 2010-06-12 14:35 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; John Gage <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>; Bruce Momjian <[email protected]>
* Tom Lane ([email protected]) wrote:
> Peter Eisentraut <[email protected]> writes:
> > I've committed a build target for that now. Use 'make postgres.html' in
> > doc/src/sgml/.
>
> Huh, is that actually worth anything? How many browsers will open it
> without crashing, or will navigate the page with decent performance
> if they do manage to open it?
If it works with links, that'd probably work well for the use case
described...
Stephen
Attachments:
[application/pgp-signature] signature.asc (197B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 15:42 Peter Eisentraut <[email protected]>
parent: Tom Lane <[email protected]>
3 siblings, 1 reply; 38+ messages in thread
From: Peter Eisentraut @ 2010-06-12 15:42 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: John Gage <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>; Bruce Momjian <[email protected]>
On lör, 2010-06-12 at 09:10 -0400, Tom Lane wrote:
> Peter Eisentraut <[email protected]> writes:
> > On lör, 2010-06-12 at 11:18 +0200, John Gage wrote:
> >> A one file html version would be a godsend.
>
> > I've committed a build target for that now. Use 'make postgres.html' in
> > doc/src/sgml/.
>
> Huh, is that actually worth anything? How many browsers will open it
> without crashing, or will navigate the page with decent performance
> if they do manage to open it?
Text output is generated by going through HTML. I haven't figured out
the best way to do the second step yet. We use lynx for INSTALL and
HISTORY, but the results for this big file aren't very clean.
Browsers seem to handle the file OK, btw.
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 16:01 Bruce Momjian <[email protected]>
parent: Peter Eisentraut <[email protected]>
0 siblings, 2 replies; 38+ messages in thread
From: Bruce Momjian @ 2010-06-12 16:01 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Tom Lane <[email protected]>; John Gage <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>
Peter Eisentraut wrote:
> On l?r, 2010-06-12 at 09:10 -0400, Tom Lane wrote:
> > Peter Eisentraut <[email protected]> writes:
> > > On l?r, 2010-06-12 at 11:18 +0200, John Gage wrote:
> > >> A one file html version would be a godsend.
> >
> > > I've committed a build target for that now. Use 'make postgres.html' in
> > > doc/src/sgml/.
> >
> > Huh, is that actually worth anything? How many browsers will open it
> > without crashing, or will navigate the page with decent performance
> > if they do manage to open it?
>
> Text output is generated by going through HTML. I haven't figured out
> the best way to do the second step yet. We use lynx for INSTALL and
> HISTORY, but the results for this big file aren't very clean.
>
> Browsers seem to handle the file OK, btw.
Well, I tried lynx and the output looked fine to me, so I applied the
attached patch to allow single-page text output. You can see the HTML
and text file results here:
http://momjian.us/expire/
The new rule name is postgres.txt. The file size are:
7,789,730 postgres.html
5,155,672 postgres.txt
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ None of us is going to be here forever. +
Attachments:
[text/x-diff] /rtmp/diff (777B, 2-%2Frtmp%2Fdiff)
download | inline diff:
Index: doc/src/sgml/Makefile
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/Makefile,v
retrieving revision 1.145
diff -c -c -r1.145 Makefile
*** doc/src/sgml/Makefile 12 Jun 2010 15:42:44 -0000 1.145
--- doc/src/sgml/Makefile 12 Jun 2010 15:57:31 -0000
***************
*** 108,113 ****
--- 108,117 ----
postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl
$(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $<
+ # single-page text
+ postgres.txt: postgres.html
+ $(LYNX) -force_html -dump -nolist -stdin $< > $@
+
HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
@$(MKDIR_P) html
$(JADE.html.call) -V html-index $<
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 16:39 John Gage <[email protected]>
parent: Bruce Momjian <[email protected]>
1 sibling, 1 reply; 38+ messages in thread
From: John Gage @ 2010-06-12 16:39 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Tom Lane <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>
UFB! This was definitely worth the visit from the Nebula.
Thanks very, very much.
Sensational.
Thanks again,
John Gage
On Jun 12, 2010, at 6:01 PM, Bruce Momjian wrote:
>
> http://momjian.us/expire/
>
> The new rule name is postgres.txt. The file size are:
>
> 7,789,730 postgres.html
> 5,155,672 postgres.txt
>
> --
> Bruce Momjian <[email protected]> http://momjian.us
> EnterpriseDB http://enterprisedb.com
>
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 16:56 Bruce Momjian <[email protected]>
parent: John Gage <[email protected]>
0 siblings, 1 reply; 38+ messages in thread
From: Bruce Momjian @ 2010-06-12 16:56 UTC (permalink / raw)
To: John Gage <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Tom Lane <[email protected]>; PostgreSQL - General <[email protected]>; Robert Gravsjö <[email protected]>
John Gage wrote:
> UFB! This was definitely worth the visit from the Nebula.
>
> Thanks very, very much.
>
> Sensational.
>
> Thanks again,
>
> John Gage
We still have to decide how to make these accessible from our web site.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ None of us is going to be here forever. +
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: [GENERAL] Cognitive dissonance
@ 2010-06-12 17:13 John Gage <[email protected]>
parent: Bruce Momjian <[email protected]>
0 siblings, 0 replies; 38+ messages in thread
From: John Gage @ 2010-06-12 17:13 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: pgsql-docs
Ah, perhaps I have misunderstood. Double ah.
So that's the reason for the current html format: ease of browser
access.
On the other hand, the pdf file, at 17MB, is the biggest one and, as
far as I am concerned, the least useful.
I would just make the single file html and text files available for
download beside the pdf. See how many people take which format.
The only change I would make in the current html browser version is to
put the "main page" link at the top as well as the bottom.
Thanks again,
John
On Jun 12, 2010, at 6:56 PM, Bruce Momjian wrote:
>
> We still have to decide how to make these accessible from our web
> site.
>
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 17:15 Tim Landscheidt <[email protected]>
parent: Bruce Momjian <[email protected]>
1 sibling, 1 reply; 38+ messages in thread
From: Tim Landscheidt @ 2010-06-12 17:15 UTC (permalink / raw)
To: [email protected]
Bruce Momjian <[email protected]> wrote:
> [...]
> + # single-page text
> + postgres.txt: postgres.html
> + $(LYNX) -force_html -dump -nolist -stdin $< > $@
^^^^^^
> +
> [...]
Isn't that unnecessary/wrong as the filename is supplied on
the command line?
Tim
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-12 17:17 Bruce Momjian <[email protected]>
parent: Tim Landscheidt <[email protected]>
0 siblings, 0 replies; 38+ messages in thread
From: Bruce Momjian @ 2010-06-12 17:17 UTC (permalink / raw)
To: Tim Landscheidt <[email protected]>; +Cc: [email protected]
Tim Landscheidt wrote:
> Bruce Momjian <[email protected]> wrote:
>
> > [...]
> > + # single-page text
> > + postgres.txt: postgres.html
> > + $(LYNX) -force_html -dump -nolist -stdin $< > $@
> ^^^^^^
> > +
> > [...]
>
> Isn't that unnecessary/wrong as the filename is supplied on
> the command line?
Ah, good catch. I wasn't able to test that because my lynx version
doesn't support -stdin. Thanks, and updated.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ None of us is going to be here forever. +
^ permalink raw reply [nested|flat] 38+ messages in thread
* Re: Cognitive dissonance
@ 2010-06-14 19:33 Chris Browne <[email protected]>
parent: Tom Lane <[email protected]>
3 siblings, 0 replies; 38+ messages in thread
From: Chris Browne @ 2010-06-14 19:33 UTC (permalink / raw)
To: [email protected]
[email protected] (Tom Lane) writes:
> Peter Eisentraut <[email protected]> writes:
>> On lör, 2010-06-12 at 11:18 +0200, John Gage wrote:
>>> A one file html version would be a godsend.
>
>> I've committed a build target for that now. Use 'make postgres.html' in
>> doc/src/sgml/.
>
> Huh, is that actually worth anything? How many browsers will open it
> without crashing, or will navigate the page with decent performance
> if they do manage to open it?
>
> (Not that I object to providing this Make target. But I thought the
> discussion was about plain-text output.)
I expect that having one HTML file would make it reasonably easy to
use lynx/links/w3m [some text-based HTML browser] to transform HTML
into plain text.
I should think that it would also enable using analagous tools to
transform HTML into eBook formats like ePub and mobi, which are the
frequently-preferable-formats on the emerging category of "electronic
book" appliances.
I have browsed the CHM form of the docs using a CHM reader on my
phone, and found that less than wonderful, which had a lot to do with
the reader not being particularly great. A format that plays well
with a decent reader may turn out pretty happily.
--
select 'cbbrowne' || '@' || 'cbbrowne.com';
http://cbbrowne.com/info/internet.html
"MS apparently now has a team dedicated to tracking problems with
Linux and publicizing them. I guess eventually they'll figure out
this back fires... ;)" -- William Burrow <[email protected]>
^ permalink raw reply [nested|flat] 38+ messages in thread
end of thread, other threads:[~2010-06-14 19:33 UTC | newest]
Thread overview: 38+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2010-06-08 09:04 Cognitive dissonance John Gage <[email protected]>
2010-06-08 12:07 ` Lew <[email protected]>
2010-06-08 14:23 ` Peter Hunsberger <[email protected]>
2010-06-08 15:36 ` Justin Graf <[email protected]>
2010-06-08 16:29 ` Chris Browne <[email protected]>
2010-06-08 15:01 ` Stephen Frost <[email protected]>
2010-06-08 16:42 ` John Gage <[email protected]>
2010-06-08 18:21 ` Justin Graf <[email protected]>
2010-06-08 18:30 ` John R Pierce <[email protected]>
2010-06-08 19:56 ` Josh Kupershmidt <[email protected]>
2010-06-09 05:28 ` John Gage <[email protected]>
2010-06-09 06:24 ` Greg Smith <[email protected]>
2010-06-09 06:59 ` Brian Modra <[email protected]>
2010-06-09 07:44 ` Torsten Zühlsdorff <[email protected]>
2010-06-09 08:24 ` Dave Coventry <[email protected]>
2010-06-09 09:38 ` Dimitri Fontaine <[email protected]>
2010-06-10 00:18 ` Lew <[email protected]>
2010-06-09 16:46 ` Alvaro Herrera <[email protected]>
2010-06-10 06:50 ` Peter Eisentraut <[email protected]>
2010-06-10 15:16 ` Alvaro Herrera <[email protected]>
2010-06-10 15:24 ` Tom Lane <[email protected]>
2010-06-10 15:33 ` Leif Biberg Kristensen <[email protected]>
2010-06-10 20:57 ` John Gage <[email protected]>
2010-06-11 12:41 ` Robert Gravsjö <[email protected]>
2010-06-12 01:20 ` Bruce Momjian <[email protected]>
2010-06-12 09:18 ` John Gage <[email protected]>
2010-06-12 09:56 ` Peter Eisentraut <[email protected]>
2010-06-12 13:10 ` Tom Lane <[email protected]>
2010-06-12 14:34 ` John Gage <[email protected]>
2010-06-12 14:35 ` Stephen Frost <[email protected]>
2010-06-12 15:42 ` Peter Eisentraut <[email protected]>
2010-06-12 16:01 ` Bruce Momjian <[email protected]>
2010-06-12 16:39 ` John Gage <[email protected]>
2010-06-12 16:56 ` Bruce Momjian <[email protected]>
2010-06-12 17:13 ` John Gage <[email protected]>
2010-06-12 17:15 ` Tim Landscheidt <[email protected]>
2010-06-12 17:17 ` Bruce Momjian <[email protected]>
2010-06-14 19:33 ` Chris Browne <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox