Documentation

README.md

@@ -1,6 +1,100 @@
 # Markdown Library
 
+A markdown library with parallel Javascript and PHP implementations. Supports
+modular "readers" for customizing the flavor of markdown desired, including
+making custom modules. Javascript implementation is vanilla Javascript with
+no dependencies. PHP implementation is written for 8.3 but may work on older
+versions (only dependency is PHPUnit if running tests).
+
+## Usage - JS
+
+Copy [markdown.js](js/markdown.js) (or [markdown.min.js](js/markdown.min.js))
+into your project and include with a `<script src="markdown.js"></script>` tag
+in your HTML. That's it.
+
+To use, create a parser with:
+
+```javascript
+const myParser = new Markdown(); // defaults to standard syntax
+
+// or with a custom set of readers
+const myParser = new Markdown([
+	new MDParagraphReader(),
+	new MDStrongReader(),
+	new MDEmphasisReader(),
+]);
+
+// or use one of the two premade parsers
+const myParser = Markdown.standardParser;  // for a basic set of common syntaxes
+const myParser = Markdown.completeParser;  // for all supported syntaxes (except line breaks)
+```
+
+Then convert markdown to HTML with:
+
+```javascript
+const html = myParser.toHTML("Your **markdown** here.");
+```
+
+## Usage - PHP
+
+As with Javascript, simply copy [markdown.php](php/markdown.php) into your
+project and `require` it in your source.
+
+To use, create a parser with:
+
+```php
+$myParser = new Markdown(); // defaults to standard syntax
+
+// or with a custom set of readers
+$myParser = new Markdown([
+	new MDParagraphReader(),
+	new MDStrongReader(),
+	new MDEmphasisReader(),
+]);
+
+// or use one of the two premade parsers
+$myParser = Markdown::standardParser();  // for a basic set of common syntaxes
+$myParser = Markdown::completeParser();  // for all supported syntaxes (except line breaks)
+```
+
+Then convert markdown to HTML with:
+
+```php
+$html = $myParser->toHTML("Your **markdown** here.");
+```
+
+## Spreadsheets
+
+One innovation in this markdown library is the ability to include _greatly
+simplified_ spreadsheet expressions in markdown tables. Intended for simple
+formulas and sums. To use, include [spreadsheet.js](js/spreadsheet.js) or
+[spreadsheet.php](php/spreadsheet.php) in your project along with the regular
+markdown source and include `MDSpreadsheetReader` in your `Markdown` instance.
+
+Example:
+
+```markdown
+| Name  | Unit Price | Qty | Discount |        Subtotal |
+| ----- | ---------: | --: | -------: | --------------: |
+| Apple |      $0.99 |   2 |          | =B*C*(1-D) FILL |
+| Pear  |      $1.09 |   1 |      10% |                 |
+| **TOTAL** |        |     |          | =SUM(E:E)       |
+```
+
+can render as:
+
+<table>
+<thead>
+<tr><th>Name</th><th>Unit Price</th><th>Qty</th><th>Discount</th><th>Subtotal</th></tr>
+</thead>
+<tbody>
+<tr><td>Apple</td><td style="text-align: right;">$0.99</td><td style="text-align: right;">2</td><td></td><td style="text-align: right;">$1.98</td></tr>
+<tr><td>Pear</td><td style="text-align: right;">$1.09</td><td style="text-align: right;">1</td><td style="text-align: right;">10%</td><td style="text-align: right;">$0.98</td></tr>
+<tr><td><strong>TOTAL</strong></td><td></td><td></td><td></td><td style="text-align: right;">$3.07</td></tr>
+</table>
+
+## More info
+
 * [Markdown syntax reference](markdown.md)
+* [Table spreadsheet formulas](spreadsheet.md)
 * [Creating custom syntax](custom.md)
-
-Minified versions of source created with `terser --compress --mangle`.

spreadsheet.md

@@ -1,6 +1,6 @@
 # Spreadsheet Expressions
 
-Spreadsheet expressions are an optional feature not enabled in the default parser configurations. To enable it, include `spreadsheet.js` / `spreadsheet.php` and create a `Markdown` instance with a `MDSpreadsheetReader`.
+Spreadsheet expressions are an optional feature not enabled in the default parser configurations. To enable it, include [`spreadsheet.js`](js/spreadsheet.js) / [`spreadsheet.php`](php/spreadsheet.php) and create a `Markdown` instance with a `new MDSpreadsheetReader()` included in its reader array.
 
 ## Expressions
 
@@ -27,6 +27,36 @@ Rows or column references can be fixed for autofilled formulas (discussed below)
 | `=A$1` | First column and row. If transposed, the column may change but the row will not. |
 | `=$A$1` | First column and row even if transposed. |
 
+## Cell Ranges
+
+Some functions accept a range of values which can be referenced with an address range. This consists of two addresses joined with a colon (`:`) and will include all the cells in the rectangle between them.
+
+Examples.
+
+| Range | Description |
+| -- | -- |
+| `A1:C9` | All the cells in columns A, B, and C from rows 1 through 9, inclusive. |
+| `A:C` | All the cells in columns A, B, and C from all rows. |
+
+Cell ranges can be used in functions like `SUM`, `AVERAGE`, `MAX`, and others that operate on arbitrary numbers of values.
+
+If the cell range exceeds the number of rows or columns in a table, the out-of-bounds addresses will be skipped.
+
+Omitting the row number is a low maintenance way of referring to all the cells in a column without having to update the lower bound as rows are added.
+
+If a cell has a formula with a range that includes its own cell, the interpeter will automatically exclude it. E.g. this is valid:
+
+```markdown
+| Name  | Qty       |
+| ----- | --------- |
+| A     | 2         |
+| B     | 3         |
+| C     | 1         |
+| TOTAL | =SUM(B:B) |
+```
+
+The sum references column B and is also in column B but will not cause a circular reference. It will produce a result of 6.
+
 ## Operators
 
 | Operator | Description |