write-methods

docz/docs/08-api/07-write-options.md

@@ -5,19 +5,57 @@ title: Writing Files
 ---
 
 import current from '/version.js';
-
-# Writing Options
-
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-`XLSX.write(wb, write_opts)` attempts to write the workbook `wb`
+**`XLSX.write(wb, options)`**
+
+`write` attempts to write the workbook `wb` and return the file.
+
+The `options` argument is required.  It must specify
+- [`bookType`](#supported-output-formats) (file format of the exported file)
+- [`type`](#output-type) (return value type)
+
+**`XLSX.writeFile(wb, filename, options)`**
+
+`writeFile` attempts to write `wb` to a local file with specified `filename`.
 
-`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`.
 In browser-based environments, it will attempt to force a client-side download.
+It also supports NodeJS, Extendscript applications, and Chromium extensions.
 
-`XLSX.writeFileAsync(filename, wb, o, cb)` attempts to write `wb` to `filename`.
-If `o` is omitted, the writer will use the third argument as the callback.
+If `options` is omitted or if `bookType` is missing from the `options` object,
+the output file format will be deduced from the filename extension.
+
+<details><summary><b>NodeJS-specific methods</b> (click to show)</summary>
+
+**`XLSX.writeFileAsync(filename, wb, cb)`**
+
+**`XLSX.writeFileAsync(filename, wb, options, cb)`**
+
+attempt to write `wb` to `filename` and invoke the callback `cb` on completion.
+
+When an `options` object is specified, it is expected to be the third argument.
+
+This method only works in NodeJS and uses `fs.writeFile` under the hood.
+
+</details>
+
+:::note Recommendation
+
+`writeFile` wraps a number of export techniques, making it suitable for browser
+downloads, NodeJS, Extendscript apps, and Chromium extensions.  It does not work
+in other environments with more advanced export methods.
+
+The `write` method returns raw bytes or strings that can be exported in
+[Desktop apps](/docs/demos/desktop/) , [Mobile apps](/docs/demos/mobile) , and
+[Servers](/docs/demos/net/server).
+
+The [demos](/docs/demos) preferentially use `writeFile`. When `writeFile` is not
+supported, the demos show file creation using `write` and platform APIs.
+
+:::
+
+## Writing Options
 
 The write functions accept an options argument:
 
@@ -200,7 +238,7 @@ output formats.  The specific file type is controlled with `bookType` option:
 
 ## Output Type
 
-The `type` argument for `write` mirrors the `type` argument for `read`:
+The `type` option specifies the JS form of the output:
 
 | `type`     | output                                                          |
 |------------|-----------------------------------------------------------------|