Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a CITATION file (fixes #309) #914

Merged
merged 1 commit into from Apr 7, 2018
Merged

Add a CITATION file (fixes #309) #914

merged 1 commit into from Apr 7, 2018

Conversation

@rouault
Copy link
Member

@rouault rouault commented Apr 1, 2018

No description provided.

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 1, 2018

That Zenodo doi thing looks cool too. Should we set that up as well?

There is also the paper on transformation pipelines that Thomas and I wrote. It is probably the closest we get to a proper academic reference at the moment, although that isn't saying much...

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 1, 2018

Also, shouldn't CITATION be added to at least the autoconf makefiles since it is referenced by README?

@rouault rouault force-pushed the rouault:add_citation branch from b897c38 to fb4ee7c Apr 1, 2018
@rouault
Copy link
Member Author

@rouault rouault commented Apr 1, 2018

There is also the paper on transformation pipelines that Thomas and I wrote

It is cited among other relevant ones (such as G. Evenden ones or @cffk ones) in http://proj4.org/references.html

shouldn't CITATION be added to at least the autoconf makefiles since it is referenced by README?

Done

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 1, 2018

it is cited among other relevant ones (such as G. Evenden ones or @cffk ones) in http://proj4.org/references.html

Yes, I was just thinking if it made sense as a the paper to reference. Probably not.

Done

Thanks

@rouault
Copy link
Member Author

@rouault rouault commented Apr 1, 2018

I'm completely a stranger to academics habits and customs, so I won't take any strong position on this. It seems to me that the purpose was to credit the software and its numerous contributors in a short way. Of course there are a number of works and papers that have lead to it but we cannot quote all the centenial long publications on geodesy and cartography ;-) (or could we ? like https://physics.aps.org/featured-article-pdf/10.1103/PhysRevLett.116.061102 and its 6 page long autorship :-)) I guess someone writing a paper where PROJ is used could/should cite PROJ itself with the above citation, and if he uses a particular aspect of it, cite the appropriate paper that implements the details he use (so perhaps we could add a link in CITATION to http://proj4.org/references.html so they are aware of those publications related to PROJ)
We could extend the authorship a bit with the most significant contributors: "G. Evenden, F. Warmerdam, C. Karney, K. Evers, T. Knudsen et al. PROJ contributors"

@mwtoews
Copy link
Member

@mwtoews mwtoews commented Apr 1, 2018

I'd consider R's CITATION the gold standard, as I see it used frequently in literature, which is impressive since it's a one letter software. Following their lead (and removing organization/address, modifying url):

To cite PROJ in publications use:

  PROJ contributors (2018). The PROJ coordinate transformation software
  library. URL http://proj4.org/.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {The {PROJ} coordinate transformation software library},
    author = {{PROJ contributors}},
    year = {2018},
    url = {http://proj4.org/},
  }
@kbevers
Copy link
Member

@kbevers kbevers commented Apr 3, 2018

I like the way R does it. Great example.

I think OSGeo should be used as the organization so that it instead becomes:

To cite PROJ in publications use:

  PROJ contributors (2018). The PROJ coordinate transformation software
  library. The Open Source Geospatial Foundation. URL http://proj4.org/.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {The {PROJ} coordinate transformation software library},
    author = {{PROJ contributors}},
    organization = {The Open Source Geospatial Foundation},
    year = {2018},
    url = {http://proj4.org/},
  }

The address seems to be related to the organization but it is not entirely clear to me if that is the case. If it is, there's a postal address for OSGeo here that could used.

How is version numbers dealt with in this? There's a hell of a difference if you are using version 4.9.3 and some future version 7 for instance.

Is the year static? Or is that to be updated with every major release?

@rouault rouault force-pushed the rouault:add_citation branch from fb4ee7c to 67c1e5b Apr 3, 2018
@rouault
Copy link
Member Author

@rouault rouault commented Apr 3, 2018

CITATION file updated with latest @kbevers 's content

CITATION Outdated
organization = {The Open Source Geospatial Foundation},
year = {2018},
url = {http://proj4.org/},
}

This comment has been minimized.

@kbevers

kbevers Apr 3, 2018
Member

There's a nasty special character at the end of the file here.

This comment has been minimized.

@rouault

rouault Apr 3, 2018
Author Member

Ah was rather the lack of newline character. Fixed.

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 3, 2018

@cffk @busstoptaktik does this look reasonable to you?

@rouault rouault force-pushed the rouault:add_citation branch from 67c1e5b to bd0512b Apr 3, 2018
@cffk
Copy link
Contributor

@cffk cffk commented Apr 3, 2018

Yes, this is fine. I prefer "corporate authorship" to trying to keep a list of contributors up-to-date.

One possible addition: say how a specific version of the library should be cited, with a "version" field and with a more specific URL?

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 3, 2018

Yes, this is fine. I prefer "corporate authorship" to trying to keep a list of contributors up-to-date.

Good point. Referring to the citation in the text would with the above be "... something PROJ-related (PROJ Contributors, 2018) ...". It is a bit unusual, but I guess it works.

One possible addition: say how a specific version of the library should be cited, with a "version" field and with a more specific URL?

Here is an example of using the "software" BibTex category instead of the "manual" category as above. For PROJ this would be something like:

@software{PROJ,
  author = {{The Open Source Geospatial Foundation}},
  title = {PROJ},
  url = {https://proj4.org},
  version = {5.0.1},
  date = {2018-04-01},
}

I think actually this is preferred since we still haven't got a stable manual that can be tied to each release (I hope we will have that with version 6, but let's see).

@QuLogic
Copy link
Contributor

@QuLogic QuLogic commented Apr 3, 2018

If you start using Zenodo, you would get a DOI for each version (plus a generic "latest" version DOI too.)

@mwtoews
Copy link
Member

@mwtoews mwtoews commented Apr 4, 2018

For these BiBTeX entries, @manual is the normal entry type for this sort of thing. @software is not common, and is effectively an alias for @misc where most of the fields like version are ignored when typesetting. Also date is not recognized. If you want to see the differences between the entry types on a PDF, take a look at a quick example I made on Overleaf.

Similar to what R does, only year should be updated based on the year of the release, and the version shouldn't matter in the reference. Also, HOWTO-RELEASE should be amended to check the year entries in CITATION.

Another nitpick, remove the leading "The" from author (they are not called "The OSGeo") and also title (it's not called "The PROJ"). I wasn't 100% sure about choosing OSGeo as either author or organization, since PROJ is still not an OSGeo Project; it's still a community project.

I'm not convinced a DOI will add any value that a URL already offers.

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 4, 2018

For these BiBTeX entries, @Manual is the normal entry type for this sort of thing. @software is not common, and is effectively an alias for @misc where most of the fields like version are ignored when typesetting. Also date is not recognized. If you want to see the differences between the entry types on a PDF, take a look at a quick example I made on Overleaf.

Alright. My knowledge on this stuff is quite limited. The "software" option just seemed like the right thing to do, but if it isn't really used it is better to go with the "manual" option.

So we update the year when new releases are issued and then it is up to whoever uses the reference to note exactly which version of the software was used? Maybe that should be explained in CITATION as well.

I wasn't 100% sure about choosing OSGeo as either author or organization, since PROJ is still not an OSGeo Project; it's still a community project

That is a good point. To me, and likely many others, the lines are a bit blurred here. It should be checked wether it is okay or not to brand PROJ with the OSGeo name in this situation. What is the correct forum to ask that sort of thing? The discuss list? The OSGeo board list? This might also be a good occasion for the first small steps towards becoming a proper OSGeo project instead of the confusing setup we have today with MetaCRS.

@rouault
Copy link
Member Author

@rouault rouault commented Apr 7, 2018

Can we merge this as it ? This can be later tuned...

@kbevers
Copy link
Member

@kbevers kbevers commented Apr 7, 2018

Sure. Do you mind removing the "the"s as suggested by @mwtoews ? And also update HOWTO-RELEASE.

@rouault rouault force-pushed the rouault:add_citation branch from bd0512b to b3617e6 Apr 7, 2018
@rouault rouault force-pushed the rouault:add_citation branch from b3617e6 to 64922f1 Apr 7, 2018
@rouault rouault merged commit b4b15d0 into OSGeo:master Apr 7, 2018
0 of 2 checks passed
0 of 2 checks passed
continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
Details
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
@kbevers kbevers added this to the 5.1.0 milestone Apr 13, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.