[Proj] Some need for updated proj-4 manuals

[Gerald I. Evenden]

On Thursday 11 September 2008 8:10:32 am support.mn at elisanet.fi wrote:
> Hello,
>
> the proj-4 manuals might need some updating and cleaning?
> There are basicly two groups whcih need them.

Between answering all the emails I sometime work on the manual .

Have you looked at the libproj4 manual.pdf on:

http://members.verizon.net/~gerald.evenden/proj4/

It is 123 pages but getting a bit old.  The version in my machine is up to 128 
pages plus corrections and I am working on an improved TM section which will 
add 7 or 8 pages.  The sections on cylindricals and pseudocylindricals are 
fairly complete.  Most work is needed on conic.  Miscellaneous is fairly 
complete.  The math for all projections is given so one can see how the 
various options relate to the computations.  Internal library procedures are 
fairly complete.

The above manual does not cover lproj options (-x etc.) but they are almost 
identical to older documentation of proj.

I would like some detailed illustrations related to things like local grid 
systems but at the moment I do not have sufficiently detailed coastline file 
to do them.
 
My manuals do not do datums.

> A) Programmers that utilise the library. More or less programming
> related matters and details. This could be the "Proj-4 Programmer's
> Manual".
>
> B) End users that use the projections. They need information what
> can be done. What is available and what are the exact parameters
> and how to use them in each projection and datum available.
> Exmples are most informative. This might be something like
> "Proj-4 End User´s Manual". These people are mostly not interrested
> of the programming details and those matter should be put in the
> first manual. Then there is also the end application´s "User Manual",
> which tells more about the application and how to use it.
> That would be the third manual, written by the proj-4-application
> makers. Maybe the proj-4 part would be an appendix in this
> manual?

I do not need to take my shoes off to count the projections that are difficult 
to use---omerc is a good example of a stinker.  Also, I cannot over emphasize 
the use of the -V option with [l]proj where one can experiment with the 
options and where the output will also tell the user if an option is 
specified and not used by the projection.

> So the "Proj-4 End User Manual" goes to the end user, if the
> proj-4 definition is directly visible for the end user... sometimes
> not, if there is a layer above proj-4.
>
> Now the situation is so that there are several proj-4 manuals in
> pdf format and it is hard to find any specific information especially
> about "how to use the projections and datums" since the
> information is here and there. At least one would expect to
> find all projections and their usage (and datums) in one manual .
>
> And of course to keep those 2 manuals up to date to the latest
> program versions. Manuals might have same versions as
> programs so that everything would be documented.
>
> The end application manuals and documentations keep us so
> busy that any help with the projections and datums would be
> highly respected. BTW: Our application can only use those
> projections that have both forward and inverese projections.
> So it would be nice if those projections with missing inverese
> projection would be separated somehow in it´s own group.
>
> Etc. etc.
>
> Any ideas? Somebody might want to collect and compose
> those two proj-4 manuals using the pdf originals that are
> somewhere? Anyway that is what we would very much need.
>
> We might hide all the projection and datum complexity in some
> applications (ready made maps), but sometimes they are visible.

To be sure. there are different interest and capability levels that manuals 
address.  However, my only intererst is to provide documentation that is as 
complete as possible but also, in the interests of brevity, assumes that the 
reader has sufficient background and related skill to understand that 
material and how to properly apply it.  It is not an elementary how-to 
manual.

Please, please, please.  Anyone finding errors in the previously reference 
manual please notify this group.  Thank-you.

-- 
The whole religious complexion of the modern world is due
to the absence from Jerusalem of a lunatic asylum.
-- Havelock Ellis (1859-1939) British psychologist