From 7a4ae9fcfe12d7b7c94df18ef9d1780c664040f0 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 9 May 2018 23:20:33 +0200 Subject: Remove PDF download link to download section --- docs/source/download.rst | 9 +++------ docs/source/index.rst | 5 ----- 2 files changed, 3 insertions(+), 11 deletions(-) (limited to 'docs/source') diff --git a/docs/source/download.rst b/docs/source/download.rst index d7c60d63..510751c4 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -4,13 +4,7 @@ Download ================================================================================ -.. contents:: Contents - :depth: 3 - :backlinks: none -Release Notes --------------------------------------------------------------------------------- -* `NEWS `_ Current Release -------------------------------------------------------------------------------- @@ -20,6 +14,7 @@ Current Release * **2018-03-01** `proj-datumgrid-europe-1.0.zip`_ * **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_ * **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_ +* **PDF Manual** `proj.pdf`_ Past Releases -------------------------------------------------------------------------------- @@ -42,6 +37,8 @@ Past Releases .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip .. _`md5`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz.md5 +.. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf + Binaries -------------------------------------------------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 72bf1600..5eb521c8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,11 +27,6 @@ own software. PROJ is maintained on `GitHub `_. .. |coverals| image:: https://coveralls.io/repos/OSGeo/proj.4/badge.svg?branch=master :target: https://coveralls.io/r/OSGeo/proj.4?branch=master -.. only:: not latex - - Full documentation is available as a single PDF at - https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf - Documentation ================= -- cgit v1.2.3 From d02e9ede9aebc10d63007ca8d18650fad6d301d7 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 00:23:48 +0200 Subject: Create "Community" section at top level of docs Mailing list section from frontpage moved to the new section. So is the contributing and for_proj_contributors pages. --- docs/source/community/channels.rst | 37 +++++ docs/source/community/code_contributions.rst | 153 +++++++++++++++++++ docs/source/community/contributing.rst | 173 ++++++++++++++++++++++ docs/source/community/index.rst | 18 +++ docs/source/contributing.rst | 173 ---------------------- docs/source/development/for_proj_contributors.rst | 153 ------------------- docs/source/development/index.rst | 1 - docs/source/index.rst | 6 +- 8 files changed, 382 insertions(+), 332 deletions(-) create mode 100644 docs/source/community/channels.rst create mode 100644 docs/source/community/code_contributions.rst create mode 100644 docs/source/community/contributing.rst create mode 100644 docs/source/community/index.rst delete mode 100644 docs/source/contributing.rst delete mode 100644 docs/source/development/for_proj_contributors.rst (limited to 'docs/source') diff --git a/docs/source/community/channels.rst b/docs/source/community/channels.rst new file mode 100644 index 00000000..ea12c3f7 --- /dev/null +++ b/docs/source/community/channels.rst @@ -0,0 +1,37 @@ +.. _channels: + +=========================== +Communication channels +=========================== + +Mailing list +------------------------------------------------------------------------------- + +Users and developers of the library are using the mailing list to discuss all +things related to PROJ. The mailing list is the primary forum for asking for +help with use of PROJ. The mailing list is also used for announcements, discussions +about the development of the library and from time to time interesting discussions +on geodesy appear as well. You are more than welcome to join in on the discussions! + + +The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj + + +GitHub +------------------------------------------------------------------------------- + +GitHub is the development platform we use for collaborating on the PROJ code. +We use GitHub to keep track of the changes in the code and to index bug reports +and feature requests. We are happy to take contributions in any form, either +as code, bug reports, documentation or feature requests. See :ref:`contributing` +for more info on how you can help improve PROJ. + +The PROJ GitHub page can be found at https://github.com/OSGeo/proj.4 + +.. note:: + + The issue tracker on GitHub is only meant to keep track of bugs, feature + request and other things related to the development of PROJ. Please ask + your questions about the use of PROJ on the mailing list instead. + + diff --git a/docs/source/community/code_contributions.rst b/docs/source/community/code_contributions.rst new file mode 100644 index 00000000..ef144399 --- /dev/null +++ b/docs/source/community/code_contributions.rst @@ -0,0 +1,153 @@ +.. _code_contributions: + +================================================================================ +Guidelines for PROJ code contributors +================================================================================ + +This is a guide for PROJ, casual or regular, code contributors. + +Code contributions. +############################################################################### + +Code contributions can be either bug fixes or new features. The process +is the same for both, so they will be discussed together in this +section. + +Making Changes +~~~~~~~~~~~~~~ + +- Create a topic branch from where you want to base your work. +- You usually should base your topic branch off of the master branch. +- To quickly create a topic branch: ``git checkout -b my-topic-branch`` +- Make commits of logical units. +- Check for unnecessary whitespace with ``git diff --check`` before + committing. +- Make sure your commit messages are in the `proper + format `__. +- Make sure you have added the necessary tests for your changes. +- Make sure that all tests pass + +Submitting Changes +~~~~~~~~~~~~~~~~~~ + +- Push your changes to a topic branch in your fork of the repository. +- Submit a pull request to the PROJ repository in the OSGeo + organization. +- If your pull request fixes/references an issue, include that issue + number in the pull request. For example: + +:: + + Wiz the bang + + Fixes #123. + +- PROJ developers will look at your patch and take an appropriate + action. + +Coding conventions +~~~~~~~~~~~~~~~~~~ + +Programming language +^^^^^^^^^^^^^^^^^^^^ + +PROJ is developed strictly in ANSI C 89. + +Coding style +^^^^^^^^^^^^ + +We don't enforce any particular coding style, but please try to keep it +as simple as possible. If improving existing code, please try to conform +with the style of the locally surrounding code. + +Whitespace +^^^^^^^^^^ + +Throughout the PROJ code base you will see differing whitespace use. +The general rule is to keep whitespace in whatever form it is in the +file you are currently editing. If the file has a mix of tabs and space +please convert the tabs to space in a separate commit before making any +other changes. This makes it a lot easier to see the changes in diffs +when evaluating the changed code. New files should use spaces as +whitespace. + +File names +^^^^^^^^^^ + +Files in which projections are implemented are prefixed with an +upper-case ``PJ_`` and most other files are prefixed with lower-case +``pj_``. Some file deviate from this pattern, most of them dates back to +the very early releases of PROJ. New contributions should follow the +pj-prefix pattern. Unless there are obvious reasons not to. + + +Tools +############################################################################### + +cppcheck static analyzer +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can run locally ``scripts/cppcheck.sh`` that is a wrapper script around the +cppcheck utility. It is known to work with cppcheck 1.61 of Ubuntu Trusty 14.0, +since this is what is currently used on Travis-CI +(``travis/linux_gcc/before_install.sh``). +At the time of writing, this also works with cppcheck 1.72 of Ubuntu Xenial +16.04, and latest cppcheck +master. + +cppcheck can have false positives. In general, it is preferable to rework the +code a bit to make it more 'obvious' and avoid those false positives. When not +possible, you can add a comment in the code like + +:: + + /* cppcheck-suppress duplicateBreak */ + +in the preceding line. Replace +duplicateBreak with the actual name of the violated rule emitted by cppcheck. + +CLang Static Analyzer (CSA) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CSA is run by the ``travis/csa`` build configuration. You may also run it locally. + +Preliminary step: install clang. For example: + +:: + + wget http://releases.llvm.org/6.0.0/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz + tar xJf clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz + +Run configure under the scan-build utility of clang: + +:: + + ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build ./configure + +Build under scan-build: + +:: + + ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build make [-j8] + +If CSA finds errors, they will be emitted during the build. And in which case, +at the end of the build process, scan-build will emit a warning message +indicating errors have been found and how to display the error report. This +is with someling like + +:: + + ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-view /tmp/scan-build-2018-03-15-121416-17476-1 + + +This will open a web browser with the interactive report. + +CSA may also have false positives. In general, this happens when the code is +non-trivial / makes assumptions that hard to check at first sight. You will +need to add extra checks or rework it a bit to make it more "obvious" for CSA. +This will also help humans reading your code ! + +Typo detection and fixes +~~~~~~~~~~~~~~~~~~~~~~~~ + +Run ``scripts/fix_typos.sh`` diff --git a/docs/source/community/contributing.rst b/docs/source/community/contributing.rst new file mode 100644 index 00000000..d56aef6e --- /dev/null +++ b/docs/source/community/contributing.rst @@ -0,0 +1,173 @@ +.. _contributing: + +=========================== +Contributing +=========================== + +PROJ has a wide and varied user base. Some are highly skilled +geodesists with a deep knowledge of map projections and reference +systems, some are GIS software developers and others are GIS users. All +users, regardless of the profession or skill level, has the ability to +contribute to PROJ. Here's a few suggestion on how: + +- Help PROJ-users that is less experienced than yourself. +- Write a bug report +- Request a new feature +- Write documentation for your favorite map projection +- Fix a bug +- Implement a new feature + +In the following sections you can find some guidelines on how to +contribute. As PROJ is managed on GitHub most contributions require +that you have a GitHub account. Familiarity with +`issues `__ and the `GitHub +Flow `__ is an advantage. + +Help a fellow PROJ user +------------------------- + +The main forum for support for PROJ is the mailing list. You can +subscribe to the mailing list +`here `__ and read the +archive `here `__. + +If you have questions about the usage of PROJ the mailing list is also +the place to go. Please *do not* use the GitHub issue tracker as a +support forum. Your question is much more likely to be answered on the +mailing list, as many more people follow that than the issue tracker. + +Adding bug reports +------------------ + +Bug reports are handled in the `issue +tracker `__ on PROJ's home on +GitHub. Writing a good bug report is not easy. But fixing a poorly +documented bug is not easy either, so please put in the effort it takes +to create a thorough bug report. + +A good bug report includes at least: + +- A title that quickly explains the problem +- A description of the problem and how it can be reproduced +- Version of PROJ being used +- Version numbers of any other relevant software being used, e.g. + operating system +- A description of what already has been done to solve the problem + +The more information that is given up front, the more likely it is that +a developer will find interest in solving the problem. You will probably +get follow-up questions after submitting a bug report. Please answer +them in a timely manner if you have an interest in getting the issue +solved. + +Finally, please only submit bug reports that are actually related to +PROJ. If the issue materializes in software that uses PROJ it is +likely a problem with that particular software. Make sure that it +actually is a PROJ problem before you submit an issue. If you can +reproduce the problem only by using tools from PROJ it is definitely a +problem with PROJ. + +Feature requests +---------------- + +Got an idea for a new feature in PROJ? Submit a thorough description +of the new feature in the `issue +tracker `__. Please include any +technical documents that can help the developer make the new feature a +reality. An example of this could be a publicly available academic paper +that describes a new projection. Also, including a numerical test case +will make it much easier to verify that an implementation of your +requested feature actually works as you expect. + +Note that not all feature requests are accepted. + +Write documentation +------------------- + +PROJ is in dire need of better documentation. Any contributions of +documentation are greatly appreciated. The PROJ documentation is +available on `proj4.org `__. The website is generated +with `Sphinx `__. Contributions to +the documentation should be made as `Pull +Requests `__ on GitHub. + +If you intend to document one of PROJ's supported projections please +use the :doc:`Mercator projection <../operations/projections/merc>` +as a template. + +Code contributions +------------------ + +See :doc:`Code contributions ` + +Legalese +~~~~~~~~ + +Committers are the front line gatekeepers to keep the code base clear of +improperly contributed code. It is important to the PROJ users, +developers and the OSGeo foundation to avoid contributing any code to +the project without it being clearly licensed under the project license. + +Generally speaking the key issues are that those providing code to be +included in the repository understand that the code will be released +under the MIT/X license, and that the person providing the code has the +right to contribute the code. For the committer themselves understanding +about the license is hopefully clear. For other contributors, the +committer should verify the understanding unless the committer is very +comfortable that the contributor understands the license (for instance +frequent contributors). + +If the contribution was developed on behalf of an employer (on work +time, as part of a work project, etc) then it is important that an +appropriate representative of the employer understand that the code will +be contributed under the MIT/X license. The arrangement should be +cleared with an authorized supervisor/manager, etc. + +The code should be developed by the contributor, or the code should be +from a source which can be rightfully contributed such as from the +public domain, or from an open source project under a compatible +license. + +All unusual situations need to be discussed and/or documented. + +Committers should adhere to the following guidelines, and may be +personally legally liable for improperly contributing code to the source +repository: + +- Make sure the contributor (and possibly employer) is aware of the + contribution terms. +- Code coming from a source other than the contributor (such as adapted + from another project) should be clearly marked as to the original + source, copyright holders, license terms and so forth. This + information can be in the file headers, but should also be added to + the project licensing file if not exactly matching normal project + licensing (COPYING). +- Existing copyright headers and license text should never be stripped + from a file. If a copyright holder wishes to give up copyright they + must do so in writing to the foundation before copyright messages are + removed. If license terms are changed it has to be by agreement + (written in email is ok) of the copyright holders. +- Code with licenses requiring credit, or disclosure to users should be + added to COPYING. +- When substantial contributions are added to a file (such as + substantial patches) the author/contributor should be added to the + list of copyright holders for the file. +- If there is uncertainty about whether a change is proper to + contribute to the code base, please seek more information from the + project steering committee, or the foundation legal counsel. + +Additional Resources +-------------------- + +- `General GitHub documentation `__ +- `GitHub pull request + documentation `__ + +Acknowledgements +---------------- + +The *code contribution* section of this CONTRIBUTING file is inspired by +`PDAL's `__ +and the *legalese* section is modified from `GDAL committer +guidelines `__ + diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst new file mode 100644 index 00000000..07308753 --- /dev/null +++ b/docs/source/community/index.rst @@ -0,0 +1,18 @@ +.. _community: + +Community +=============================================================================== + +The PROJ community is what makes the software stand out from its competitors. +PROJ is used and developed by group of very enthusiastic, knowledgeable and +friendly people. Whether you are a first time user of PROJ or a long-time +contributor the community is always very welcoming. + +.. only:: html + + .. toctree:: + :maxdepth: 1 + + channels + contributing + code_contributions diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst deleted file mode 100644 index 368f659f..00000000 --- a/docs/source/contributing.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. _contributing: - -=========================== -Contributing -=========================== - -PROJ has a wide and varied user base. Some are highly skilled -geodesists with a deep knowledge of map projections and reference -systems, some are GIS software developers and others are GIS users. All -users, regardless of the profession or skill level, has the ability to -contribute to PROJ. Here's a few suggestion on how: - -- Help PROJ-users that is less experienced than yourself. -- Write a bug report -- Request a new feature -- Write documentation for your favorite map projection -- Fix a bug -- Implement a new feature - -In the following sections you can find some guidelines on how to -contribute. As PROJ is managed on GitHub most contributions require -that you have a GitHub account. Familiarity with -`issues `__ and the `GitHub -Flow `__ is an advantage. - -Help a fellow PROJ user -------------------------- - -The main forum for support for PROJ is the mailing list. You can -subscribe to the mailing list -`here `__ and read the -archive `here `__. - -If you have questions about the usage of PROJ the mailing list is also -the place to go. Please *do not* use the GitHub issue tracker as a -support forum. Your question is much more likely to be answered on the -mailing list, as many more people follow that than the issue tracker. - -Adding bug reports ------------------- - -Bug reports are handled in the `issue -tracker `__ on PROJ's home on -GitHub. Writing a good bug report is not easy. But fixing a poorly -documented bug is not easy either, so please put in the effort it takes -to create a thorough bug report. - -A good bug report includes at least: - -- A title that quickly explains the problem -- A description of the problem and how it can be reproduced -- Version of PROJ being used -- Version numbers of any other relevant software being used, e.g. - operating system -- A description of what already has been done to solve the problem - -The more information that is given up front, the more likely it is that -a developer will find interest in solving the problem. You will probably -get follow-up questions after submitting a bug report. Please answer -them in a timely manner if you have an interest in getting the issue -solved. - -Finally, please only submit bug reports that are actually related to -PROJ. If the issue materializes in software that uses PROJ it is -likely a problem with that particular software. Make sure that it -actually is a PROJ problem before you submit an issue. If you can -reproduce the problem only by using tools from PROJ it is definitely a -problem with PROJ. - -Feature requests ----------------- - -Got an idea for a new feature in PROJ? Submit a thorough description -of the new feature in the `issue -tracker `__. Please include any -technical documents that can help the developer make the new feature a -reality. An example of this could be a publicly available academic paper -that describes a new projection. Also, including a numerical test case -will make it much easier to verify that an implementation of your -requested feature actually works as you expect. - -Note that not all feature requests are accepted. - -Write documentation -------------------- - -PROJ is in dire need of better documentation. Any contributions of -documentation are greatly appreciated. The PROJ documentation is -available on `proj4.org `__. The website is generated -with `Sphinx `__. Contributions to -the documentation should be made as `Pull -Requests `__ on GitHub. - -If you intend to document one of PROJ's supported projections please -use the `Mercator projection `__ -as a template. - -Code contributions ------------------- - -See :doc:`Code contributions ` - -Legalese -~~~~~~~~ - -Committers are the front line gatekeepers to keep the code base clear of -improperly contributed code. It is important to the PROJ users, -developers and the OSGeo foundation to avoid contributing any code to -the project without it being clearly licensed under the project license. - -Generally speaking the key issues are that those providing code to be -included in the repository understand that the code will be released -under the MIT/X license, and that the person providing the code has the -right to contribute the code. For the committer themselves understanding -about the license is hopefully clear. For other contributors, the -committer should verify the understanding unless the committer is very -comfortable that the contributor understands the license (for instance -frequent contributors). - -If the contribution was developed on behalf of an employer (on work -time, as part of a work project, etc) then it is important that an -appropriate representative of the employer understand that the code will -be contributed under the MIT/X license. The arrangement should be -cleared with an authorized supervisor/manager, etc. - -The code should be developed by the contributor, or the code should be -from a source which can be rightfully contributed such as from the -public domain, or from an open source project under a compatible -license. - -All unusual situations need to be discussed and/or documented. - -Committers should adhere to the following guidelines, and may be -personally legally liable for improperly contributing code to the source -repository: - -- Make sure the contributor (and possibly employer) is aware of the - contribution terms. -- Code coming from a source other than the contributor (such as adapted - from another project) should be clearly marked as to the original - source, copyright holders, license terms and so forth. This - information can be in the file headers, but should also be added to - the project licensing file if not exactly matching normal project - licensing (COPYING). -- Existing copyright headers and license text should never be stripped - from a file. If a copyright holder wishes to give up copyright they - must do so in writing to the foundation before copyright messages are - removed. If license terms are changed it has to be by agreement - (written in email is ok) of the copyright holders. -- Code with licenses requiring credit, or disclosure to users should be - added to COPYING. -- When substantial contributions are added to a file (such as - substantial patches) the author/contributor should be added to the - list of copyright holders for the file. -- If there is uncertainty about whether a change is proper to - contribute to the code base, please seek more information from the - project steering committee, or the foundation legal counsel. - -Additional Resources --------------------- - -- `General GitHub documentation `__ -- `GitHub pull request - documentation `__ - -Acknowledgements ----------------- - -The *code contribution* section of this CONTRIBUTING file is inspired by -`PDAL's `__ -and the *legalese* section is modified from `GDAL committer -guidelines `__ - diff --git a/docs/source/development/for_proj_contributors.rst b/docs/source/development/for_proj_contributors.rst deleted file mode 100644 index d85f5cb1..00000000 --- a/docs/source/development/for_proj_contributors.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. _for_proj_contributors: - -================================================================================ -Development rules and tools for PROJ code contributors -================================================================================ - -This is a guide for PROJ, casual or regular, code contributors. - -Code contributions. -############################################################################### - -Code contributions can be either bug fixes or new features. The process -is the same for both, so they will be discussed together in this -section. - -Making Changes -~~~~~~~~~~~~~~ - -- Create a topic branch from where you want to base your work. -- You usually should base your topic branch off of the master branch. -- To quickly create a topic branch: ``git checkout -b my-topic-branch`` -- Make commits of logical units. -- Check for unnecessary whitespace with ``git diff --check`` before - committing. -- Make sure your commit messages are in the `proper - format `__. -- Make sure you have added the necessary tests for your changes. -- Make sure that all tests pass - -Submitting Changes -~~~~~~~~~~~~~~~~~~ - -- Push your changes to a topic branch in your fork of the repository. -- Submit a pull request to the PROJ repository in the OSGeo - organization. -- If your pull request fixes/references an issue, include that issue - number in the pull request. For example: - -:: - - Wiz the bang - - Fixes #123. - -- PROJ developers will look at your patch and take an appropriate - action. - -Coding conventions -~~~~~~~~~~~~~~~~~~ - -Programming language -^^^^^^^^^^^^^^^^^^^^ - -PROJ is developed strictly in ANSI C 89. - -Coding style -^^^^^^^^^^^^ - -We don't enforce any particular coding style, but please try to keep it -as simple as possible. If improving existing code, please try to conform -with the style of the locally surrounding code. - -Whitespace -^^^^^^^^^^ - -Throughout the PROJ code base you will see differing whitespace use. -The general rule is to keep whitespace in whatever form it is in the -file you are currently editing. If the file has a mix of tabs and space -please convert the tabs to space in a separate commit before making any -other changes. This makes it a lot easier to see the changes in diffs -when evaluating the changed code. New files should use spaces as -whitespace. - -File names -^^^^^^^^^^ - -Files in which projections are implemented are prefixed with an -upper-case ``PJ_`` and most other files are prefixed with lower-case -``pj_``. Some file deviate from this pattern, most of them dates back to -the very early releases of PROJ. New contributions should follow the -pj-prefix pattern. Unless there are obvious reasons not to. - - -Tools -############################################################################### - -cppcheck static analyzer -~~~~~~~~~~~~~~~~~~~~~~~~ - -You can run locally ``scripts/cppcheck.sh`` that is a wrapper script around the -cppcheck utility. It is known to work with cppcheck 1.61 of Ubuntu Trusty 14.0, -since this is what is currently used on Travis-CI -(``travis/linux_gcc/before_install.sh``). -At the time of writing, this also works with cppcheck 1.72 of Ubuntu Xenial -16.04, and latest cppcheck -master. - -cppcheck can have false positives. In general, it is preferable to rework the -code a bit to make it more 'obvious' and avoid those false positives. When not -possible, you can add a comment in the code like - -:: - - /* cppcheck-suppress duplicateBreak */ - -in the preceding line. Replace -duplicateBreak with the actual name of the violated rule emitted by cppcheck. - -CLang Static Analyzer (CSA) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -CSA is run by the ``travis/csa`` build configuration. You may also run it locally. - -Preliminary step: install clang. For example: - -:: - - wget http://releases.llvm.org/6.0.0/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz - tar xJf clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz - -Run configure under the scan-build utility of clang: - -:: - - ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build ./configure - -Build under scan-build: - -:: - - ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build make [-j8] - -If CSA finds errors, they will be emitted during the build. And in which case, -at the end of the build process, scan-build will emit a warning message -indicating errors have been found and how to display the error report. This -is with someling like - -:: - - ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-view /tmp/scan-build-2018-03-15-121416-17476-1 - - -This will open a web browser with the interactive report. - -CSA may also have false positives. In general, this happens when the code is -non-trivial / makes assumptions that hard to check at first sight. You will -need to add extra checks or rework it a bit to make it more "obvious" for CSA. -This will also help humans reading your code ! - -Typo detection and fixes -~~~~~~~~~~~~~~~~~~~~~~~~ - -Run ``scripts/fix_typos.sh`` diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 0a5fea60..3f8a7bf6 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -19,4 +19,3 @@ PROJ project or using the library in their own software. cmake bindings migration - for_proj_contributors diff --git a/docs/source/index.rst b/docs/source/index.rst index 5eb521c8..03e993ec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -41,16 +41,12 @@ Documentation resource_files geodesic development/index + community/index faq - contributing glossary license references -Mailing List -================================================================================ - -The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj Indices and tables ================== -- cgit v1.2.3 From 5272565cdf5acfd15ab5c96a74f49d57b5a18217 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 12:35:33 +0200 Subject: Complete overhaul of the website frontpage Removed everything but the leading introduction and added release history from 5.0.0 and on. --- docs/source/index.rst | 330 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 298 insertions(+), 32 deletions(-) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 03e993ec..ca14a5d6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,37 +1,11 @@ .. _home: -****************************************************************************** PROJ -****************************************************************************** - -PROJ is a standard UNIX filter function which converts geographic longitude -and latitude coordinates into cartesian coordinates (and vice versa), and it is -a C API for software developers to include coordinate transformation in their -own software. PROJ is maintained on `GitHub `_. - -.. only:: html - - ============= ================================================================ - Platform Test Status and Coverage - ============= ================================================================ - Travis |travis| - AppVeyor |appveyor| - Coverage |coverals| - ============= ================================================================ - - - .. |travis| image:: https://travis-ci.org/OSGeo/proj.4.svg?branch=master - :target: https://travis-ci.org/OSGeo/proj.4 - .. |appveyor| image:: https://ci.appveyor.com/api/projects/status/584j49uguwoo5evi?svg=true - :target: https://ci.appveyor.com/project/OSGeo/proj-4 - .. |coverals| image:: https://coveralls.io/repos/OSGeo/proj.4/badge.svg?branch=master - :target: https://coveralls.io/r/OSGeo/proj.4?branch=master - -Documentation -================= +############################################################################### .. toctree:: :maxdepth: 1 + :hidden: download install @@ -47,10 +21,302 @@ Documentation license references +PROJ is a standard UNIX filter function which converts geographic longitude +and latitude coordinates into cartesian coordinates (and vice versa), and it is +a C API for software developers to include coordinate transformation in their +own software. PROJ is maintained on `GitHub `_. + +.. only:: html + + NEWS + --------------------------------------------------------------------------- + + .. attention:: + + The ``projects.h`` header and the functions related to it is considered + deprecated from version 5.0.0 and onwards. The header will be removed + from PROJ in version 6.0.0 scheduled for release February 1st 2019. + + .. attention:: + + The nmake build system on Windows will not be supported from + version 6.0.0 on onwards. Use CMake instead. + + .. attention:: + + The ``proj_api.h`` header and the functions related to it is + considered deprecated from version 5.0.0 and onwards. The header will be + removed from PROJ in version 7.0.0 scheduled for release February 1st + 2020. + + + + + PROJ 5.0.1 + ++++++++++++++++++++++++++++++++++++++++ + *March 1st 2018* + + Bug fixes + *********** + + * Handle ellipsoid change correctly in pipelines when ``+towgs84=0,0,0`` is set (`#881 `_) + + + * Handle the case where nad_ctable2_init returns NULL (`#883 `_) + + + * Avoid shadowed declaration errors with old gcc (`#880 `_) + + + * Expand ``+datum`` properly in pipelines (`#872 `_) + + + * Fail gracefully when incorrect headers are encountered in grid files (`#875 `_) + + + * Improve roundtrip stability in pipelines using ``+towgs84`` (`#871 `_) + + + * Fixed typo in gie error codes (`#861 `_) + + + * Numerical stability fixes to the geodesic package (`#826 `_ & `#843 `_) + + + * Make sure that transient errors are returned correctly (`#857 `_) + + + * Make sure that locally installed header files are not used when building PROJ (`#849 `_) + + + * Fix inconsistent parameter names in ``proj.h``/``proj_4D_api.c`` (`#842 `_) + + + * Make sure ``+vunits`` is applied (`#833 `_) + + + * Fix incorrect Web Mercator transformations (`#834 `_) + + + + PROJ 5.0.0 + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + *February 1st 2018* + + This version of PROJ introduces some significant extensions and + improvements to (primarily) the geodetic functionality of the system. + + The main driver for introducing the new features is the emergence of + dynamic reference frames, the increasing use of high accuracy GNSS, + and the related growing demand for accurate coordinate + transformations. While older versions of PROJ included some geodetic + functionality, the new framework lays the foundation for turning PROJ + into a generic geospatial coordinate transformation engine. + + The core of the library is still the well established projection code. + The new functionality is primarily exposed in a new programming + interface and a new command line utility, :ref:`cct` + (for "Coordinate Conversion and Transformation"). The old programming interface is + still available and can - to some extent - use the new geodetic + transformation features. + + The internal architecture has also seen many changes and much + improvement. So far, these improvements respect the existing + programming interface. But the process has revealed a need to simplify + and reduce the code base, in order to support sustained active + development. + + + **Therefore we have scheduled regular releases over the coming years** + **which will gradually remove the old programming interface.** + + **This will cause breaking changes with the next two major version** + **releases, which will affect all projects that depend on PROJ** + **(cf. section "deprecations" below).** + + The decision to break the existing API has not been easy, but has + ultimately been deemed necessary to ensure the long term survival of + the project. Not only by improving the maintainability immensely, but + also by extending the potential user (and hence developer) community. + + The end goal is to deliver a generic coordinate transformation + software package with a clean and concise code base appealing to + both users and developers. + + + Versioning and naming + *************************************************************************** + + For the first time in more than 25 years the major version number of + the software is changed. The decision to do this is based on the many + new features and new API. While backwards compatibility remains - + except in a few rare corner cases - the addition of a new and improved + programming interface warrants a new major release. + + The new major version number unfortunately leaves the project in a bit + of a conundrum regarding the name. For the majority of the life-time + of the product it has been known as PROJ.4, but since we have now + reached version 5 the name is no longer aligned with the version + number. + + Hence we have decided to decouple the name from the version number and + from this version and onwards the product will simply be called PROJ. + + In recognition of the history of the software we are keeping PROJ.4 as + the *name of the organizing project*. The same project team also + produces the datum-grid package. + + In summary: + + * The PROJ.4 project provides the product PROJ, which is now at + version 5.0.0. + + * The foundational component of PROJ is the library libproj. + + * Other PROJ components include the application proj, which provides + a command line interface to libproj. + + * The PROJ.4 project also distributes the datum-grid package, + which at the time of writing is at version 1.6.0. + + Updates + *************************************************************************** + + * Introduced new API in ``proj.h``. + + - The new API is orthogonal to the existing ``proj_api.h`` API and the internally used ``projects.h`` API. + + - The new API adds the ability to transform spatiotemporal (4D) coordinates. + + - Functions in the new API use the ``proj_`` namespace. + + - Data types in the new API use the ``PJ_`` namespace. + + * Introduced the concept of "transformation pipelines" that makes possible to do complex geodetic transformations of coordinates by daisy chaining simple coordinate operations. + + * Introduced :ref:`cct`, the Coordinate Conversion and Transformation application. + + * Introduced :ref:`gie`, the Geospatial Integrity Investigation Environment. + + - Selftest invoked by ``-C`` flag in :ref:`proj` has been removed + - Ported approx. 1300 built-in selftests to :ref:`gie` format + - Ported approx. 1000 tests from the gigs test framework + - Added approx. 200 new tests + + * Adopted terminology from the OGC/ISO-19100 geospatial standards series. Key definitions are: + + - At the most generic level, a *coordinate operation* is a change of coordinates, based on a one-to-one relationship, from one coordinate reference system to another. + + - A *transformation* is a coordinate operation in which the two coordinate reference systems are based on different datums, e.g. a change from a global reference frame to a regional frame. + + - A *conversion* is a coordinate operation in which both coordinate reference systems are based on the same datum, e.g. change of units of coordinates. + + - A *projection* is a coordinate conversion from an ellipsoidal coordinate system to a plane. Although projections are simply conversions according to the standard, they are treated as separate entities in PROJ as they make up the vast majority of operations in the library. + + * New operations + + - :ref:`The pipeline operator` (``pipeline``) + + - Transformations + + :ref:`Helmert transform` (``helmert``) + + Horner real and complex polynomial evaluation (``horner``) + + :ref:`Horizontal gridshift` (``hgridshift``) + + :ref:`Vertical gridshift` (``vgridshift``) + + :ref:`Molodensky transform` (``molodensky``) + + :ref:`Kinematic gridshift with deformation model` (``deformation``) + + - Conversions + + :ref:`Unit conversion` (``unitconvert``) + + :ref:`Axis swap` (``axisswap``) + + - Projections + + :ref:`Central Conic projection` (``ccon``) + + * Significant documentation updates, including + + - Overhaul of the structure of the documentation + - A better introduction to the use of PROJ + - :ref:`A complete reference to the new API` + - a complete rewrite of the section on geodesic calculations + - Figures for all projections + + * New "free format" option for operation definitions, which permits separating tokens by whitespace when specifying key/value- pairs, e.g. ``proj = merc lat_0 = 45``. + + * Added metadata to init-files that can be read with the :c:func:`proj_init_info` function in the new ``proj.h`` API. + + * Added ITRF2000, ITRF2008 and ITRF2014 init-files with ITRF transformation parameters, including plate motion model parameters. + + * Added ellipsoid parameters for GSK2011, PZ90 and "danish". The latter is similar to the already supported andrae ellipsoid, but has a slightly different semimajor axis. + + * Added Copenhagen prime meridian. + + * Updated EPSG database to version 9.2.0. + + * Geodesic library updated to version 1.49.2-c. + + * Support for analytical partial derivatives has been removed. + + * Improved performance in Winkel Tripel and Aitoff. + + * Introduced ``pj_has_inverse()`` function to ``proj_api.h``. Checks if an operation has an inverse. Use this instead of checking whether ``P->inv`` exists, since that can no longer be relied on. + + * ABI version number updated to 13:0:0. + + * Removed support for Windows CE. + + * Removed the VB6 COM interface. + + Bug fixes + *************************************************************************** + + * Fixed incorrect convergence calculation in Lambert Conformal Conic. (`#16 `_) + + + * Handle ellipsoid parameters correctly when using ``+nadgrids=@null``. (`#22 `_) + + + * Return correct latitude when using negative northings in Transverse Mercator. (`#138 `_) + + + * Return correct result at origin in inverse Mod. Stereographic of Alaska. (`#161 `_) + + + * Return correct result at origin in inverse Mod. Stereographic of 48 U.S. (`#162 `_) + + + * Return correct result at origin in inverse Mod. Stereographic of 50 U.S. (`#163 `_) + + + * Return correct result at origin in inverse Lee Oblated Stereographic. (`#164 `_) + + + * Return correct result at origin in inverse Miller Oblated Stereographic. (`#165 `_) + + + * Fixed scaling and wrap-around issues in Oblique Cylindrical Equal Area. (`#166 `_) + + + * Corrected a coefficient error in inverse Transverse Mercator. (`#174 `_) + + * Respect ``-r`` flag when calling :program:`proj` with ``-V``. (`#184 `_) + + * Remove multiplication by 2 at the equator error in Stereographic projection. (`#194 `_) + + * Allow +alpha=0 and +gamma=0 when using Oblique Mercator. (`#195 `_) + + * Return correct result of inverse Oblique Mercator when alpha is between 90 and 270. (`#331 `_) + + * Avoid segmentation fault when accessing point outside grid. (`#396 `_) + + * Avoid segmentation fault on NaN input in Robin inverse. (`#463 `_) + + * Very verbose use of :program:`proj` (``-V``) on Windows is fixed. (`#484 `_) + + * Fixed memory leak in General Oblique Transformation. (`#497 `_) -Indices and tables -================== + * Equations for meridian convergence and partial derivatives have + been corrected for non-conformal projections. (`#526 `_) -* :ref:`genindex` -* :ref:`search` + * Fixed scaling of cartesian coordinates in ``pj_transform()``. (`#726 `_) + * Additional bug fixes courtesy of `Google's OSS-Fuzz program `_ -- cgit v1.2.3 From f5eeef8a5933d41f229f6551c6612daa5d61a7b5 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 17:34:36 +0200 Subject: Add about section to docs Short description of PROJ. Citation section added from README. License moved from it's own page to a section on the about page. --- docs/source/about.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 2 +- docs/source/license.rst | 46 --------------------------------- 3 files changed, 70 insertions(+), 47 deletions(-) create mode 100644 docs/source/about.rst delete mode 100644 docs/source/license.rst (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 00000000..198dbead --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,69 @@ +############################################################################### +About +############################################################################### + +PROJ is a generic coordinate transformation software, that transforms geospatial +coordinates from one coordinate reference system (CRS) to another. This +includes cartographic projections as well as geodetic transformations. + +PROJ includes :ref:`command line applications` for easy conversion of +coordinates from text files or directly from user input. In addition to the +command line utilities PROJ also exposes an +:ref:`application programming interface`, or API in short. The API +let developers use the functionality of PROJ in their own software without having +to implement similar functionality themselves. + +PROJ started purely as a cartography application letting users convert geodetic +coordinates into projected coordinates using a number of different cartographic +projections. Over the years, as the need has become apparent, support for datum +shifts has slowly worked it's way into PROJ as well. Today PROJ support more +than a hundred different map projections and can transform coordinates between +datums using all but the most obscure geodetic techniques. + +Citation +------------------------------------------------------------------------------- + +To cite PROJ in publications use: + + PROJ contributors (2018). PROJ coordinate transformation software + library. Open Source Geospatial Foundation. URL http://proj4.org/. + +A BibTeX entry for LaTeX users is + +.. code-block:: latex + + @Manual{, + title = {{PROJ} coordinate transformation software library}, + author = {{PROJ contributors}}, + organization = {Open Source Geospatial Foundation}, + year = {2018}, + url = {http://proj4.org/}, + } + +License +------------------------------------------------------------------------------- + +PROJ uses the MIT license. The software was initially released by the USGS in +the public domain. When Frank Warmerdam took over the development of PROJ it +was moved under the MIT license. The license is as follows: + + Copyright (c) 2000, Frank Warmerdam + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + diff --git a/docs/source/index.rst b/docs/source/index.rst index ca14a5d6..97872470 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,7 @@ PROJ :maxdepth: 1 :hidden: + about download install usage/index @@ -18,7 +19,6 @@ PROJ community/index faq glossary - license references PROJ is a standard UNIX filter function which converts geographic longitude diff --git a/docs/source/license.rst b/docs/source/license.rst deleted file mode 100644 index bd4f633c..00000000 --- a/docs/source/license.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _license: - -================================================================================ -License -================================================================================ - -:Author: Frank Warmerdam -:Contact: warmerdam@pobox.com -:Date: 2001 - -PROJ.4 has been placed under an MIT license. I believe this to be as close as -possible to public domain while satisfying those who say that a copyright -notice is required in some countries. The COPYING file read as follows: - -All source, data files and other contents of the PROJ.4 package are available -under the following terms. Note that the PROJ 4.3 and earlier was "public -domain" as is common with US government work, but apparently this is not a well -defined legal term in many countries. I am placing everything under the -following MIT style license because I believe it is effectively the same as -public domain, allowing anyone to use the code as they wish, including making -proprietary derivatives. - -Though I have put my own name as copyright holder, I don't mean to imply I did -the work. Essentially all work was done by Gerald Evenden. - -:: - - Copyright (c) 2000, Frank Warmerdam - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS - OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. -- cgit v1.2.3 From 609873534e6407ba0ca5c3bb6ff40425222d6a9b Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 21:19:37 +0200 Subject: Update install doc page with build instructions Also added more possible ways to install from package managers. Removed links to externally build binaries from download page. --- docs/source/download.rst | 33 ++----------- docs/source/install.rst | 123 ++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 126 insertions(+), 30 deletions(-) (limited to 'docs/source') diff --git a/docs/source/download.rst b/docs/source/download.rst index 510751c4..32ce8012 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -4,7 +4,11 @@ Download ================================================================================ +Here you can download current and previous releases of PROJ. We only supply a +distribution of the source code and various resource files archives. See +:ref:`install` for information on how to get pre-built packages of PROJ. +.. _current_release: Current Release -------------------------------------------------------------------------------- @@ -38,32 +42,3 @@ Past Releases .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip .. _`md5`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz.md5 .. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf - - -Binaries --------------------------------------------------------------------------------- - -Linux -................................................................................ - -* `RedHat RPMs `__ -* `SUSE `__ -* `Debian `__ -* `pkgsrc `__ -* `Delphi `__ - -Docker -................................................................................ - -A `Docker`_ image with just PROJ binaries and a full compliment of grid shift -files is available on `DockerHub`_: - -.. _`Docker`: https://docker.org -.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/ - -Windows -................................................................................ - -* `OSGeo4W`_ contains 32-bit and 64-bit Windows binaries, including support for many :ref:`grids `. - -.. _`OSGeo4W`: https://trac.osgeo.org/osgeo4w/ diff --git a/docs/source/install.rst b/docs/source/install.rst index 5b3256a1..03e6bc9d 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -9,6 +9,34 @@ yourself. Below are guides for installing on Windows, Linux and Mac OS X. This is a good place to get started if this is your first time using PROJ. More advanced users may want to compile the software themselves. +Installation from package management systems +################################################################################ + + +Cross platform +-------------------------------------------------------------------------------- + +PROJ is also available via cross platform package managers. + +Conda +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The conda package manager includes several PROJ packages. We recommend installing +from the ``conda-forge`` channel:: + + conda install -c conda-forge proj4 + +Docker ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A `Docker`_ image with just PROJ binaries and a full compliment of grid shift +files is available on `DockerHub`_. Get the package with:: + + docker pull osgeo/proj.4 + +.. _`Docker`: https://docker.org +.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/ + Windows -------------------------------------------------------------------------------- @@ -69,6 +97,99 @@ On Red Hat based system packages are installed with yum:: Mac OS X -------------------------------------------------------------------------------- -On OS X PROJ can be installed via the Homebrew package manager: +On OS X PROJ can be installed via the Homebrew package manager:: brew install proj + +PROJ is also available from the MacPorts system:: + + sudo ports install proj + +Compilation and installation from source code +################################################################################ + +The classical way of installing PROJ is via the source code distribution. The +most recent version is available from the :ref:`download page`. +You will need that and at least the standard *proj-datumgrid* package for a +successful installation. +The following guides show how to compile and install the software using the +Autotools and CMake build systems. + +Autotools +-------------------------------------------------------------------------------- + +FSF's configuration procedure is used to ease installation of the PROJ system. + +.. note:: + The Autotools build system is only available on UNIX-like systems. + Follow the CMake installation guide if you are not using a UNIX-like + operating system. + +The default destination path prefix for installed files is ``/usr/local``. +Results from the installation script will be placed into subdirectories ``bin``, +``include``, ``lib``, ``man/man1`` and ``man/man3``. If this default path prefix +is proper, then execute:: + + ./configure + +If another path prefix is required, then execute:: + + ./configure --prefix=/my/path + +In either case, the directory of the prefix path must exist and be writable by +the installer. + +Before proceeding with the installation we need to add the datum grids. Unzip +the contents of the *proj-datumgrid* package into ``nad/``:: + + unzip proj-datumgrid-1.7.zip -d proj-5.0.1/nad/ + +The installation will automatically move the grid files to the correct location. +Alternatively the grids can be installed manually in the directory pointed to +by the :envvar:`PROJ_LIB` environment variable. The default location is +``/usr/local/share/proj``. + +With the grid files in place we can now build and install PROJ:: + + make + make install + +The install target will create, if necessary, all required sub-directories. + +Tests are run with:: + + make check + +The test suite requires that the proj-datumgrid package is installed in +:envvar:`PROJ_LIB`. + + +CMake +-------------------------------------------------------------------------------- + +With the CMake build system you can compile and install PROJ on more or less any +platform. After unpacking the source distribution archive step into the source- +tree:: + + cd proj-5.0.1 + +Create a build directory and step into it:: + + mkdir build + cd build + +From the build directory you can now configure CMake and build the binaries:: + + cmake .. + cmake --build . + +On Windows, one may need to specify generator:: + + cmake -G "Visual Studio 15 2017" .. + +Tests are run with:: + + ctest + +The test suite requires that the proj-datumgrid package is installed +in :envvar:`PROJ_LIB`. -- cgit v1.2.3 From 6f8e1b56a9277d6689f162fda9b0be285de237ab Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 22:50:10 +0200 Subject: Remove annotations from old version of example --- docs/source/usage/projections.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst index f5f46f46..20e82763 100644 --- a/docs/source/usage/projections.rst +++ b/docs/source/usage/projections.rst @@ -129,8 +129,8 @@ meridian. :: cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid - 0 0 (input) - 3d41'16.48"E 0dN 0.000 (output) + 0 0 + 3d41'16.48"E 0dN 0.000 Axis orientation -- cgit v1.2.3 From a9758f60f02bb04657312c76f9bba55b2128641f Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 22:50:38 +0200 Subject: Improve PDF generation of docs Removed content sections from a bunch of pages since they clutter up the PDF output and the same info is available in the sidebar of the webpage. A few sections has been turned of for the PDF output, most notable the front page of the webpage. It doesn't really fit in the PDF. --- docs/source/community/index.rst | 12 +++++------- docs/source/faq.rst | 8 +++++--- docs/source/geodesic.rst | 4 ---- docs/source/index.rst | 13 +++++++------ docs/source/references.rst | 8 +++++--- docs/source/resource_files.rst | 4 ---- 6 files changed, 22 insertions(+), 27 deletions(-) (limited to 'docs/source') diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst index 07308753..675d107a 100644 --- a/docs/source/community/index.rst +++ b/docs/source/community/index.rst @@ -8,11 +8,9 @@ PROJ is used and developed by group of very enthusiastic, knowledgeable and friendly people. Whether you are a first time user of PROJ or a long-time contributor the community is always very welcoming. -.. only:: html +.. toctree:: + :maxdepth: 1 - .. toctree:: - :maxdepth: 1 - - channels - contributing - code_contributions + channels + contributing + code_contributions diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 6d6d2280..333a5029 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -4,9 +4,11 @@ FAQ ****************************************************************************** -.. contents:: Contents - :depth: 3 - :backlinks: none +.. only:: not latex + + .. contents:: + :depth: 3 + :backlinks: none diff --git a/docs/source/geodesic.rst b/docs/source/geodesic.rst index 8f6f5bbe..f677ae1d 100644 --- a/docs/source/geodesic.rst +++ b/docs/source/geodesic.rst @@ -3,10 +3,6 @@ Geodesic calculations ===================== -.. contents:: Contents - :depth: 2 - :backlinks: none - Introduction ------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 97872470..86393291 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ PROJ ############################################################################### .. toctree:: - :maxdepth: 1 + :maxdepth: 3 :hidden: about @@ -21,13 +21,14 @@ PROJ glossary references -PROJ is a standard UNIX filter function which converts geographic longitude -and latitude coordinates into cartesian coordinates (and vice versa), and it is -a C API for software developers to include coordinate transformation in their -own software. PROJ is maintained on `GitHub `_. - .. only:: html + PROJ is a standard UNIX filter function which converts geographic longitude + and latitude coordinates into cartesian coordinates (and vice versa), and it is + a C API for software developers to include coordinate transformation in their + own software. PROJ is maintained on `GitHub `_. + + NEWS --------------------------------------------------------------------------- diff --git a/docs/source/references.rst b/docs/source/references.rst index 75d7f352..807e2faa 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -1,8 +1,10 @@ .. _references: -================================================================================ -References -================================================================================ +.. only:: not latex + + ================================================================================ + References + ================================================================================ .. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002), ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications, diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst index daf5c00a..b6aa950d 100644 --- a/docs/source/resource_files.rst +++ b/docs/source/resource_files.rst @@ -4,10 +4,6 @@ Resource files ================================================================================ -.. contents:: Contents - :depth: 2 - :backlinks: none - A number of files containing preconfigured transformations and default parameters for certain projections are bundled with the PROJ distribution. Init files contains preconfigured proj-strings for various coordinate reference systems -- cgit v1.2.3