Обсуждение: BUG #14258: Documentation pl/pgsql
VGhlIGZvbGxvd2luZyBidWcgaGFzIGJlZW4gbG9nZ2VkIG9uIHRoZSB3ZWJz aXRlOgoKQnVnIHJlZmVyZW5jZTogICAgICAxNDI1OApMb2dnZWQgYnk6ICAg ICAgICAgIERpbGlhbiBQYWxhdXpvdgpFbWFpbCBhZGRyZXNzOiAgICAgIGRw YS1wb3N0Z3Jlc0BhZWdlZS5vcmcKUG9zdGdyZVNRTCB2ZXJzaW9uOiA5LjUu MwpPcGVyYXRpbmcgc3lzdGVtOiAgIGFueQpEZXNjcmlwdGlvbjogICAgICAg IAoKSGVsbG8sDQoNCmluIGRvYy9zcmMvc2dtbC9wbHBnc3FsLnNnbWwgcGxl YXNlIHJlcGxhY2U6DQoNCi0tLSBhL2RvYy9zcmMvc2dtbC9wbHBnc3FsLnNn bWwNCisrKyBiL2RvYy9zcmMvc2dtbC9wbHBnc3FsLnNnbWwNCkBAIC0zMjgs NyArMzI4LDcgQEAgYXJvdyBSRUNPUkQ7DQo8cGFyYT4NClRoZSBnZW5lcmFs IHN5bnRheCBvZiBhIHZhcmlhYmxlIGRlY2xhcmF0aW9uIGlzOg0KPHN5bm9w c2lzPg0KLTxyZXBsYWNlYWJsZT5uYW1lPC9yZXBsYWNlYWJsZT4gPG9wdGlv bmFsPiBDT05TVEFOVCA8L29wdGlvbmFsPgo8cmVwbGFjZWFibGU+dHlwZTwv cmVwbGFjZWFibGU+IDxvcHRpb25hbD4gQ09MTEFURQo8cmVwbGFjZWFibGU+ Y29sbGF0aW9uX25hbWU8L3JlcGxhY2VhYmxlPiA8L29wdGlvbmFsPiA8b3B0 aW9uYWw+IE5PVCBOVUxMCjwvb3B0aW9uYWw+IDxvcHRpb25hbD4geyBERUZB VUxUIHwgOj0gfCA9IH0KPHJlcGxhY2VhYmxlPmV4cHJlc3Npb248L3JlcGxh Y2VhYmxlPiA8L29wdGlvbmFsPjsNCis8cmVwbGFjZWFibGU+bmFtZTwvcmVw bGFjZWFibGU+IDxvcHRpb25hbD4gQ09OU1RBTlQgPC9vcHRpb25hbD4KPHJl cGxhY2VhYmxlPnR5cGU8L3JlcGxhY2VhYmxlPiA8b3B0aW9uYWw+IENPTExB VEUKPHJlcGxhY2VhYmxlPmNvbGxhdGlvbl9uYW1lPC9yZXBsYWNlYWJsZT4g PC9vcHRpb25hbD4gPG9wdGlvbmFsPiAgPG9wdGlvbmFsPgpOT1QgTlVMTCA8 L29wdGlvbmFsPnsgREVGQVVMVCB8IDo9IHwgPSB9CjxyZXBsYWNlYWJsZT5l eHByZXNzaW9uPC9yZXBsYWNlYWJsZT4gPC9vcHRpb25hbD47DQo8L3N5bm9w c2lzPg0KVGhlIDxsaXRlcmFsPkRFRkFVTFQ8Lz4gY2xhdXNlLCBpZiBnaXZl biwgc3BlY2lmaWVzIHRoZSBpbml0aWFsIHZhbHVlCmFzc2lnbmVkDQp0byB0 aGUgdmFyaWFibGUgd2hlbiB0aGUgYmxvY2sgaXMgZW50ZXJlZC4gIElmIHRo ZSA8bGl0ZXJhbD5ERUZBVUxUPC8+CmNsYXVzZQ0KDQoNCmJlY2F1c2UgTk9U IE5VTEwgY2FuIGJlIHVzZWQgb25seSB3aXRoIHtERUZBVUxUIHwgOj0gfCA9 fS4gIEtlZXAgaW4gbWluZAp0aGF0IHRoZSBtZW50aW9uZWQgbGluZSBpcyBz byBsb25nLCB0aGF0IGl0IGRvZXMgbm90IGZpdCBpbiB0aGUgUERGL0E0CmRv Y3VtZW50YXRpb24KKGh0dHBzOi8vd3d3LnBvc3RncmVzcWwub3JnL2ZpbGVz L2RvY3VtZW50YXRpb24vcGRmLzkuNS9wb3N0Z3Jlc3FsLTkuNS1BNC5wZGYs CnBhZ2UgMTA2My8xMTM4KS4NCg0KRm9yIEdFVCBbQ1VSUkVOVF0gRElBR05P U0lUQ1MgKHBscGdzcWwuc2dtbCwgbGluZSAxNDQxKSB0aGUgZG9jdW1lbnRh dGlvbgp3aXRoaW4gcGdwZ3NxbC5zZ21sIGlzIHVuY2xlYXIsIHdoYXQgaXMg Q1VSUkVOVCBzdXBwb3NlZCB0byBkby4NCg0KSW4gICAgPHNlY3QyIGlkPSJw bHBnc3FsLWNvbmRpdGlvbmFscyI+LCAxODM0IGlzIHdyaXR0ZW4NCg0KSUYg Li4uIFRIRU4NCg0KQ0FTRSAuLi4gV0hFTiAuLi4gRU5EIENBU0UNCg0KTW9y ZSBjb25zaXN0ZW50IHdvdWxkIGJlIHRvIHdyaXRlIElGIC4uLiBUSEVOIC4u LiBFTkQgSUYNCg0KSW4gVHJpZ2dlciBQcm9jZWR1cmVzLCBUcmlnZ2VycyBv biBEYXRhIENoYW5nZXMgaXMgc3RhdGVkLCB0aGF0IHRoZSByZXR1cm4KdmFs dWUgb2YgYSByb3ctbGV2ZWwgdHJpZ2dlciBpcyBpZ25vcmVkLiAgRG9lcyBz dWNoIGEgdHJpZ2dlciBoYXZlIHRvCmV4ZWN1dGUgZXhwbGljaXRseSBSRVRV Uk4sIGNvbnRyYXJ5IHRvIGZ1bmN0aW9ucyByZXR1cm5pbmcgdm9pZD8NCg0K SW4gdGhlIGV4YW1wbGUgYWZ0ZXJ3YXJkcyAiQSBQTC9wZ1NRTCBUcmlnZ2Vy IFByb2NlZHVyZSBGb3IgQXVkaXRpbmciLCBpbgpwcm9jZXNzX2VtcF9hdWRp dCgpIGFzIEFGVEVSIHRyaWdnZXIsIHRoZSBjb21tZW50IHN0YXRlcywgdGhh dCB0aGUgcmV0dXJuCnZhbHVlIGlzIGlnbm9yZWQsIGJ1dCB3aHkgZG9lcyB0 aGUgZnVuY3Rpb24gaGF2ZSBmb3VyIHJldHVybiBzdGF0ZW1lbnRzCmluc3Rl YWQgb2YganVzdCBvbmU/DQoNCkluIHN1YnNlY3Rpb24gIlRyaWdnZXJzIG9u IEV2ZW50cyIgcGxlYXNlIHJlcGxhY2UgImlzIGNhbGxlZCBhcyBhIGV2ZW50 CnRyaWdnZXIiIHdpdGggImlzIGNhbGxlZCBhcyBBTiBldmVudCB0cmlnZ2Vy Ii4KCg==
dpa-postgres@aegee.org writes:
> in doc/src/sgml/plpgsql.sgml please replace:
> ...
> because NOT NULL can be used only with {DEFAULT | := | =}.
I'm disinclined to do that; it's not required by the plpgsql grammar,
and in principle it might not be required at runtime either. In
particular, if the variable is of a domain type it would be sensible for
plpgsql to adopt the domain's default value if any.
> For GET [CURRENT] DIAGNOSITCS (plpgsql.sgml, line 1441) the documentation
> within pgpgsql.sgml is unclear, what is CURRENT supposed to do.
Hmm, it's just a noise word, but I agree the docs ought to say that.
> In <sect2 id="plpgsql-conditionals">, 1834 is written
> IF ... THEN
> CASE ... WHEN ... END CASE
> More consistent would be to write IF ... THEN ... END IF
Makes sense.
> In Trigger Procedures, Triggers on Data Changes is stated, that the return
> value of a row-level trigger is ignored. Does such a trigger have to
> execute explicitly RETURN, contrary to functions returning void?
Yes, I believe so; the documentation for RETURN does not make any
exception for triggers.
> In the example afterwards "A PL/pgSQL Trigger Procedure For Auditing", in
> process_emp_audit() as AFTER trigger, the comment states, that the return
> value is ignored, but why does the function have four return statements
> instead of just one?
[ shrug... ] Seems like reasonable coding style to me; for one thing,
it would make it easier to copy-and-paste the example as a basis for a
BEFORE trigger. I probably wouldn't have written it that way myself,
but I don't feel a need to change it.
> In subsection "Triggers on Events" please replace "is called as a event
> trigger" with "is called as AN event trigger".
Good catch, looks like there's a couple of those...
Thanks for the notes!
regards, tom lane
Hello Tom,
in you answer you have not tackled the argument, that the line with NOT NULL {DEFAULT | := | = } is soo long, that it
doesfit in its current form in the PDF provided documentation:
https://www.postgresql.org/files/documentation/pdf/9.5/postgresql-9.5-A4.pdf,page logical 1063(physical 1138).
On which occasions is the online documentation regenerated (in terms of https://www.postgresql.org/docs/9.5/static/,
https://www.postgresql.org/docs/9.4/static/and
https://www.postgresql.org/files/documentation/pdf/9.5/postgresql-9.5-A4.pdf) from the .sgml files?
Greetings Dilian
On 07/18/2016 09:29 PM, Tom Lane wrote:
> dpa-postgres@aegee.org writes:
>> in doc/src/sgml/plpgsql.sgml please replace:
>> ...
>> because NOT NULL can be used only with {DEFAULT | := | =}.
>
> I'm disinclined to do that; it's not required by the plpgsql grammar,
> and in principle it might not be required at runtime either. In
> particular, if the variable is of a domain type it would be sensible for
> plpgsql to adopt the domain's default value if any.
>
>> For GET [CURRENT] DIAGNOSITCS (plpgsql.sgml, line 1441) the documentation
>> within pgpgsql.sgml is unclear, what is CURRENT supposed to do.
>
> Hmm, it's just a noise word, but I agree the docs ought to say that.
>
>> In <sect2 id="plpgsql-conditionals">, 1834 is written
>> IF ... THEN
>> CASE ... WHEN ... END CASE
>> More consistent would be to write IF ... THEN ... END IF
>
> Makes sense.
>
>> In Trigger Procedures, Triggers on Data Changes is stated, that the return
>> value of a row-level trigger is ignored. Does such a trigger have to
>> execute explicitly RETURN, contrary to functions returning void?
>
> Yes, I believe so; the documentation for RETURN does not make any
> exception for triggers.
>
>> In the example afterwards "A PL/pgSQL Trigger Procedure For Auditing", in
>> process_emp_audit() as AFTER trigger, the comment states, that the return
>> value is ignored, but why does the function have four return statements
>> instead of just one?
>
> [ shrug... ] Seems like reasonable coding style to me; for one thing,
> it would make it easier to copy-and-paste the example as a basis for a
> BEFORE trigger. I probably wouldn't have written it that way myself,
> but I don't feel a need to change it.
>
>> In subsection "Triggers on Events" please replace "is called as a event
>> trigger" with "is called as AN event trigger".
>
> Good catch, looks like there's a couple of those...
>
> Thanks for the notes!
>
> regards, tom lane
>
On Thu, Jul 21, 2016 at 5:08 PM, =D0=94=D0=B8=D0=BB=D1=8F=D0=BD =D0=9F=D0=
=B0=D0=BB=D0=B0=D1=83=D0=B7=D0=BE=D0=B2 <dpa-postgres@aegee.org>
wrote:
> Hello Tom,
>
> in you answer you have not tackled the argument, that the line with NOT
> NULL {DEFAULT | :=3D | =3D } is soo long, that it does fit in its current=
form
> in the PDF provided documentation:
> https://www.postgresql.org/files/documentation/pdf/9.5/postgresql-9.5-A4.=
pdf,
> page logical 1063(physical 1138).
>
=E2=80=8BPlease don't top-post; and trim unnecessary content from the quote=
d text
in the process.
=E2=80=8BThe failure for the PDF file to not wrap "code/syntax" blocks is n=
ot
limited to this one instance. The page for VACUUM (logical 1681, physical
1756) exhibits the same problem. I found this by happenstance during a
cursory skim of the PDF, there is at least one more instance in one of the
program syntax definitions but I gave up trying to re-locate it.
For the pl/pgsql page I could see trying to shorten it via:
expression -> expr
collation_name -> collation
That recovers 11 of the 9 required characters.
VACUUM is a bit tougher, we need at least 14 characters and there are only
two labels
The only cosmetic way to do this is to define
<OPTION> ::=3D { FULL | FREEZE | VERBOSE | ANALYZE | DISABLE_PAGE_SKIPPING =
}
VACUUM [ ( OPTION [, ...] ) ] [ table_name [ (column_name [, ...] ) ] ]
Non-cosmetically...
VACUUM [ ( { FULL | FREEZE | VERBOSE | ANALYZE | DISABLE_PAGE_SKIPPING } [,
...] ) ] [ tbl [ (col [, ...] ) ] ]
I'm hoping there is some kind of warning output during the PDF build
process that can help locate these kinds of problems. The only way to
solve them is to do what I did above - write an alternate form that is
shorter, ideally by changing labels (i.e., <replaceable>).
I don't know whether it is considered acceptable, or structurally correct,
to define "OPTION" that way but you get the idea. There is probably a more
idiomatic way to do that since long command sequences are not uncommon in
the docs and we seem to generally handle them well. Would like to give
someone more experienced a chance to comment before I go digging any deeper=
.
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> I'm hoping there is some kind of warning output during the PDF build
> process that can help locate these kinds of problems.
Yeah, look for "Overfull \hbox" in the TeX log. Unfortunately, the
warnings reference line numbers in TeX's input (the tex-pdf file,
which isn't even saved after the make is done :-(). So it's a pain
to work backwards to where the problem is in the SGML docs. But you
can if you're determined.
By my count, there are 3021 such warnings generated in current HEAD docs.
A lot of them are small enough to be negligible, but a lot are not.
There's about 450 that are for more than 72 points (an inch) of overflow.
I do not see a lot of value in attacking such problems one instance at a
time.
regards, tom lane
Дилян Палаузов <dpa-postgres@aegee.org> writes: > On which occasions is the online documentation regenerated (in terms of https://www.postgresql.org/docs/9.5/static/, https://www.postgresql.org/docs/9.4/static/and https://www.postgresql.org/files/documentation/pdf/9.5/postgresql-9.5-A4.pdf) from the .sgml files? I believe the web team updates those pages whenever a new minor release occurs. regards, tom lane