General proofreading

Simple overhaul of the code: Clarify comments where unclear,
clarify code where non-risky.

The ruminations are not considered code, and hence not treated here.

Author: busstoptaktik

CHANGELOG.md

@@ -14,6 +14,10 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   in coordinate tuple types (Coor4D, Coor3D, Coor2D, Coor32)
 - `TriaxialEllpisoid`, mostly as a placeholder
 
+### Fixed
+
+- A large number of linguistic errors and ambiguities
+
 ### Changed
 
 - `CoordinateTuple` trait now requires implementation of the constructor
@@ -22,12 +26,14 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   and a number of associated traits requiring `EllipsoidBase`.
 - Meaning of `EllipsoidBase::aspect_ratio()` switched from *b / a* to the
   apparently more common *a / b*
-- Major restructuring and clean up of `lib.rs`. Only marignally visible externally,
+- Major restructuring and clean up of `lib.rs`. Only marginally visible externally,
   if using `use geodesy::prelude::*`
+- Moved some_basic_coorNdinates to `crate::test_dat::coorNd`
 
 ### Removed
 
-- CHANGES.md
+- `CHANGES.md`
+- Unused parallel context stup `context/parallel.rs`
 
 ## [0.13.0] - 2024-04-06
 

Cargo.toml

@@ -66,7 +66,7 @@ required-features = ["binary"]
 
 [profile.release]
 lto = true
-strip = true # Automatically strip symbols from the binary.
+strip = true
 
 [target.wasm32-unknown-unknown.dependencies]
 wasm-bindgen = "0.2"

HOWTO-RELEASE.md

@@ -1,15 +1,16 @@
 # DRAFT: How to release
 
+- `git switch main`
+- `just clean-check`
+
 - manually check that all [issues](https://github.com/busstoptaktik/geodesy/issues/)
   assigned to the
   [milestone for the upcomming release](https://github.com/busstoptaktik/geodesy/issues?q=is%3Aopen+is%3Aissue+milestone%3A0.14.0)
   are resolved
 - update `Cargo.toml` with new version id, i.e. `"0.14.0"`
 
-- `just clean-check`
 - `just changes` (to preview a new `CHANGELOG`)
-- update `CHANGELOG.md`
-- `just changelog` (to generate a new `CHANGELOG`)
+- manually update `CHANGELOG.md` (mostly: change unreleased to 0.14.0)
 - `git commit -a -m "CHANGELOG.md for v0.14.0"`
 - `git push`
 - `git tag v0.14.0`
@@ -25,4 +26,8 @@
 
 Twitter/Mastodon/DiscordGeo:
 
-Rust Geodesy version 0.14.0 just released. 3 months and 36 commits in the making. Get it while it's hot! https://lib.rs/geodesy | https://crates.io/crates/geodesy | https://docs.rs/geodesy/latest/geodesy/
+```txt
+Rust Geodesy version 0.14.0 just released. X months and Y commits in the making. Get it while it's hot! https://lib.rs/geodesy | https://crates.io/crates/geodesy | https://docs.rs/geodesy/latest/geodesy/
+```
+
+Also post new section of Changelog to DiscordGeo

README.md

@@ -15,7 +15,8 @@ The most important **features** are
 The most important **objectives** are
 
 - to support new, and hopefully better, abstractions,
-- to use these abstractions to build better, simpler, and more tractable, geospatial **standards, transformations, and software**.
+- to use these abstractions to build better, simpler, and more tractable,
+  geospatial **standards, transformations, and software**.
 
 If any of this resonates with you, read on after this minimal usage example...
 
@@ -31,7 +32,8 @@ $ cd foo
 $ cargo add geodesy
 ```
 
-Then copy this to the `foo/src/main.rs` file: A minimal example, computing the UTM coordinates of some Scandinavian capitals
+Then overwrite the contents of the `foo/src/main.rs` file with this:
+A minimal example, computing the UTM coordinates of some Scandinavian capitals
 
 ```rust
 use geodesy::prelude::*;
@@ -72,11 +74,28 @@ $ cargo r
 - Lambert Conformal Conic
 - Lambert Azimuthal Equal Area
 
-But fundamentally, *RG* is born as a *geodesy*, rather than *cartography* library. And while PROJ benefits from four decades of *reality hardening*, RG, being a platform for experiments, does not have operational robustness as a main focus. Hence, viewing *RG* as *another PROJ*, or *PROJ [RiiR](https://acronyms.thefreedictionary.com/RIIR)*, will lead to bad disappointment. At best, you may catch a weak mirage of a *potential* [shape of jazz to come](https://en.wikipedia.org/wiki/The_Shape_of_Jazz_to_Come) for the PROJ internal dataflow.
-
-That said, being written in Rust, with all the memory safety guarantees Rust provides, *RG* by design avoids a number of pitfalls that are explicitly worked around in the PROJ code base. So the miniscule size of *RG* compared to PROJ is not just a matter of functional pruning. It is also a matter of development using a tool wonderfully suited for the task at hand.
-
-Also, having the advantage of learning from PROJ experience, both from a user's and a developer's perspective, *RG* is designed to be significantly more extensible than PROJ. So perhaps for a number of applications, and despite its limitations, RG may be sufficient, and perhaps even useful.
+But fundamentally, *RG* is born as a *geodesy*, rather than
+a *cartography* library. And while PROJ benefits from four
+decades of *reality hardening*, RG, being a platform for experiments,
+does not have operational robustness as a main focus.
+Hence, viewing *RG* as *another PROJ*, or
+*PROJ [RiiR](https://acronyms.thefreedictionary.com/RIIR)*,
+will lead to bad disappointment.
+At best, you may catch a weak mirage of a *potential*
+[shape of jazz to come](https://en.wikipedia.org/wiki/The_Shape_of_Jazz_to_Come)
+for the PROJ internal dataflow.
+
+That said, being written in Rust, with all the memory safety guarantees Rust provides,
+*RG* by design avoids a number of pitfalls that are explicitly worked
+around in the PROJ code base. So the miniscule size of *RG* compared to
+PROJ is not just a matter of functional pruning. It is also a matter of
+development using a tool wonderfully suited for the task at hand.
+
+Also, having the advantage of learning from PROJ experience, both from
+a user's and a developer's perspective, *RG* is designed to be
+significantly more extensible than PROJ. So perhaps for a number of
+applications, and despite its limitations, RG may be sufficient, and
+perhaps even useful.
 
 ## Aims
 
@@ -87,7 +106,8 @@ Dataflow experimentation is just one aspect of *RG*. Overall, the aims are (at l
 3. Hence, provide easy access to a number of basic geodetic operations, not limited to coordinate operations.
 4. Support experiments with data flow and alternative abstractions. Mostly as a tool for aims (1, 2, 3)
 
-All four aims are guided by a wish to amend explicitly identified shortcomings in the existing geodetic system landscape.
+All four aims are guided by a wish to amend explicitly identified
+shortcomings in the existing geodetic system landscape.
 
 ## Documentation
 
@@ -103,7 +123,8 @@ The documentation is currently limited, but take a look at:
 
 ## License
 
-*Rust Geodesy*: Copyright 2020, 2021, 2022, 2023, 2024 by Thomas Knudsen <knudsen.thomas@gmail.com> and contributors.
+*Rust Geodesy*: Copyright 2020, 2021, 2022, 2023, 2024 by
+Thomas Knudsen <knudsen.thomas@gmail.com> and contributors.
 
 Licensed under either of
 
@@ -116,4 +137,7 @@ at your option.
 
 ## Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the
+Apache-2.0 license, shall be dual licensed as above, without any
+additional terms or conditions.

justfile

@@ -69,10 +69,6 @@ run-all:
 changes:
     git log --pretty=format:"%as: %s (%an)"
 
-# Update CHANGELOG file
-changelog:
-    git log --pretty=format:"%as: %s (%an)" > CHANGELOG
-
 # Some invisible oddities for general amusement
 
 _sysinfo:

src/bibliography/mod.rs

@@ -83,11 +83,18 @@ pub enum Bibliography {
     Kar22,
 
     /// Thomas Knudsen, Kristian Evers, Geir Arne Hjelle,
-    /// Guðmundur Valsson, Martin Lidberg and Pasi Häkli (2019):
+    /// Guðmundur Valsson, Martin Lidberg and Pasi Häkli, 2019:
     /// *The Bricks and Mortar for Contemporary Reimplementation of Legacy Nordic Transformations*.
     /// Geophysica, 54(1), pp. 107–116.
     Knu19,
 
+    /// R. König and K.H. Weise, 1951:
+    /// *Mathematische Grundlagen der Höheren Geodäsie und Kartographie:
+    /// Erster Band: Das Erdsphäroid und Seine Konformen Abbildungen*
+    /// Berlin: Springer, 540 pp.
+    /// [URL](https://link.springer.com/book/10.1007/978-3-642-87438-3)
+    KuW51,
+
     /// L. Krüger (1912). *Konforme Abbildung des Erdellipsoids in der Ebene*.
     /// Veröffentlichung des Königlich Preuszischen Geodätischen Instituts:
     /// Neue Folge vol. 52, Leipzig: Teubner, 181 pp.
@@ -96,6 +103,13 @@ pub enum Bibliography {
     /// [pdf](https://gfzpublic.gfz-potsdam.de/rest/items/item_8827_5/component/file_130038/content).
     Kru12,
 
+    /// Knud Poder and Karsten Engsager, 1998.
+    /// *Some Conformal Mappings and Transformations for Geodesy and Topographic Cartography*.
+    /// Copenhagen, Denmark: Geodetic Division, KMS,
+    /// Skrifter 4. række, bind 6, 63 pp.
+    /// [URL](https://ftp.space.dtu.dk/pub/Altimetry/ENGSAGER/SomeConformalMappings.pdf)
+    Pod98,
+
     /// A. C. Ruffhead (2016):  The SMITSWAM method of datum transformations
     /// consisting of Standard Molodensky in two stages with applied misclosures,
     /// Survey Review, 48:350, pp. 376-384,

src/context/minimal.rs

@@ -131,7 +131,7 @@ mod tests {
     fn basic() -> Result<(), Error> {
         let mut ctx = Minimal::new();
 
-        // The "stupid way of adding 1" macro from geodesy/macro/stupid_way.macro
+        // The "stupid way of adding 1" macro from geodesy/resources/stupid.md
         ctx.register_resource("stupid:way", "addone | addone | addone inv");
         let op = ctx.op("stupid:way")?;
 
@@ -141,7 +141,7 @@ mod tests {
         assert_eq!(steps[1], "addone");
         assert_eq!(steps[2], "addone inv");
 
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         assert_eq!(data[0].x(), 55.);
         assert_eq!(data[1].x(), 59.);
 
@@ -166,7 +166,7 @@ mod tests {
 
         let op = ctx.op("geo:in | utm zone=32 | neu:out")?;
 
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         assert_eq!(data[0].x(), 55.);
         assert_eq!(data[1].x(), 59.);
 

src/context/parallel.rs

@@ -12,7 +12,6 @@ use std::{
 /// external grids, and macros.
 /// Sufficient for most uses, especially geodetic grid development.
 /// May get somewhat clunky when working with large numbers of grids or macros,
-/// as each reside in its own file.
 #[derive(Debug)]
 pub struct Plain {
     constructors: BTreeMap<String, OpConstructor>,
@@ -120,7 +119,9 @@ impl Context for Plain {
 
     /// Instantiate an operator. Recognizes PROJ syntax and converts it to Geodesy syntax.
     /// Bear in mind, however, that Geodesy does not support all PROJ operators, and that
-    /// the input/output conventions differ.
+    /// the input/output conventions differ. This functionality may be a better fit for
+    /// somewhere between [`token::split_into_steps()`](crate::token::Tokenize::split_into_steps())
+    /// and [`token::normalize()`](crate::token::Tokenize::normalize())
     fn op(&mut self, definition: &str) -> Result<OpHandle, Error> {
         // It may be a PROJ string, so we filter it through the PROJ parser
         let definition = parse_proj(definition)?;
@@ -311,7 +312,7 @@ mod tests {
         let op = ctx.op("stupid:way")?;
 
         // ...and it works as expected?
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         assert_eq!(data[0].x(), 55.);
         assert_eq!(data[1].x(), 59.);
 
@@ -341,7 +342,7 @@ mod tests {
         let op = ctx.op("stupid:way_too")?;
 
         // ...and it works as expected?
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
 
         ctx.apply(op, Fwd, &mut data)?;
         assert_eq!(data[0].x(), 57.);
@@ -352,13 +353,13 @@ mod tests {
         assert!(matches!(op, Err(Error::Syntax(_))));
 
         let op = ctx.op("stupid:addthree")?;
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         ctx.apply(op, Fwd, &mut data)?;
         assert_eq!(data[0].x(), 58.);
         assert_eq!(data[1].x(), 62.);
 
         let op = ctx.op("stupid:addthree_one_by_one")?;
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         ctx.apply(op, Fwd, &mut data)?;
         assert_eq!(data[0].x(), 58.);
         assert_eq!(data[1].x(), 62.);
@@ -373,7 +374,7 @@ mod tests {
 
         // But this classic should work...
         let op = ctx.op("geo:in | utm zone=32")?;
-        let mut data = some_basic_coor2dinates();
+        let mut data = crate::test_data::coor2d();
         ctx.apply(op, Fwd, &mut data)?;
         let expected = [691875.6321396609, 6098907.825005002];
         assert_float_eq!(data[0].0, expected, abs_all <= 1e-9);

src/context/plain.rs

@@ -151,4 +151,10 @@ mod tests {
         let b = Coor32([4., 3.]);
         assert_eq!(a.dot(b), 10.)
     }
+
+    #[test]
+    fn crate_test_data() {
+        let a = crate::test_data::coor32();
+        assert_eq!(a[0][0], 55.);
+    }
 }

src/coordinate/coor32.rs

@@ -1,4 +1,4 @@
-/// CoordinateSet is the fundamental coordinate access interface in ISO-19111.
+/// `CoordinateSet` is the fundamental coordinate access interface in ISO-19111.
 /// Strictly speaking, it is not a set, but (in abstract terms) rather an
 /// indexed list, or (in more concrete terms): An array.
 ///
@@ -352,7 +352,7 @@ mod tests {
     // Test the "impl<const N: usize> CoordinateSet for [Coor4D; N]"
     #[test]
     fn array() {
-        let mut operands = some_basic_coor4dinates();
+        let mut operands = crate::test_data::coor4d();
         assert_eq!(operands.len(), 2);
         assert!(!operands.is_empty());
 
@@ -374,7 +374,7 @@ mod tests {
     // Test the "impl CoordinateSet for Vec<Coor4D>"
     #[test]
     fn vector() {
-        let mut operands = Vec::from(some_basic_coor4dinates());
+        let mut operands = Vec::from(crate::test_data::coor2d());
         assert_eq!(operands.len(), 2);
         assert!(!operands.is_empty());
 
@@ -396,7 +396,7 @@ mod tests {
     // Test the "AngularUnits" conversion trait
     #[test]
     fn angular() {
-        let operands = some_basic_coor2dinates();
+        let operands = crate::test_data::coor2d();
         let cph = operands.get_coord(0);
 
         // Note the different usage patterns when using the AngularUnits trait with

src/coordinate/set.rs

@@ -107,13 +107,13 @@ all_coord_operators!(Coor2D, Coor2D, coor2d);
 all_coord_operators!(Coor2D, Coor32, coor2d);
 all_coord_operators!(Coor32, Coor32, coor32);
 
-/// CoordinateTuple is the ISO-19111 atomic spatial/spatiotemporal
+/// `CoordinateTuple` is the ISO-19111 atomic spatial/spatiotemporal
 /// referencing element. So loosely speaking, a CoordinateSet is a
 /// collection of CoordinateTuples.
 ///
 /// Note that (despite the formal name) the underlying data structure
-/// need not be a tuple: It can be any item, for which it makes sense
-/// to implement the CoordinateTuple trait.
+/// need not be a Rust tuple: It can be any item, for which it makes
+///  sense to implement the CoordinateTuple trait.
 ///
 /// The CoordinateTuple trait provides a number of convenience accessors
 /// for accessing single coordinate elements or tuples of subsets.

src/coordinate/tuple.rs

@@ -51,6 +51,12 @@ impl Ellipsoid {
             return Ok(Ellipsoid::new(ax, f));
         }
 
+        // Remove optional parenthesis
+        let mut name = name;
+        if name.starts_with('(') && name.ends_with(')') {
+            name = name.strip_prefix('(').unwrap().strip_suffix(')').unwrap();
+        }
+
         // The "semimajor, reciproque-flattening" form, e.g. "6378137, 298.3"
         let a_and_rf = name.split(',').collect::<Vec<_>>();
         if a_and_rf.len() == 2_usize {
@@ -88,6 +94,10 @@ mod tests {
         assert_eq!(ellps.semimajor_axis(), 6378137.0);
         assert_eq!(ellps.flattening(), 1. / 298.25);
 
+        let ellps = Ellipsoid::named("(6378137, 298.25)")?;
+        assert_eq!(ellps.semimajor_axis(), 6378137.0);
+        assert_eq!(ellps.flattening(), 1. / 298.25);
+
         let ellps = Ellipsoid::named("GRS80")?;
         assert_eq!(ellps.semimajor_axis(), 6378137.0);
         assert_eq!(ellps.flattening(), 1. / 298.257_222_100_882_7);