Coord doc tweaks

Author: hadley

R/coord-cartesian-.r

@@ -1,4 +1,4 @@
-#' Cartesian coordinates.
+#' Cartesian coordinates
 #'
 #' The Cartesian coordinate system is the most familiar, and common, type of
 #' coordinate system. Setting limits on the coordinate system will zoom the

R/coord-fixed.r

@@ -1,4 +1,4 @@
-#' Cartesian coordinates with fixed relationship between x and y scales.
+#' Cartesian coordinates with fixed "aspect ratio"
 #'
 #' A fixed scale coordinate system forces a specified ratio between the
 #' physical representation of data units on the axes. The ratio represents the

R/coord-flip.r

@@ -1,6 +1,6 @@
-#' Flipped cartesian coordinates.
+#' Cartesian coordinates with x and y flipped
 #'
-#' Flipped cartesian coordinates so that horizontal becomes vertical, and
+#' Flip cartesian coordinates so that horizontal becomes vertical, and
 #' vertical, horizontal. This is primarily useful for converting geoms and
 #' statistics which display y conditional on x, to x conditional on y.
 #'

R/coord-map.r

@@ -1,38 +1,35 @@
-#' Map projections.
+#' Map projections
 #'
-#' The representation of a portion of the earth, which is approximately spherical,
-#' onto a flat 2D plane requires a projection. This is what
-#' \code{\link{coord_map}} does. These projections account for the fact that the
-#' actual length (in km) of one degree of longitude varies between the equator
-#' and the pole. Near the equator, the ratio between the lengths of one degree
-#' of latitude and one degree of longitude is approximately 1. Near the pole, it
-#' is tends towards infinity because the length of one degree of longitude tends
-#' towards 0. For regions that span only a few degrees and are not too close to
-#' the poles, setting the aspect ratio of the plot to the appropriate lat/lon
-#' ratio approximates the usual mercator projection. This is what
-#' \code{coord_quickmap} does. With \code{\link{coord_map}} all elements of the
-#' graphic have to be projected which is not the case here. So
-#' \code{\link{coord_quickmap}} has the advantage of being much faster, in
-#' particular for complex plots such as those using with
-#' \code{\link{geom_tile}}, at the expense of correctness in the projection.
-#' This coordinate system provides the full range of map projections available
-#' in the mapproj package.
+#' \code{coord_map} projects a portion of the earth, which is approximately
+#' spherical, onto a flat 2D plane using any projection defined by the
+#' \code{mapproj} package. Map projections do not, in general, preserve straight
+#' lines, so this requires considerable computation. \code{coord_quickmap} is a
+#' quick approximation that does preserve straight lines. It works best for
+#' smaller areas closer to the equator.
+#'
+#' In general, map projections must account for the fact that the actual length
+#' (in km) of one degree of longitude varies between the equator and the pole.
+#' Near the equator, the ratio between the lengths of one degree of latitude and
+#' one degree of longitude is approximately 1. Near the pole, it is tends
+#' towards infinity because the length of one degree of longitude tends towards
+#' 0. For regions that span only a few degrees and are not too close to the
+#' poles, setting the aspect ratio of the plot to the appropriate lat/lon ratio
+#' approximates the usual mercator projection. This is what
+#' \code{coord_quickmap} does, and is much faster (particularly for complex
+#' plots like \code{\link{geom_tile}}) at the expense of correctness.
 #'
-#' @export
 #' @param projection projection to use, see
 #'    \code{\link[mapproj]{mapproject}} for list
-#' @param ... other arguments passed on to \code{\link[mapproj]{mapproject}}.
-#' Ignored if the \code{parameters} argument is present.
-#' @param parameters optional numeric vector of parameters for use
-#' with the projection argument. This argument is optional only in
-#' the sense that certain projections do not require additional
-#' parameters. Passed to \code{\link[mapproj]{mapproject}}.
+#' @param ...,parameters Other arguments passed on to
+#'   \code{\link[mapproj]{mapproject}}. Use \code{...} for named parameters to
+#'   the projection, and \code{parameters} for unnamed parameters.
+#'   \code{...} is ignored if the \code{parameters} argument is present.
 #' @param orientation projection orientation, which defaults to
-#'  \code{c(90, 0, mean(range(x)))}.  This is not optimal for many
-#'  projections, so you will have to supply your own. See
-#'  \code{\link[mapproj]{mapproject}} for more information.
-#' @param xlim manually specific x limits (in degrees of longitude)
-#' @param ylim manually specific y limits (in degrees of latitude)
+#'   \code{c(90, 0, mean(range(x)))}.  This is not optimal for many
+#'   projections, so you will have to supply your own. See
+#'   \code{\link[mapproj]{mapproject}} for more information.
+#' @param xlim,ylim Manually specific x/y limits (in degrees of
+#'   longitude/latitude)
 #' @export
 #' @examples
 #' if (require("maps")) {

R/coord-polar.r

@@ -1,4 +1,4 @@
-#' Polar coordinates.
+#' Polar coordinates
 #'
 #' The polar coordinate system is most commonly used for pie charts, which
 #' are a stacked bar chart in polar coordinates.

R/coord-transform.r

@@ -1,12 +1,12 @@
-#' Transformed cartesian coordinate system.
+#' Transformed Cartesian coordinate system
 #'
 #' \code{coord_trans} is different to scale transformations in that it occurs after
 #' statistical transformation and will affect the visual appearance of geoms - there is
 #' no guarantee that straight lines will continue to be straight.
 #'
-#' All current transformations only work with continuous values - see
-#' \code{\link[scales]{trans_new}} for list of transformations, and instructions on
-#' how to create your own.
+#' Transformations only work with continuous values: see
+#' \code{\link[scales]{trans_new}} for list of transformations, and instructions
+#' on how to create your own.
 #'
 #' @param x,y transformers for x and y axes
 #' @param xtrans,ytrans Deprecated; use \code{x} and \code{y} instead.

_pkgdown.yml

@@ -110,8 +110,19 @@ reference:
   - label_bquote
 
 - title: Coordinate systems
-  contents:
-  - starts_with("coord_")
+  desc:
+    The coordinate system determines how the `x` and `y` aesthetics combine
+    to position elements in the plot. The default coordinate system is
+    Cartesian (`coord_cartesian()`), which can be tweaked with `coord_map()`,
+    `coord_fixed()`, `coord_flip()`, and `coord_trans()`, or completely
+    replaced with `coord_polar()`.
+  contents:
+  - coord_cartesian
+  - coord_fixed
+  - coord_flip
+  - coord_map
+  - coord_polar
+  - coord_trans
 
 - title: Themes
   contents: