[Proj] A template for documenting projections

[Kristian Evers]

Good point, Howard. I've added a "Further reading" section now.

Regarding Snyder's book. It's published by the USGS and therefore presumably in the public domain. Are we allowed to use his text directly in the documentation? Filling out the blanks would be a lot faster if that's the case :)

I am not too familiar with the Sphinx ecosystem. Is it possible to use intelligent bibliography like in LaTeX? For now I have just hard-coded the references but in a PDF it would look a lot better if there was a proper bibliography at the end of the document. It's also a lot easier to manage I guess.

Kristian

> -----Oprindelig meddelelse-----
> Fra: proj-bounces at lists.maptools.org [mailto:proj-
> bounces at lists.maptools.org] På vegne af Howard Butler
> Sendt: 9. september 2016 06:12
> Til: PROJ.4 and general Projections Discussions
> Emne: Re: [Proj] A template for documenting projections
> 
> 
> > On Sep 8, 2016, at 4:50 PM, Kristian Evers <kreve at sdfe.dk> wrote:
> >
> > All,
> >
> > I have spend a few hours documenting the Mercator projection in the
> hopes that it can serve as a template for the rest of the projections that still
> need to be documented.
> >
> > http://proj4.org/projections/merc.html
> >
> > This is just my first initial thoughts on how to document a projection.
> > I've divided the page into a few sections:
> >
> > - A short introduction
> > - A table with a few key facts
> > - Plot(s)
> > - Usage/examples
> > - Underlying math
> > - References
> >
> > I would like to hear your thought on this. Is this a sufficient level of
> documentation? Did I leave out something obvious (in general terms, not
> specific to the Mercator projection)? Do you like the general format?
> 
> I think it looks great, with the greatest benefit being everything about it
> finally in one place. I might only add links to Wikipedia, Wolfram, and/or
> Wherever as a "further reading" section. Maybe we just need Snyder's book
> in Sphinx format ;)
> 
> Sphinx sure does make for some pretty documentation when you put in the
> effort. I will work through automated PDF generation of the website in
> addition to the currently existing HTML. We have this for PDAL and
> MapServer sites as well, and we have found it very valuable for snapshotting
> documentation in conjunction with releases.