[postgis-tickets] [PostGIS] #3692: Write up developer docs on how to format code so doesn't get mangled by our parsers

[PostGIS]

#3692: Write up developer docs on how to format code so doesn't get mangled by our
parsers
----------------------------+---------------------------
  Reporter:  robe           |      Owner:  robe
      Type:  task           |     Status:  new
  Priority:  medium         |  Milestone:  PostGIS 2.4.0
 Component:  documentation  |    Version:  trunk
Resolution:                 |   Keywords:
----------------------------+---------------------------
Description changed by robe:

Old description:

> There are a lot of gotchas with our perl scripts as I am discovering
> trying to get the BRIN logic to be conditionally installed based on if
> they are not present.
>
> AS noted by strk, these aren't explained anywhere.
>
> Things like
>
> 1) DO commands have to use $$ (can't use a named delimiter) or our parser
> does crazy things with it when making upgrade
>
> 2) Conveniently whatever is created in a DO is picked up by the uninstall
> (which won't be used by DROP EXTENSION anyway, but important for old-
> fashioned folks and our current regress), as long as set CREATE
> statements are not indented.
>
> 3) Purpose of postgis_drop_before.sql and postgis_drop_after.sql for use
> to prevent ambiguous this and that when converting a function that has no
> default args to have default args, or when renaming function args.

New description:

 There are a lot of gotchas with our perl scripts as I am discovering
 trying to get the BRIN logic to be conditionally installed based on if
 they are not present.

 AS noted by strk, these aren't explained anywhere.

 Things like

 1) DO commands have to use $$ (can't use a named delimiter) or our parser
 does crazy things with it when making upgrade

 2) Conveniently whatever is created in a DO is picked up by the uninstall
 (which won't be used by DROP EXTENSION anyway, but important for old-
 fashioned folks and our current regress), as long as set CREATE statements
 are not indented.

 3) Purpose of postgis_drop_before.sql and postgis_drop_after.sql for use
 to prevent ambiguous this and that when converting a function that has no
 default args to have default args, or when renaming function args.

 4) Purpose of putting Availability and Changed notes in script files and
 how the perl upgrade script generator uses that information.

--

--
Ticket URL: <https://trac.osgeo.org/postgis/ticket/3692#comment:1>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.