[PROJ] Use of EPSG codes in proj_create()

[Kristian Evers]

As you’ve already found out, maintaining the PROJ docs is not the most active area of work.
For that reason I am somewhat hesitant on making a lot of transition guides because they would
only be of interest for a limited time period and take time from writing docs that are generally
applicable to all developers. They are also extremely difficult to write since the old API’s are
poorly documented, so the code has to be studied carefully to determine what a given function
does.

I prefer to write good introductions to the API instead of spending
time on mapping old API functions to the new API. If the development guides are written properly
they will be of use both for developers migrating from an old API to the new API and for people
starting from scratch.

Unfortunately, I myself haven’t got much available time to work on this the next couple of months.
I hope someone else has available time to pull the heavy load on this one. I am very happy to
give feedback on any documenation contributions.

To finish off this mail I just want to remind everyone that the PROJ docs are better than they ever
have been before. The API’s in projects.h and proj_api.h was practically undocumented for ~20
years. Bridging that gap is a hell of a task and it is not one that anyone particularly enjoys working
on. So please be patient. We’ll get there eventually. Sooner if we get help from the community.
All inputs are valuable to us so we can spend time on the things that are the most need of fixing.

Thanks to everyone who’s pointed out shortcomings in the documentation. Hopefully we will be
able to address those quickly!

/Kristian

> On 3 Apr 2019, at 08:04, Oliver Eichler <oliver.eichler at dspsolutions.de> wrote:
> 
> 
>> But it raises the question: What sort of things will be useful to
>> demonstrate on doc pages
>> like that?
> 
> Well, as mentioned, it should contain a code snippet that restores the old functionality of pj_transform(). I would guess that is in close to 100% of the migration cases the function to migrate. It does not have to be necessarily API compliant to pj_transform(). But it shouldn't break the functionality. And if it does this has to be documented as detailed as possible.
> 
> There is no problem in telling the users that there has been a version change and some things have to be done different. As long as I can point out what's different and provide an example for the alternative. But "Ooops it breaks because it's different and I don't really know why and how to fix it" isn't satisfying for anyone.
> 
> And probably examples how to port the other complex functions like pj_datum_transform(), pj_geocentric_to_geodetic(), pj_geodetic_to_geocentric(), pj_compare_datums() and pj_apply_gridshift() would be helpful. The rest of the functions seems to be simple enough to be replaced by some counterpart of the new API. But a complete table would help. The current one seems to be a bit short.
> 
> 
> 
> 
> _______________________________________________
> PROJ mailing list
> PROJ at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/proj