Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.92) (envelope-from ) id 1jFLoJ-00049e-MA for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 17:51:56 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1jFLoI-00039k-Cr for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 17:51:54 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1jFLoH-00039d-Ug for pgsql-hackers@lists.postgresql.org; Fri, 20 Mar 2020 17:51:54 +0000 Received: from mail-qk1-x72a.google.com ([2607:f8b0:4864:20::72a]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jFLoE-0005GW-AB for pgsql-hackers@postgresql.org; Fri, 20 Mar 2020 17:51:53 +0000 Received: by mail-qk1-x72a.google.com with SMTP id d11so7787057qko.3 for ; Fri, 20 Mar 2020 10:51:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=2ndquadrant-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :content-transfer-encoding:in-reply-to:user-agent; bh=qDdktnB0DMOovWTk378B8SQ3+kkNybqGbPtppTApH4E=; b=h7mTIyP+i2qIciWCv8xusDguSzLqiROzpPA8enDxBaJ0eSa8TkHN/Oj7Wxtu/Z7A3L e/rJyO1Xh4ECK9aKclGMgKhZ0grFkEOeFjxmG0BPMI6kXlKGqk00+VosfQOQ3bTsGsR5 cVexZiz79Dmlll2ighHok1qd2E2knlSIZ8Ro+55mUF4HVw2frdtOTlDJiLeWMfQFzrku 9QiDge0FWoxqno/o7wdOZgzGEjoc7qhNObLRDIftyUmJrhgUPpcbu3D/7GoSO6+2HAiB /07PkQSyS9omOyWSIN1VDazD5ZFkDbD294DcAUvhEd3ausMOgaCdtW8DAsZoDJhuiQWV 4p9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=qDdktnB0DMOovWTk378B8SQ3+kkNybqGbPtppTApH4E=; b=khTF5wMYCu4wbGhNIFDz1hCs4oHwIVJcTC5KPrjp+7mk9gXCxIFV4hlbDjl2r+QqCq J5abJbTZ7MSjJfzdJFRTmQwhgI7I0kgMBODew2nqx19M8co3VFerQqXWcRTuQrSVMWFz g/RrCTO7OXZnswte/xAkqoGFM21FLqUcEAn5m6uFyqxsmsA/b75bYd1ycDW+ZeK3po5k rVeYY5xLd2JWlu0LbBVIGSpTmqNZFPifhsXcllZM4GCdWYO30nz/ApDo2rPF9/xvyLq5 kxJjmjb7SswWFDm4EDy8s8fzRbrUVlXVD0o2f7I0RaxVy1gs+dVU2vDyw46edF19dJ1b xqYg== X-Gm-Message-State: ANhLgQ2w6ZpkgtZzT79trZTOwvN18q48JBduOKM0Y8+pf1Vp06Gd3zqp 7pwju41ssQwl8dq7M5uUR7LM2Q== X-Google-Smtp-Source: ADFU+vs0vVvMF4v/f/oInO2858ddhuj7nX3i0i3W5ME6NKPPmGkvGT+GuRU33Phm/9r08biI63MW5Q== X-Received: by 2002:ae9:c011:: with SMTP id u17mr9135617qkk.92.1584726707739; Fri, 20 Mar 2020 10:51:47 -0700 (PDT) Received: from nimloth.alvh.no-ip.org ([201.186.208.119]) by smtp.gmail.com with ESMTPSA id a188sm4451517qkg.17.2020.03.20.10.51.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 20 Mar 2020 10:51:46 -0700 (PDT) Received: by nimloth.alvh.no-ip.org (Postfix, from userid 1000) id C04333007F6; Fri, 20 Mar 2020 14:51:44 -0300 (-03) Date: Fri, 20 Mar 2020 14:51:44 -0300 From: Alvaro Herrera To: Corey Huinker Cc: =?iso-8859-1?Q?J=FCrgen?= Purtz , Roger Harkavy , pgsql-hackers@postgresql.org, Fabien COELHO , Michael Paquier Subject: Re: Add A Glossary Message-ID: <20200320175144.GA20645@alvherre.pgsql> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="+HP7ph2BbKc20aGI" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --+HP7ph2BbKc20aGI Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit On 2020-Mar-20, Corey Huinker wrote: > > Jürgen mentioned off-list that the man page doesn't build. I was going to > > look into that, but if anyone has more familiarity with that, I'm listening. > Looking at this some more, I'm not sure anything needs to be done for man > pages. Yeah, I don't think he was saying that we needed to do anything to produce a glossary man page; rather that the "make man" command failed. I tried it here, and indeed it failed. But on further investigation, after a "make maintainer-clean" it no longer failed. I'm not sure what to make of it, but it seems that this patch needn't concern itself with that. I gave a read through the first few actual definitions. It's a much slower work than I thought! Attached you'll find the first few edits that I propose. Looking at the definition of "Aggregate" it seemed weird to have it stand as a verb infinitive. I looked up other glossaries, found this one https://www.gartner.com/en/information-technology/glossary?glossaryletter=T and realized that when they do verbs, they put the present participle (-ing) form. So I changed it to "Aggregating", and split out the "Aggregate function" into its own term. In Atomic, there seemed to be excessive use of in the definitions. Style guides seem to suggest to do that only the first time you use a term in a definition. I removed some markup. I'm not sure about some terms such as "analytic" and "backend server". I put them in XML comments for now. The other changes should be self-explanatory. It's hard to review work from a professional tech writer. I'm under the constant impression that I'm ruining somebody's perfect end product, making a fool of myself. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services --+HP7ph2BbKc20aGI Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="glossary-3.patch" diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index 612ce6e5f4..05fca33d9b 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -6,25 +6,34 @@ systems in general. - - Aggregate + + Aggregating - To combine a collection of data values into a single value, whose - value may not be of the same type as the original values. - Aggregate Functions - combine multiple Rows that share a common set - of values into one Row, which means that the - only data visible in the values in common, and the aggregates of the - non-common data. + The act of combining a collection of data (input) values into + a single output value, which may not be of the same type as the + input values. + + + + + + Aggregate Function + + A Function that combines multiple input values, + for example by counting, averaging or adding them all together, + yielding a single output value. For more information, see . + + See also Window Function. + Archiver - A process that backs up WAL Files in order to - reclaim space on the file system. + A process that saves aside copies of WAL Files, + for the purposes of creating backup copies or keeping + Replicas current. For more information, see @@ -59,16 +70,15 @@ In reference to the value of an Attribute or - Datum: cannot be broken down into smaller - components. + Datum: the property that it cannot be broken down + into smaller components. In reference to an operation: An event that cannot be completed in part: it must either entirely succeed or entirely fail. A series of SQL statements can be combined into a Transaction, and that - transaction is said to be - Atomic. + transaction is said to be atomic. @@ -112,6 +122,7 @@ + Background Worker @@ -142,8 +154,9 @@ Background Writer - Writes continuously dirty pages from Shared - Memory to the file system. It starts periodically, but + A process that continuously writes dirty pages from + Shared Memory to the file system. + It starts periodically, but works only for a short period in order to distribute expensive I/O activity over time instead of generating fewer large I/O peaks which could block other processes. @@ -218,10 +231,9 @@ Checkpoint - A Checkpoint is a point in time - when all older dirty pages of the Shared - Memory, all older WAL records, and - a special Checkpoint record have been written + A point in time when all older dirty pages of the + Shared Memory, all older WAL records, + and a special Checkpoint record have been written and flushed to disk. @@ -543,8 +555,8 @@ A Relation that contains data derived from a - Table (or Relation such - as a Materialized View). It's internal + Table (or other kind of Relation + such as a Materialized View). Its internal structure supports very fast retrieval of and access to the original data. @@ -815,7 +827,7 @@ Record - See Tupple. + See Tuple. A single Row of a Table @@ -944,7 +956,7 @@ Row - See Tupple. + See Tuple. @@ -1194,9 +1206,9 @@ Session or a Transaction, as defined at creation time. The data in them is not visible to other Sessions, - and is not Logged. Temporary - Tables are most often used to store intermediate data for - a multi-step data transformation. + and is not Logged. + Temporary Tables are often used to store + intermediate data for a multi-step data transformation. For more information, see @@ -1227,8 +1239,9 @@ A Function which can be defined to execute whenever a certain operation (INSERT, - UPDATE, or DELTE) is applied to - that Relation. A Trigger + UPDATE, DELETE, + TRUNCATE) is applied to a Relation. + A Trigger executes within the same Transaction as the statement which invoked it, and if the Function fails then the invoking statement also fails. @@ -1249,8 +1262,8 @@ the Tuple is found, in which case the Tuple is often called a Row or Record. It may - also be defined by the structure of a Result - Set. + also be defined by the structure of a + Result Set. @@ -1260,7 +1273,7 @@ The condition of having no matching values in the same - Relation. Most often used in the concept of + Relation. Often used in the concept of Unique Indexes. --+HP7ph2BbKc20aGI--