Update, polish, consistencify preface/intro sections.

doc/src/sgml/notation.sgml

@@ -1,71 +1,30 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.13 2000/12/22 21:51:58 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.14 2001/02/03 19:03:27 petere Exp $
 -->
 
-<sect1 id="terminology">
- <title>Terminology</title>
-
- <para>
-  The 
-  <Productname>Postgres</Productname> <firstterm>superuser</firstterm>
-  is the user named <replaceable>postgres</replaceable>
-  who owns the <Productname>Postgres</Productname>
-  binaries and database files.  As the database superuser, all
-  protection mechanisms may be bypassed and any data accessed
-  arbitrarily.  
-  In addition, the <Productname>Postgres</Productname> superuser is
-  allowed to execute
-  some support programs which are generally not available to all users.
-  Note that the <Productname>Postgres</Productname> superuser is
-  <emphasis>not</emphasis>
-  the same as the Unix superuser (which will be referred to as
-  <firstterm>root</firstterm>).
-  The superuser should have a non-zero user identifier
-  (<firstterm>UID</firstterm>) for security reasons.
- </para>
-
- <para>
-  The
-  <firstterm>database administrator</firstterm>
-  or <acronym>DBA</acronym>, is the person who is responsible for installing 
-  <Productname>Postgres</Productname> with mechanisms to
-  enforce a security policy for a site.  The DBA can add new users by
-  the method described below 
-  and maintain a set of template databases for use by
-  <application>createdb</application>.
- </para>
-
- <para>
-  The <application>postmaster</application>
-  is the process that acts as a clearing-house for requests 
-  to the <Productname>Postgres</Productname> system.
-  Frontend applications connect to the <application>postmaster</application>,
-  which keeps tracks of any system errors and communication between the
-  backend processes.  The <application>postmaster</application>
-  can take several command-line arguments to tune its behavior.
-  However, supplying arguments is necessary only if you intend to run multiple
-  sites or a non-default site.
- </para>
-
- <para>
-  The <Productname>Postgres</Productname> backend
-  (the actual executable program <application>postgres</application>) may be executed
-  directly from the user shell by the 
-  <Productname>Postgres</Productname> super-user 
-  (with the database name as an argument).  However,
-  doing this bypasses the shared buffer pool and lock table associated
-  with a postmaster/site, therefore this is not recommended in a multiuser
-  site.
- </para>
-</sect1>
-
 <sect1 id="notation">
- <title>Notation</title>
+ <title>Terminology and Notation</title>
 
  <para>
-  "<literal>...</literal>" or <filename>/usr/local/pgsql/</filename> 
-  at the front of a file name is used to represent the
-  path to the <Productname>Postgres</Productname> superuser's home directory.
+  The terms <quote>Postgres</quote> and <quote>PostgreSQL</quote> will be
+  used interchangeably to refer to the software that accompanies this
+  documentation.
+ </para>
+
+ <para>
+  An <firstterm>administrator</firstterm> is generally a person who is
+  in charge of installing and running the server.  A <firstterm>user</firstterm>
+  could be anyone who is using, or wants to use, any part of the
+  <productname>PostgreSQL</productname> system.  These terms should not
+  be interpreted too narrowly; this documentation set does not have fixed
+  presumptions about system administration procedures.
+ </para>
+
+ <para>
+  <filename>/usr/local/pgsql/</filename> is generally used as the root
+  directory of the installation and <filename>/usr/local/pgsql/data</filename>
+  as the directory with the database files.  These directories may vary
+  on your site, details can be derived in the <citetitle>Administrator's Guide</citetitle>.
  </para>
 
  <para>
@@ -77,28 +36,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.13 2000/12/22 21:51:58 pe
   indicates that you must choose one.
  </para>
 
- <para>
-  In examples, parentheses ("<literal>(</literal>" and "<literal>)</literal>") are
-  used to group boolean
-  expressions.  "<literal>|</literal>" is the boolean operator OR.
- </para>
-
  <para>
   Examples will show commands executed from various accounts and programs.
-  Commands executed from the root account will be preceeded with
-  "<literal>&gt;</literal>".
-  Commands executed from the <Productname>Postgres</Productname>
-  superuser account will be preceeded with "<literal>%</literal>", while commands
-  executed from an unprivileged user's account will be preceeded with
-  "<literal>$</literal>".
-  <acronym>SQL</acronym> commands will be preceeded with "<literal>=&gt;</literal>"
+  Commands executed from a Unix shell may be preceeded with a dollar sign
+  (<quote><literal>$</literal></quote>).  Commands executed from particular user
+  accounts such as root or postgres are specially flagged and explained.
+  <acronym>SQL</acronym> commands may be preceeded with
+  <quote><literal>=&gt;</literal></quote>
   or will have no leading prompt, depending on the context.
  </para>
 
  <note>
   <para>
-   At the time of writing (<Productname>Postgres</Productname> 7.0)
-   the notation for
+   The notation for
    flagging commands is not universally consistant throughout the
    documentation set.
    Please report problems to the documentation mailing list