Refactor: autoOrient() is primary, rotate() is alias

docs/api-operation.md

@@ -1,19 +1,15 @@
 ## rotate
 > rotate([angle], [options]) ⇒ <code>Sharp</code>
 
-Rotate the output image by either an explicit angle
-or auto-orient based on the EXIF `Orientation` tag.
+Rotate the output image.
 
-If an angle is provided, it is converted to a valid positive degree rotation.
+The provided angle is converted to a valid positive degree rotation.
 For example, `-450` will produce a 270 degree rotation.
 
 When rotating by an angle other than a multiple of 90,
 the background colour can be provided with the `background` option.
 
-If no angle is provided, it is determined from the EXIF data.
-Mirroring is supported and may infer the use of a flip operation.
-
-The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
+For backwards compatibility, if no angle is provided, `.autoOrient()` will be called.
 
 Only one rotation can occur per pipeline (aside from an initial call without
 arguments to orient via EXIF data). Previous calls to `rotate` in the same
@@ -36,18 +32,6 @@ for example `.rotate(x).extract(y)` will produce a different result to `.extract
 | [options] | <code>Object</code> |  | if present, is an Object with optional attributes. |
 | [options.background] | <code>string</code> \| <code>Object</code> | <code>&quot;\&quot;#000000\&quot;&quot;</code> | parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. |
 
-**Example**  
-```js
-const pipeline = sharp()
-  .rotate()
-  .resize(null, 200)
-  .toBuffer(function (err, outputBuffer, info) {
-    // outputBuffer contains 200px high JPEG image data,
-    // auto-rotated using EXIF Orientation tag
-    // info.width and info.height contain the dimensions of the resized image
-  });
-readableStream.pipe(pipeline);
-```
 **Example**  
 ```js
 const rotateThenResize = await sharp(input)
@@ -64,17 +48,29 @@ const resizeThenRotate = await sharp(input)
 ## autoOrient
 > autoOrient() ⇒ <code>Sharp</code>
 
-Alias for calling `rotate()` with no arguments, which orients the image based
-on EXIF orientsion.
+Auto-orient based on the EXIF `Orientation` tag, then remove the tag.
+Mirroring is supported and may infer the use of a flip operation.
 
-This operation is aliased to emphasize its purpose, helping to remove any
-confusion between rotation and orientation.
+Previous or subsequent use of `rotate(angle)` and either `flip()` or `flop()`
+will logically occur after auto-orientation, regardless of call order.
 
 
 **Example**  
 ```js
 const output = await sharp(input).autoOrient().toBuffer();
 ```
+**Example**  
+```js
+const pipeline = sharp()
+  .autoOrient()
+  .resize(null, 200)
+  .toBuffer(function (err, outputBuffer, info) {
+    // outputBuffer contains 200px high JPEG image data,
+    // auto-oriented using EXIF Orientation tag
+    // info.width and info.height contain the dimensions of the resized image
+  });
+readableStream.pipe(pipeline);
+```
 
 
 ## flip