[WIP] Documentation improvements + some work on GEOS

docs/make.jl

@@ -101,6 +101,12 @@ makedocs(;
         "Explanations" => [
             "Paradigms" => "explanations/paradigms.md",
             "Peculiarities" => "explanations/peculiarities.md",
+            "GIS things" => [
+                "CRS" => "explanations/crs.md",
+                "Winding order" => "explanations/winding_order.md",
+                # "Geometry types and lack of support" => "explanations/well_known_geometry.md", # TODO write this
+                # "When you should use LibGEOS or ArchGDAL" => "explanations/notgeometryops.md", # TODO write this
+            ],
         ],
         "Source code" => literate_pages,
     ],

docs/src/experiments/random_walk_through_geometryops.jl

@@ -0,0 +1,46 @@
+#=
+# A random walk through [GeometryOps.jl](https://juliageo.org/GeometryOps.jl)
+
+In this tutorial, we'll take a random walk through GeometryOps and its capabilities, just to show off what it can do.
+
+
+=#
+import GeometryOps as GO
+## ecosystem packages we'll need
+import GeoInterface as GI
+using CairoMakie # for plotting
+#
+
+#=
+## The `apply` interface
+
+- my_coord_op
+- my_linestring_op
+=# 
+
+
+#=
+## The `applyreduce` interface
+This one is arguably more useful for daily tasks.
+
+- my_centroid on a linestring/ring level
+- 
+
+=#
+
+#=
+## The `fix` interface
+- Choose your fixes
+- How to make a new fix (antimeridian cutting)
+=#
+
+
+#=
+## LibGEOS extension
+> If you can't do it yourself, then use something else.  
+TODO: chatgpt this quote
+
+=#
+import LibGEOS # we will never actually call LibGEOS here
+
+GO.buffer(poly, 1) |> Makie.poly

docs/src/explanations/crs.md

@@ -0,0 +1,32 @@
+# Coordinate Reference Systems
+
+[Coordinate Reference System](https://en.wikipedia.com/wiki/Spatial_reference_system)s are simply descriptions of what some set of coordinates really mean in reference to some standard.
+
+In a mathematical sense, coordinate reference systems can be thought of defining a _space_, with associated transformations from and to latitude-longitude space (plate-carree, long-lat, WGS84) which is the default CRS we assume.
+
+## Geographic CRS
+
+If a CRS is _geographic_, that means that it refers to coordinates on a sphere.  Such coordinates should ideally be handled using a spherical geometry library like Google's s2.  GeometryOps does not currently handle spherical geometry computations except in special cases ([`perimeter`](@ref), [`GeodesicSegments`](@ref) in `segmentize`, [`GeodesicDistance`](@ref)).
+
+A non-geographic CRS is assumed to be in Cartesian space.
+
+## Projected CRS
+
+Projected CRS are generally treated as Cartesian.
+
+## Ways to describe CRS
+
+Completely separate from the _meaning_ of the CRS is the way you describe or define it.  There are a [dizzying array of ways](@ref crs-format-table) to do this, but two easy ones are Proj strings and Well Known Text.
+
+The geographic community seems to be standardizing on [Well Known Text]() as the "best" CRS identifier.  This is quite verbose, but is unambiguous and easy enough to read once you get the hang of it.
+
+To indicate the type of CRS definition you're using, you can wrap a string in its corresponding `GeoFormatTypes` type.
+
+## [CRS format table](@id crs-format-table)
+<!-- TODO: convert this to a Markdown table-->
+- Proj-strings: a brief but powerful way to describe a set of known CRS + some transformations to them.  Really useful when plotting and interactively adjusting CRS.  See the Proj docs.
+- EPSG codes: a short way to refer to a known coordinate system in the database of the European Petroleum Survey Group.  Example: `EPSG:4236`.
+- ESRI codes: similar to EPSG codes, but referring to CRS known to ESRI instead.  Example: `ESRI:12345`
+- ProjJSON: a more structured way to express Proj-strings using JSON.  
+- KML: key-markup language, an XML extension, used in web feature services
+- Mapinfo CoordSys: 

docs/src/explanations/winding_order.md

@@ -0,0 +1,11 @@
+# Winding order
+
+Winding order refers specifically to the "direction" that a polygon's rings go in.  This has several different and conflicting definitions, which you can find some discussion of in the following articles:
+- [GIS Stack Exchange: Order of polygon vertices?](https://gis.stackexchange.com/questions/119150/order-of-polygon-vertices-in-general-gis-clockwise-or-counterclockwise)
+- [ObservableHQ winding order article](https://observablehq.com/@d3/winding-order)
+
+GeometryOps assumes that polygon exteriors are clockwise and interiors are counterclockwise.  However, most algorithms are agnostic to winding order, and instead rely on the GeoInterface `getexterior` and `gethole` functions to distinguish holes from exteriors.  Notably, _most_ GIS implementations agree that polygons can have only one exterior but several holes.
+
+## What other libraries do
+
+TODO: Markdown table with a bunch of libraries/standards, their winding orders, and references.