pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedSGML on functions
10+ messages / 4 participants
[nested] [flat]
* SGML on functions
@ 2010-08-27 18:56 Thom Brown <thom@linux.com>
0 siblings, 3 replies; 10+ messages in thread
From: Thom Brown @ 2010-08-27 18:56 UTC (permalink / raw)
To: pgsql-docs
Copied from another thread...
Something I've noticed is an inconsistency in the SGML markup around
functions listed in tables. Sometimes the entire function signature
is considered to be the function, and other times it's just the
function name, with its parameters outside of the <function> tags.
E.g.:
<function>variance</function>(<replaceable
class="parameter">expression</replaceable>)
vs
<function>stddev_samp(<replaceable
class="parameter">expression</replaceable>)</function>
Which way is correct?
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-27 20:57 Thom Brown <thom@linux.com>
parent: Thom Brown <thom@linux.com>
2 siblings, 1 reply; 10+ messages in thread
From: Thom Brown @ 2010-08-27 20:57 UTC (permalink / raw)
To: pgsql-docs
On 27 August 2010 19:56, Thom Brown <thom@linux.com> wrote:
> Copied from another thread...
>
> Something I've noticed is an inconsistency in the SGML markup around
> functions listed in tables. Sometimes the entire function signature
> is considered to be the function, and other times it's just the
> function name, with its parameters outside of the <function> tags.
>
> E.g.:
>
> <function>variance</function>(<replaceable
> class="parameter">expression</replaceable>)
>
> vs
>
> <function>stddev_samp(<replaceable
> class="parameter">expression</replaceable>)</function>
>
> Which way is correct?
>
I've also noticed that a lot of the <screen> contents are indented as
part of the markup, but when output in HTML, each space it recreated
as it ends up in either <code> or <pre> tags.
<programlisting> contents seem to have been intentionally entered so
that they break with the indenting style so they're output correctly.
Shouldn't tags such as <screen> follow the same style so that they can
also avoid unintentional leading whitespace?
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-27 22:31 Alvaro Herrera <alvherre@commandprompt.com>
parent: Thom Brown <thom@linux.com>
2 siblings, 1 reply; 10+ messages in thread
From: Alvaro Herrera @ 2010-08-27 22:31 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs
Excerpts from Thom Brown's message of vie ago 27 14:56:04 -0400 2010:
> Copied from another thread...
>
> Something I've noticed is an inconsistency in the SGML markup around
> functions listed in tables. Sometimes the entire function signature
> is considered to be the function, and other times it's just the
> function name, with its parameters outside of the <function> tags.
>
> E.g.:
>
> <function>variance</function>(<replaceable
> class="parameter">expression</replaceable>)
>
> vs
>
> <function>stddev_samp(<replaceable
> class="parameter">expression</replaceable>)</function>
>
> Which way is correct?
The latter I think -- see
http://www.docbook.org/tdg/en/html/function.html
(but perhaps search the actual standard)
--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 15:21 Kevin Grittner <Kevin.Grittner@wicourts.gov>
parent: Alvaro Herrera <alvherre@commandprompt.com>
0 siblings, 1 reply; 10+ messages in thread
From: Kevin Grittner @ 2010-08-29 15:21 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@commandprompt.com>; Thom Brown <thom@linux.com>; +Cc: pgsql-docs
Alvaro Herrera <alvherre@commandprompt.com> wrote:
> Excerpts from Thom Brown's message:
>> <function>variance</function>(<replaceable
>> class="parameter">expression</replaceable>)
>>
>> vs
>>
>> <function>stddev_samp(<replaceable
>> class="parameter">expression</replaceable>)</function>
>>
>> Which way is correct?
>
> The latter I think -- see
> http://www.docbook.org/tdg/en/html/function.html
> (but perhaps search the actual standard)
Nothing I saw at that link suggests that the parameters should be
included within the <function> scope. If you follow links from
there to here:
http://www.docbook.org/tdg/en/html/funcsynopsis.html
You find examples like this:
<funcsynopsis>
<funcprototype>
<funcdef>void <function>qsort</function></funcdef>
<paramdef>void *<parameter>dataptr</parameter>[]</paramdef>
<paramdef>int <parameter>left</parameter></paramdef>
<paramdef>int <parameter>right</parameter></paramdef>
<paramdef>int <parameter>(* comp)</parameter>
<funcparams>void *, void *</funcparams></paramdef>
</funcprototype>
</funcsynopsis>
-Kevin
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 15:54 Thom Brown <thom@linux.com>
parent: Kevin Grittner <Kevin.Grittner@wicourts.gov>
0 siblings, 1 reply; 10+ messages in thread
From: Thom Brown @ 2010-08-29 15:54 UTC (permalink / raw)
To: Kevin Grittner <Kevin.Grittner@wicourts.gov>; +Cc: Alvaro Herrera <alvherre@commandprompt.com>; pgsql-docs
On 29 August 2010 16:21, Kevin Grittner <Kevin.Grittner@wicourts.gov> wrote:
> Alvaro Herrera <alvherre@commandprompt.com> wrote:
>> Excerpts from Thom Brown's message:
>
>>> <function>variance</function>(<replaceable
>>> class="parameter">expression</replaceable>)
>>>
>>> vs
>>>
>>> <function>stddev_samp(<replaceable
>>> class="parameter">expression</replaceable>)</function>
>>>
>>> Which way is correct?
>>
>> The latter I think -- see
>> http://www.docbook.org/tdg/en/html/function.html
>> (but perhaps search the actual standard)
>
> Nothing I saw at that link suggests that the parameters should be
> included within the <function> scope. If you follow links from
> there to here:
>
> http://www.docbook.org/tdg/en/html/funcsynopsis.html
>
> You find examples like this:
>
> <funcsynopsis>
> <funcprototype>
> <funcdef>void <function>qsort</function></funcdef>
> <paramdef>void *<parameter>dataptr</parameter>[]</paramdef>
> <paramdef>int <parameter>left</parameter></paramdef>
> <paramdef>int <parameter>right</parameter></paramdef>
> <paramdef>int <parameter>(* comp)</parameter>
> <funcparams>void *, void *</funcparams></paramdef>
> </funcprototype>
> </funcsynopsis>
>
But that page also says "Using FuncSynopsis for languages that are
unrelated to C may prove difficult."
Using that syntax will result in a semi-colon being placed at the end
of the function when parsed.
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 16:24 Kevin Grittner <Kevin.Grittner@wicourts.gov>
parent: Thom Brown <thom@linux.com>
0 siblings, 0 replies; 10+ messages in thread
From: Kevin Grittner @ 2010-08-29 16:24 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: Alvaro Herrera <alvherre@commandprompt.com>; pgsql-docs
Thom Brown <thom@linux.com> wrote:
> Kevin Grittner <Kevin.Grittner@wicourts.gov> wrote:
>> You find examples like this:
>>
>> <funcsynopsis>
>> <funcprototype>
>> <funcdef>void <function>qsort</function></funcdef>
>> <paramdef>void *<parameter>dataptr</parameter>[]</paramdef>
>> <paramdef>int <parameter>left</parameter></paramdef>
>> <paramdef>int <parameter>right</parameter></paramdef>
>> <paramdef>int <parameter>(* comp)</parameter>
>> <funcparams>void *, void *</funcparams></paramdef>
>> </funcprototype>
>> </funcsynopsis>
>>
>
> But that page also says "Using FuncSynopsis for languages that are
> unrelated to C may prove difficult."
>
> Using that syntax will result in a semi-colon being placed at the
> end of the function when parsed.
Yes, but that's the only place I could find an example of function
and parameter together. The parameter tag can be used inside of
function as well as in most of the places function can be used, so
the definition seemed ambiguous to me. I took these examples as
being the best evidence I could find about whether parameter tags
were intended to be inside or outside of the function tag.
I suppose an argument could be made that for functions for which the
identity is totally determined by function name (as in C) the
parameters should be outside the tag, while functions in SQL need
the parameters inside the tag, because they are used to identify a
particular function among many with the same name.
It appears that, technically, either format is allowed.
-Kevin
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 19:12 Peter Eisentraut <peter_e@gmx.net>
parent: Thom Brown <thom@linux.com>
0 siblings, 1 reply; 10+ messages in thread
From: Peter Eisentraut @ 2010-08-29 19:12 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs
On fre, 2010-08-27 at 21:57 +0100, Thom Brown wrote:
> I've also noticed that a lot of the <screen> contents are indented as
> part of the markup, but when output in HTML, each space it recreated
> as it ends up in either <code> or <pre> tags.
>
> <programlisting> contents seem to have been intentionally entered so
> that they break with the indenting style so they're output correctly.
> Shouldn't tags such as <screen> follow the same style so that they can
> also avoid unintentional leading whitespace?
I don't really know what you mean here. Do you have an example?
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 19:12 Peter Eisentraut <peter_e@gmx.net>
parent: Thom Brown <thom@linux.com>
2 siblings, 0 replies; 10+ messages in thread
From: Peter Eisentraut @ 2010-08-29 19:12 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs
On fre, 2010-08-27 at 19:56 +0100, Thom Brown wrote:
> E.g.:
>
> <function>variance</function>(<replaceable
> class="parameter">expression</replaceable>)
>
> vs
>
> <function>stddev_samp(<replaceable
> class="parameter">expression</replaceable>)</function>
>
> Which way is correct?
"Correct" is a strong word in such matters, but I prefer the latter
version.
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 19:24 Thom Brown <thom@linux.com>
parent: Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 10+ messages in thread
From: Thom Brown @ 2010-08-29 19:24 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
On 29 August 2010 20:12, Peter Eisentraut <peter_e@gmx.net> wrote:
> On fre, 2010-08-27 at 21:57 +0100, Thom Brown wrote:
>> I've also noticed that a lot of the <screen> contents are indented as
>> part of the markup, but when output in HTML, each space it recreated
>> as it ends up in either <code> or <pre> tags.
>>
>> <programlisting> contents seem to have been intentionally entered so
>> that they break with the indenting style so they're output correctly.
>> Shouldn't tags such as <screen> follow the same style so that they can
>> also avoid unintentional leading whitespace?
>
> I don't really know what you mean here. Do you have an example?
Yes, although it appears to have been resolved in 9.0's documentation:
http://www.postgresql.org/docs/8.4/static/libpq-connect.html
Compare to..
http://www.postgresql.org/docs/9.0/static/libpq-connect.html
The part in question is the line after which it says "Makes a new
connection to the database server".
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: SGML on functions
@ 2010-08-29 20:05 Thom Brown <thom@linux.com>
parent: Thom Brown <thom@linux.com>
0 siblings, 0 replies; 10+ messages in thread
From: Thom Brown @ 2010-08-29 20:05 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
On 29 August 2010 20:24, Thom Brown <thom@linux.com> wrote:
> On 29 August 2010 20:12, Peter Eisentraut <peter_e@gmx.net> wrote:
>> On fre, 2010-08-27 at 21:57 +0100, Thom Brown wrote:
>>> I've also noticed that a lot of the <screen> contents are indented as
>>> part of the markup, but when output in HTML, each space it recreated
>>> as it ends up in either <code> or <pre> tags.
>>>
>>> <programlisting> contents seem to have been intentionally entered so
>>> that they break with the indenting style so they're output correctly.
>>> Shouldn't tags such as <screen> follow the same style so that they can
>>> also avoid unintentional leading whitespace?
>>
>> I don't really know what you mean here. Do you have an example?
>
> Yes, although it appears to have been resolved in 9.0's documentation:
>
> http://www.postgresql.org/docs/8.4/static/libpq-connect.html
>
> Compare to..
>
> http://www.postgresql.org/docs/9.0/static/libpq-connect.html
>
> The part in question is the line after which it says "Makes a new
> connection to the database server".
Ah, it appears it was actually *you* who fixed it!
"Fix indentation of verbatim block elements
Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output. The CSS stylesheets already take care of indenting
the output.
Assorted markup improvements to go along with it."
http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/libpq.sgml.diff?r1=1.313.2.2;r2=1.313.2....
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
^ permalink raw reply [nested|flat] 10+ messages in thread
end of thread, other threads:[~2010-08-29 20:05 UTC | newest]
Thread overview: 10+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2010-08-27 18:56 SGML on functions Thom Brown <thom@linux.com>
2010-08-27 20:57 ` Thom Brown <thom@linux.com>
2010-08-29 19:12 ` Peter Eisentraut <peter_e@gmx.net>
2010-08-29 19:24 ` Thom Brown <thom@linux.com>
2010-08-29 20:05 ` Thom Brown <thom@linux.com>
2010-08-27 22:31 ` Alvaro Herrera <alvherre@commandprompt.com>
2010-08-29 15:21 ` Kevin Grittner <Kevin.Grittner@wicourts.gov>
2010-08-29 15:54 ` Thom Brown <thom@linux.com>
2010-08-29 16:24 ` Kevin Grittner <Kevin.Grittner@wicourts.gov>
2010-08-29 19:12 ` Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox