Обсуждение: XML documentation question
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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
On Friday 24 April 2009 06:17:47 Bruce Momjian wrote: > 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. 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.
Peter Eisentraut wrote:
> On Friday 24 April 2009 06:17:47 Bruce Momjian wrote:
> > 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.
>
> 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.
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>
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
On Friday 24 April 2009 15:48:52 Bruce Momjian wrote: > 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. I don't know what is unclear about this.
Peter Eisentraut wrote: > On Friday 24 April 2009 15:48:52 Bruce Momjian wrote: > > 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. > > I don't know what is unclear about this. The "mappings made by" and "mappings produced by" seem redundant, and hence confusing. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
> Peter Eisentraut wrote:
>> On Friday 24 April 2009 15:48:52 Bruce Momjian wrote:
>>> 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.
>>
>> I don't know what is unclear about this.
> The "mappings made by" and "mappings produced by" seem redundant, and
> hence confusing.
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
Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Peter Eisentraut wrote:
> >> On Friday 24 April 2009 15:48:52 Bruce Momjian wrote:
> >>> 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.
> >>
> >> I don't know what is unclear about this.
>
> > The "mappings made by" and "mappings produced by" seem redundant, and
> > hence confusing.
>
> 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.
I updated the text to:
The following functions return XML Schema documents similar to the
mappings produced by the corresponding functions above:
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> Couldn't the sentence be trimmed to just
>>
>> The following functions return XML Schema documents describing the
>> mappings produced by the corresponding functions above.
> I updated the text to:
> The following functions return XML Schema documents similar to the
> mappings produced by the corresponding functions above:
Hmm, I'm not sure that means the same thing at all.
regards, tom lane
Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > Tom Lane wrote: > >> Couldn't the sentence be trimmed to just > >> > >> The following functions return XML Schema documents describing the > >> mappings produced by the corresponding functions above. > > > I updated the text to: > > > The following functions return XML Schema documents similar to the > > mappings produced by the corresponding functions above: > > 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Sunday 26 April 2009 18:27:27 Tom Lane wrote: > Couldn't the sentence be trimmed to just > > The following functions return XML Schema documents describing the > mappings produced by the corresponding functions above. Sounds good.
On Monday 27 April 2009 20:20:29 Bruce Momjian wrote: > I updated the text to: > > The following functions return XML Schema documents similar to the > 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?
Peter Eisentraut wrote: > On Monday 27 April 2009 20:20:29 Bruce Momjian wrote: > > I updated the text to: > > > > The following functions return XML Schema documents similar to the > > 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 > the docs? 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > Peter Eisentraut wrote: > > On Monday 27 April 2009 20:20:29 Bruce Momjian wrote: > > > I updated the text to: > > > > > > The following functions return XML Schema documents similar to the > > > 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? 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