Re: BUG #14258: Documentation pl/pgsql

On Thu, Jul 21, 2016 at 5:08 PM, Дилян Палаузов <dpa-postgres(at)aegee(dot)org>
wrote:

> Hello Tom,
>
> in you answer you have not tackled the argument, that the line with NOT
> NULL {DEFAULT | := | = } 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).
>

​Please don't top-post; and trim unnecessary content from the quoted text
in the process.

​The failure for the PDF file to not wrap "code/syntax" blocks is not
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> ::= { 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.