Subject: XML documentation question

From: Bruce Momjian <[email-masked]>
Date: Thu, 23 Apr 2009 23:17:47 -0400 (EDT)

What does this first sentence mean in our XML function documentation; 
would someone please rewrite it to be intelligable?

    In addition, the following functions are available to produce
    analogous mappings of entire schemas or the entire current
    database.
<synopsis>
schema_to_xml(schema name, nulls boolean, tableforest boolean, targetns text)
schema_to_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)
schema_to_xml_and_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)

database_to_xml(nulls boolean, tableforest boolean, targetns text)
database_to_xmlschema(nulls boolean, tableforest boolean, targetns text)
database_to_xml_and_xmlschema(nulls boolean, tableforest boolean, targetns text)
</synopsis>

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 24 Apr 2009 14:15:12 +0300

>     analogous mappings of entire schemas or the entire current

It means that the functions described below produce mappings that are 
analogous to the ones described earlier in that section which map tables 
instead of schemas or databases.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 24 Apr 2009 08:48:52 -0400 (EDT)

> instead of schemas or databases.

Apologies, I quoted the wrong section;  I meant to ask about this
sentence:

	    The following functions return XML Schema documents describing the
	    mappings made by the data mappings produced by the corresponding
	    functions above.
	<synopsis>
	table_to_xmlschema(tbl regclass, nulls boolean, tableforest boolean,
	targetns text)
	query_to_xmlschema(query text, nulls boolean, tableforest boolean,
	targetns text)
	cursor_to_xmlschema(cursor refcursor, nulls boolean, tableforest
	boolean, targetns text)
	</synopsis>

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 26 Apr 2009 14:34:50 +0300

> 	    mappings made by the data mappings produced by the corresponding

I don't know what is unclear about this.

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 26 Apr 2009 09:14:06 -0400 (EDT)

> I don't know what is unclear about this.

The "mappings made by" and "mappings produced by" seem redundant, and
hence confusing.

---

From: Tom Lane <[email-masked]>
Date: Sun, 26 Apr 2009 11:27:27 -0400

> The "mappings made by" and "mappings produced by" seem redundant, and

Couldn't the sentence be trimmed to just

	The following functions return XML Schema documents describing the
	mappings produced by the corresponding functions above.

If that phrasing is wrong for some reason, then I agree with Bruce that
the sentence needs a complete rewrite.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 27 Apr 2009 13:20:29 -0400 (EDT)

> the sentence needs a complete rewrite.

I updated the text to:

    The following functions return XML Schema documents similar to the
    mappings produced by the corresponding functions above:

---

From: Tom Lane <[email-masked]>
Date: Mon, 27 Apr 2009 13:55:35 -0400

>     mappings produced by the corresponding functions above:

Hmm, I'm not sure that means the same thing at all.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 27 Apr 2009 14:23:23 -0400 (EDT)

> Hmm, I'm not sure that means the same thing at all.

Well, short of getting new text from Peter, that's the best I can do.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 27 Apr 2009 21:46:54 +0300

> 	mappings produced by the corresponding functions above.

Sounds good.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 27 Apr 2009 21:48:08 +0300

>     mappings produced by the corresponding functions above:

Sorry, that is completely wrong.

Are you aware of what "XML Schema" is?  Should that perhaps be explained in 
the docs?

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 27 Apr 2009 14:52:48 -0400 (EDT)

> >     mappings produced by the corresponding functions above:

OK, that is what is in our SGML now.

> Sorry, that is completely wrong.

You did just email "sounds good", but were mistaken, right?

> Are you aware of what "XML Schema" is?  Should that perhaps be explained in

Uh, it would be nice to explain it, yes.  My guess it that the paragraph
is much too short and needs perhaps an addtional sentence, but I have no
clue what it should be.

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 27 Apr 2009 16:00:11 -0400

> You did just email "sounds good", but were mistaken, right?

But that was to Tom proposal, which is completely different (yes -- one
word can change the meaning of a sentence).

I agree the paragraph (even with Tom's rework) is a bit confusing to the
uninitiated.  Maybe the subsection could be reflowed so that each
function is described along the corresponding XML Schema function (to
table_to_xml and table_to_xmlschema, later query_to_xml and
query_to_xmlschema and so on).

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support