From: | Alvaro Herrera <alvherre(at)2ndquadrant(dot)com> |
---|---|
To: | Corey Huinker <corey(dot)huinker(at)gmail(dot)com> |
Cc: | Jürgen Purtz <juergen(at)purtz(dot)de>, Roger Harkavy <rogerharkavy(at)gmail(dot)com>, pgsql-hackers(at)postgresql(dot)org, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>, Michael Paquier <michael(at)paquier(dot)xyz> |
Subject: | Re: Add A Glossary |
Date: | 2020-03-20 17:51:44 |
Message-ID: | 20200320175144.GA20645@alvherre.pgsql |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs pgsql-hackers |
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 <glossterm> 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
Attachment | Content-Type | Size |
---|---|---|
glossary-3.patch | text/x-diff | 7.7 KB |
From | Date | Subject | |
---|---|---|---|
Next Message | Roger Harkavy | 2020-03-20 18:08:14 | Re: Add A Glossary |
Previous Message | Corey Huinker | 2020-03-20 15:48:24 | Re: Add A Glossary |
From | Date | Subject | |
---|---|---|---|
Next Message | Roger Harkavy | 2020-03-20 18:08:14 | Re: Add A Glossary |
Previous Message | Tom Lane | 2020-03-20 16:42:42 | Re: Correlated IN/Any Subquery Transformation |