pgsql: remove tags.

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

---------------------------------------------------------------------------

Branch
------
master

Details
-------
http://git.postgresql.org/gitweb?p=postgresql.git;a=commitdiff;h=ad762426333aac5bd8e1ceac753bebe4a6411c28

Modified Files
--------------
doc/src/sgml/advanced.sgml | 2 +-
doc/src/sgml/array.sgml | 2 +-
doc/src/sgml/backup.sgml | 4 ++--
doc/src/sgml/catalogs.sgml | 5 ++---
doc/src/sgml/client-auth.sgml | 8 ++++----
doc/src/sgml/config.sgml | 7 +++----
doc/src/sgml/func.sgml | 4 ++--
doc/src/sgml/high-availability.sgml | 2 +-
doc/src/sgml/libpq.sgml | 2 +-
doc/src/sgml/runtime.sgml | 4 ++--
doc/src/sgml/spi.sgml | 2 +-
doc/src/sgml/tsearch2.sgml | 2 +-
12 files changed, 21 insertions(+), 23 deletions(-)

--
Sent via pgsql-committers mailing list (pgsql-committers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-committers

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

How about git revert, instead? It's not apparent to me that these
changes were improvements.

regards, tom lane

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead?  It's not apparent to me that these
changes were improvements.

I'll buy that one.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead? ?It's not apparent to me that these
changes were improvements.

I'll buy that one.

[ CC to docs, committers removed. ]

Well, if we want to revert, then we have to add <literal> to all the
numbers used in our docs --- there was no logic in what we previously
had. Do we want that?

Here is an example line I did not change:

an otherwise idle connection. A value of 0 uses the system default.

Do we want that 0 to appear in a fixed-width font via <literal>?
It is easy to do but we should decide.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Mon, Feb 7, 2011 at 9:54 AM, Bruce Momjian <bruce@momjian.us> wrote:

Robert Haas wrote:

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead? ?It's not apparent to me that these
changes were improvements.

I'll buy that one.

[  CC to docs, committers removed. ]

Well, if we want to revert, then we have to add <literal> to all the
numbers used in our docs --- there was no logic in what we previously
had.  Do we want that?

Here is an example line I did not change:

  an otherwise idle connection.  A value of 0 uses the system default.

Do we want that 0 to appear in a fixed-width font via <literal>?
It is easy to do but we should decide.

[ removing -hackers from CC also, no need to cross-post ]

Hmm. I'm starting to lean toward leaving this as you have it.

Which way did we more commonly do it before you applied this patch?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one. It's hopeless to imagine
that you'll ever achieve any uniformity that way. It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this. I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

regards, tom lane

Robert Haas wrote:

On Mon, Feb 7, 2011 at 9:54 AM, Bruce Momjian <bruce@momjian.us> wrote:

Robert Haas wrote:

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead? ?It's not apparent to me that these
changes were improvements.

I'll buy that one.

[ ?CC to docs, committers removed. ]

Well, if we want to revert, then we have to add <literal> to all the
numbers used in our docs --- there was no logic in what we previously
had. ?Do we want that?

Here is an example line I did not change:

? an otherwise idle connection. ?A value of 0 uses the system default.

Do we want that 0 to appear in a fixed-width font via <literal>?
It is easy to do but we should decide.

[ removing -hackers from CC also, no need to cross-post ]

Hmm. I'm starting to lean toward leaving this as you have it.

Which way did we more commonly do it before you applied this patch?

It was mostly like the line I have above, meaning it was not in
fixed-width font, 95% I would say. I modified 19 to be like the rest.
I left <literal> where the context made sense.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one.  It's hopeless to imagine
that you'll ever achieve any uniformity that way.  It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this.  I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

*reads patch more carefully*

Here are my verdicts:

advanced.sgml: good
array.sgml: good
backup.sgml: unsure
catalogs.sgml: bad
client-auth.sgml: bad
config.sgml: bad
func.sgml: bad
high-availability.sgml: bad
libpq.sgml: bad
runtime.sgml: bad
spi.sgml: unsure
tsearch2.sgml: good

So I guess I'm back agreeing with you. Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged). It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet"). The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Tom Lane wrote:

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one. It's hopeless to imagine
that you'll ever achieve any uniformity that way. It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

Well, the problem is that we then have paragraphs where a number is
fixed width, and in the next paragraph it isn't; this is particuarly
true in the config.sgml file where we show defaults. Seems worth trying
to make that consistent. I am happy to do whatever we agree on --- I
don't have an opinion.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this. I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

Yes, I reviewed all the places and left <literal> where it made sense.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Robert Haas wrote:

On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one. ?It's hopeless to imagine
that you'll ever achieve any uniformity that way. ?It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this. ?I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

*reads patch more carefully*

Here are my verdicts:

advanced.sgml: good
array.sgml: good
backup.sgml: unsure
catalogs.sgml: bad
client-auth.sgml: bad
config.sgml: bad
func.sgml: bad
high-availability.sgml: bad
libpq.sgml: bad
runtime.sgml: bad
spi.sgml: unsure
tsearch2.sgml: good

So I guess I'm back agreeing with you. Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged). It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet"). The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

OK, let's decide what we want and I will make it happen.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

it appears that PDF files need no reformatting, and that it is ok to allow long command lines to be truncated by the right margins, or even better, that pronouns that refer back to a noun, are not specific enough.  One has to stop and think, --- to which noun is "this" (a pronoun) referring to.

I am not challenging the technical content, which I have found to be precise, but only that someone should proof read text to ensure good grammar.

No real improvement between pdf version 9.02 and 9.03, after I reported some issues with the former.

------------------

Regards
 Leslie
Mr. Leslie Satenstein
40 years in IT and going strong.
Yesterday was a good day, today is a better day,
and tomorrow will be even better.
 
mailto:lsatenstein@yahoo.com
alternative: leslie.satenstein@itbms.biz
www.itbms.biz / www.eclipseguard.com

--- On Mon, 2/7/11, Bruce Momjian <bruce@momjian.us> wrote:

From: Bruce Momjian <bruce@momjian.us>
Subject: Re: [DOCS] [COMMITTERS] pgsql: remove tags.
To: "Robert Haas" <robertmhaas@gmail.com>
Cc: "Tom Lane" <tgl@sss.pgh.pa.us>, "PostgreSQL-documentation" <pgsql-docs@postgresql.org>
Date: Monday, February 7, 2011, 10:54 AM

Robert Haas wrote:

On Mon, Feb 7, 2011 at 9:54 AM, Bruce Momjian <bruce@momjian.us> wrote:

Robert Haas wrote:

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead? ?It's not apparent to me that these
changes were improvements.

I'll buy that one.

[ ?CC to docs, committers removed. ]

Well, if we want to revert, then we have to add <literal> to all the
numbers used in our docs --- there was no logic in what we previously
had. ?Do we want that?

Here is an example line I did not change:

? an otherwise idle connection. ?A value of 0 uses the system default.

Do we want that 0 to appear in a fixed-width font via <literal>?
It is easy to do but we should decide.

[ removing -hackers from CC also, no need to cross-post ]

Hmm.  I'm starting to lean toward leaving this as you have it.

Which way did we more commonly do it before you applied this patch?

It was mostly like the line I have above, meaning it was not in
fixed-width font, 95% I would say.  I modified 19 to be like the rest.
I left <literal> where the context made sense.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Robert Haas wrote:

On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one. ?It's hopeless to imagine
that you'll ever achieve any uniformity that way. ?It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this. ?I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

*reads patch more carefully*

Here are my verdicts:

advanced.sgml: good
array.sgml: good
backup.sgml: unsure
catalogs.sgml: bad
client-auth.sgml: bad
config.sgml: bad
func.sgml: bad
high-availability.sgml: bad
libpq.sgml: bad
runtime.sgml: bad
spi.sgml: unsure
tsearch2.sgml: good

So I guess I'm back agreeing with you. Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged). It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet"). The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

Robert, based on your logic, the 'return -1' should not be literal
because no one would type that in. Unless I hear otherwise I will work
on a patch to match the rules you outlined above.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

I already told you that your changes will only appear in 9.1 --- we don't
usually backpatch wording changes. You can see the development docs here:

http://developer.postgresql.org/pgdocs/postgres/index.html

---------------------------------------------------------------------------

Leslie S Satenstein wrote:

it appears that PDF files need no reformatting, and that it is ok to
allow long command lines to be truncated by the right margins, or even
better, that pronouns that refer back to a noun, are not specific
enough.? One has to stop and think, --- to which noun is "this" (a
pronoun) referring to.

I am not challenging the technical content, which I have found to be
precise, but only that someone should proof read text to ensure good
grammar.

No real improvement between pdf version 9.02 and 9.03, after I reported
some issues with the former.

------------------

Regards ?Leslie
Mr. Leslie Satenstein 40 years in IT and going strong. Yesterday was
a good day, today is a better day, and tomorrow will be even better.
? mailto:lsatenstein@yahoo.com alternative: leslie.satenstein@itbms.biz
www.itbms.biz / www.eclipseguard.com

--- On Mon, 2/7/11, Bruce Momjian <bruce@momjian.us> wrote:

From: Bruce Momjian <bruce@momjian.us> Subject: Re: [DOCS] [COMMITTERS]
pgsql: remove tags. To: "Robert Haas" <robertmhaas@gmail.com> Cc: "Tom
Lane" <tgl@sss.pgh.pa.us>, "PostgreSQL-documentation"
<pgsql-docs@postgresql.org> Date: Monday, February 7, 2011, 10:54 AM

Robert Haas wrote:

On Mon, Feb 7, 2011 at 9:54 AM, Bruce Momjian <bruce@momjian.us> wrote:

Robert Haas wrote:

On Sun, Feb 6, 2011 at 11:12 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Bruce Momjian <bruce@momjian.us> writes:

Bruce Momjian wrote:

remove tags.

Sorry, vague commit message (I forgot squash).

Can I will use git ammend to improve this message?

Absolutely not.

How about git revert, instead? ?It's not apparent to me that these
changes were improvements.

I'll buy that one.

[ ?CC to docs, committers removed. ]

Well, if we want to revert, then we have to add <literal> to all the
numbers used in our docs --- there was no logic in what we previously
had. ?Do we want that?

Here is an example line I did not change:

? an otherwise idle connection. ?A value of 0 uses the system default.

Do we want that 0 to appear in a fixed-width font via <literal>?
It is easy to do but we should decide.

[ removing -hackers from CC also, no need to cross-post ]

Hmm.? I'm starting to lean toward leaving this as you have it.

Which way did we more commonly do it before you applied this patch?

It was mostly like the line I have above, meaning it was not in
fixed-width font, 95% I would say.? I modified 19 to be like the rest.
I left <literal> where the context made sense.

-- ? Bruce Momjian? <bruce@momjian.us>? ? ? ? http://momjian.us ?
EnterpriseDB? ? ? ? ? ? ? ? ? ? ? ? ? ???http://enterprisedb.com

? + It's impossible for everything to be true. +

-- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make
changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Did we want to do any more on the issue of using <literal> for numbers
in our docs? The February thread is here:

http://archives.postgresql.org/pgsql-docs/2011-02/msg00028.php

While the applied patch removed the 'literal' tag from some numbers, we
were not consistenly using 'literal' for constants in our docs.

I can make the change if we decide what we consistently want, or maybe it
is fine as-is.

---------------------------------------------------------------------------

Robert Haas wrote:

On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

Which way did we more commonly do it before you applied this patch?

We don't have a standard for this, and an undocumented patch applied
without any discussion doesn't create one. ?It's hopeless to imagine
that you'll ever achieve any uniformity that way. ?It won't last long
if you do, since you're outnumbered by committers who won't be following
whatever you think the convention is.

I'm not even sure why you're trying --- I don't think it even makes
sense to try to have a standard about this. ?I can easily imagine that
integer constants might read better with <literal> in some contexts
and better without in others.

*reads patch more carefully*

Here are my verdicts:

advanced.sgml: good
array.sgml: good
backup.sgml: unsure
catalogs.sgml: bad
client-auth.sgml: bad
config.sgml: bad
func.sgml: bad
high-availability.sgml: bad
libpq.sgml: bad
runtime.sgml: bad
spi.sgml: unsure
tsearch2.sgml: good

So I guess I'm back agreeing with you. Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged). It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet"). The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian wrote:

So I guess I'm back agreeing with you. Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged). It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet"). The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

Robert, based on your logic, the 'return -1' should not be literal
because no one would type that in. Unless I hear otherwise I will work
on a patch to match the rules you outlined above.

FYI, here is what I thought was Robert's conclusion on this.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Mon, Sep 5, 2011 at 10:51 AM, Bruce Momjian <bruce@momjian.us> wrote:

Did we want to do any more on the issue of using <literal> for numbers
in our docs?  The February thread is here:

       http://archives.postgresql.org/pgsql-docs/2011-02/msg00028.php

While the applied patch removed the 'literal' tag from some numbers, we
were not consistenly using 'literal' for constants in our docs.

I can make the change if we decide what we consistently want, or maybe it
is fine as-is.

I think it's fine as-is.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company