Updated docs

doc/attributes.md

@@ -1,12 +1,14 @@
 ## Style Attributes
 
-Style attributes in Zefyr documents are simple key-value pairs, where
+> If you haven't yet, read introduction to Zefyr document model called
+> Notus [here][data_and_document];
+
+Style attributes in Notus documents are simple key-value pairs, where
 keys identify the attribute and value describes the style applied, for
 instance, `{ "heading": 1 }` defines heading style for a line of
 text with value `1` (equivalent of `h1` in HTML).
 
-It is important to note
-that one attribute can describe multiple different styles depending
+Note that one attribute can describe multiple different styles depending
 on the current value. E.g. attribute with key "heading" can be set to values
 `1`, `2` or `3`, equivalents of `h1`, `h2` and `h3` in HTML. This prevents
 a line of text from being formatted as `h1` and `h2` heading at the same time,
@@ -15,7 +17,7 @@ which is intentional.
 Additionally, each attribute gets assigned one of two scopes. An
 attribute can be either *inline-scoped* or *line-scoped*, but not both.
 A good example of an inline-scoped attribute is "bold" attribute. Bold
-style can be applied to any character within a line, but not the the
+style can be applied to any character within a line, but not to the
 line itself. Similarly "heading" style is line-scoped and has effect
 only on the line as a whole.
 
@@ -29,6 +31,7 @@ attributes in Zefyr:
 | Link    | `a`       | `inline` | `String` | Non-empty string                       |
 | Heading | `heading` | `line`   | `int`    | `1`, `2` and `3`                       |
 | Block   | `block`   | `line`   | `String` | `"ul"`, `"ol"`, `"code"` and `"quote"` |
+| Embed   | `embed`   | `inline` | `Map`    | `"hr"`, `"image"`                      |
 
 Removing a specific style is as simple as setting corresponding
 attribute to `null`.
@@ -36,35 +39,35 @@ attribute to `null`.
 Here is an example of applying some styles to a document:
 
 ```dart
-import 'package:zefyr/zefyr.dart';
+import 'package:notus/notus.dart';
 
-void makeItPretty(ZefyrDocument document) {
-  /// All attributes can be accessed through [ZefyrAttribute] class.
+void makeItPretty(NotusDocument document) {
+  /// All attributes can be accessed through [NotusAttribute] class.
 
   // Format 5 characters starting at index 0 as bold.
-  document.format(0, 5, ZefyrAttribute.bold);
+  document.format(0, 5, NotusAttribute.bold);
 
   // Similarly for italic.
-  document.format(0, 5, ZefyrAttribute.italic);
+  document.format(0, 5, NotusAttribute.italic);
 
   // Format the first line as a heading (level 1).
   // Note that there is no need to specify character range of the whole
   // line. Simply set index position to anywhere within the line and
   // length to 0.
-  document.format(0, 0, ZefyrAttribute.heading.level1);
+  document.format(0, 0, NotusAttribute.heading.level1);
 
   // Add a link:
-  document.format(10, 15, ZefyrAttribute.link.fromString('https://github.com'));
+  document.format(10, 15, NotusAttribute.link.fromString('https://github.com'));
 
   // Format a line as code block. Similarly to heading styles there is no need
   // to specify the whole character range of the line. In following example:
   // whichever line is at character index 23 in the document will get
   // formatted as code block.
-  document.format(23, 0, ZefyrAttribute.block.code);
+  document.format(23, 0, NotusAttribute.block.code);
 
   // Remove heading style from the first line. All attributes
   // have `unset` property which can be used the same way.
-  document.format(0, 0, ZefyrAttribute.heading.unset);
+  document.format(0, 0, NotusAttribute.heading.unset);
 }
 ```
 
@@ -74,21 +77,21 @@ As mentioned previously a document delta consists of a sequence of `insert`
 operations. Attributes (if any) are stored as metadata on each of the
 operations.
 
-One important detail here is how line and inline-scoped attributes are
+There is a difference in how line and inline-scoped attributes are
 handled. Since Deltas are essentially a flat data structure there is
 nothing in the format itself to represent a line of text, which is
 required to allow storing line-scoped style attributes.
 
-To solve this issue Zefyr (similarly to Quill.js) reserves the
+To solve this issue Notus document (similarly to Quill.js) reserves the
 **newline** character (aka `\n` and `0x0A`) as storage for line-scoped
 styles.
 
-Zefyr's document model is designed to enforce this rule and
+Notus document model is designed to enforce this rule and
 prevents malformed changes from being composed into a document. For
 instance, an attempt to apply "bold" style to a newline character
 will have no effect.
 
-Below is an example of Zefyr document's Delta with two lines of text.
+Below is an example of Notus document's Delta with two lines of text.
 The first line is formatted as an `h1` heading and on the second line
 there is bold-styled word "Flutter":
 
@@ -110,10 +113,10 @@ already reserved newline character for line styles.
 As it turns out, this is not a big issue and it is possible to achieve
 a friendly user experience without this extra level in a document model.
 
-The `block` attribute in Zefyr is line-scoped. To change a group of
-lines from "bullet list" to "number list" we need to update block
-style on each of the lines individually. Zefyr editor abstracts away
-such details with help of [heuristic rules][heuristics].
+The `block` attribute in Notus documents is line-scoped. To change a
+group of lines from "bullet list" to "number list" we need to update
+block style on each of the lines individually. Zefyr editor abstracts
+away such details with help of [heuristic rules][heuristics].
 
 ### Next up
 
@@ -123,4 +126,6 @@ such details with help of [heuristic rules][heuristics].
 
 ### Previous
 
-* [Data Format and Document Model](/doc/data_and_document.md)
+* [Data Format and Document Model][data_and_document]
+
+[data_and_document]: /doc/data_and_document.md

doc/data_and_document.md

@@ -1,6 +1,12 @@
 ## Data Format and Document Model
 
-Zefyr documents are based on Quill.js [Delta][] format. Deltas are
+Zefyr document model exists as a separate platform-agnostic library
+called Notus. Notus implements all building blocks of a rich text
+document and can be used separately from Zefyr on any platform
+supported by Dart SDK, e.g. web, desktop or server (macos, windows,
+linux) and, of course, mobile (ios, android).
+
+Notus documents are based on Quill.js [Delta][] format. Deltas are
 simple and expressive format of describing rich text data, and is also
 suitable for [Operational transformations][ot]. The format is
 essentially JSON, and is human readable.
@@ -82,17 +88,18 @@ for more details.
 
 ### Document model
 
-Zefyr documents are represented as a tree of nodes. There are 3 main types of
-nodes:
+Notus documents are represented as a tree of nodes. There are 3 main
+types of nodes:
 
-* `Text` - a leaf node which represents a segment of styled text within
-  a document.
-* `Line` - represents an individual line of text within a document.
+* `LeafNode` - a leaf node which represents a segment of styled text
+  within a document. There are two kinds of leaf nodes - text and
+  embeds.
+* `LineNode` - represents an individual line of text within a document.
   Line nodes are containers for leaf nodes.
 * `Block` - represents a group of adjacent lines which share the same
   style. Examples of blocks include lists, quotes or code blocks.
 
-Given above description, here is ASCII-style visualization of a Zefyr
+Given above description, here is ASCII-style visualization of a Notus
 document tree:
 
 ```
@@ -112,15 +119,14 @@ root
 ```
 
 It is currently not allowed to nest blocks inside other blocks but this
-may change in the future. More node types are likely to be added as well.
-For example, another leaf node for embedded content, like images.
+may change in the future.
 
-All manipulations of Zefyr documents are designed strictly to match
+All manipulations of Notus documents are designed strictly to match
 semantics of underlying Delta format. As a result the model itself is
 fairly simple and predictable.
 
-To learn more about consequences of this design read about
-[attributes][] and [heuristics][].
+Learn more about other building blocks of Notus documents in
+documentation for [attributes][] and [heuristics][].
 
 [heuristics]: /doc/heuristics.md
 [attributes]: /doc/attributes.md

doc/faq.md

@@ -1,17 +1,17 @@
 ## Frequently asked questions
 
-### Are Zefyr documents compatible with Quill documents?
+### Are Notus documents compatible with Quill documents?
 
-Short answer is no. Even though Zefyr uses Quill Delta as underlying
+Short answer is no. Even though Notus uses Quill Delta as underlying
 representation for its documents there are at least differences in
 attribute declarations. For instance heading style in Quill
-editor uses "header" as the attribute key, in Zefyr it's "heading".
+editor uses "header" as the attribute key, in Notus it's "heading".
 
-There are also semantical differences. In Quill, both list and heading
+There are also semantic differences. In Quill, both list and heading
 styles are treated as block styles. This means applying "heading"
-style to a list item removes the item from the list. In Zefyr, heading
+style to a list item removes the item from the list. In Notus, heading
 style is handled separately from block styles like lists and quotes.
 As a consequence you can have a heading line inside of a quote block.
 This is intentional and inspired by how Markdown handles such scenarios.
-In fact, Zefyr format tries to follow Markdown semantics as close as
+In fact, Notus format tries to follow Markdown semantics as close as
 possible.

doc/heuristics.md

@@ -2,18 +2,18 @@
 
 As it turns out, a good rich text editor not only allows the user to
 manually apply different styles to text in a document. It can also
-automatically apply certain styles based on the context of a user
-action.
+automatically apply certain styles based on the context of user
+actions.
 
 Some very common examples include autoformatting of links or inserting
-a new list item.
+a new list item when user presses `Enter` key.
 
-In Zefyr, such rules are called *heuristic rules*. There are two main
-purposes for heuritic rules:
+In Notus (document model used by Zefyr editor), such rules are called
+*heuristic rules*. There are two main purposes for heuristic rules:
 
 1. User experience: rules like above-mentioned autoformatting of links
-  are here to make editing a nice and pleasant process.
-2. Style normalizing: this is mostly invisible for the user but
+   are here to make editing a user friendly process.
+2. Semantics preservation: this is mostly invisible for the user but
   is very important nevertheless. There is a set of rules to make sure
   that a document change conforms to the data format and model
   semantics.
@@ -35,17 +35,17 @@ var doc = getDocument();
 var cursorPosition = 8; // after the word "Document"
 var selectionLength = 0; // selection is collapsed.
 var change = doc.format(
-  cursorPosition, selectionLength, ZefyrAttribute.heading.level2);
+  cursorPosition, selectionLength, NotusAttribute.heading.level2);
 ```
 
 If we try to apply this change as-is it would have no effect or, more
 likely, result in an `AssertionError`. This is why all methods in
-`ZefyrDocument` have an extra step which applies heuristic rules to
+`NotusDocument` have an extra step which applies heuristic rules to
 the change (there is one method which skips this step, `compose`,
 read more on it later) before actually composing it.
 
-The `ZefyrDocument.format` method returns an instance of `Delta` which
-was actualy applied to the document. For the above scenario it would
+The `NotusDocument.format` method returns an instance of `Delta` which
+was actually applied to the document. For the above scenario it would
 look like this:
 
 ```json
@@ -62,7 +62,7 @@ what user intended to do.
 There are more similar scenarios which are covered by heuristic rules
 to ensure consistency with the document model and provide better UX.
 
-### `ZefyrDocument.compose()` and skipping heuristic rules.
+### `NotusDocument.compose()` and skipping heuristic rules.
 
 The `compose()` method is the only method which skips the step of
 applying heuristic rules and therefore **should be used with great
@@ -84,6 +84,6 @@ This method exists mostly to enable following use cases:
   before composing.
 
 When composing a change which came from a different site or server make
-sure to use `ChangeSource.api` when calling `compose()`. This allows
+sure to use `ChangeSource.remote` when calling `compose()`. This allows
 you to distinguish such changes from local changes made by the user
-when listening on `ZefyrDocument.changes` stream.
+when listening on `NotusDocument.changes` stream.

doc/quick_start.md

@@ -1,5 +1,11 @@
 ## Quick Start
 
+Zefyr project is split in two main packages:
+
+1. `zefyr` - Flutter package which provides the UI part
+2. `notus` - platform-agnostic package which provides document model
+   used by `zefyr` package.
+
 ### Installation
 
 Add `zefyr` package as a dependency to your `pubspec.yaml`:
@@ -9,16 +15,17 @@ dependencies:
   zefyr: ^0.1.0
 ```
 
-And run `flutter packages get` to install.
+And run `flutter packages get` to install. This installs both `zefyr`
+and `notus` packages.
 
 ### Usage
 
 There are 3 main objects you would normally interact with in your code:
 
-* `ZefyrDocument`, represents a rich text document and provides
+* `NotusDocument`, represents a rich text document and provides
   high-level methods for manipulating the document's state, like
   inserting, deleting and formatting of text.
-  Read [documentation][data_and_docs] for more details on Zefyr's
+  Read [documentation][data_and_docs] for more details on Notus
   document model and data format.
 * `ZefyrEditor`, a Flutter widget responsible for rendering of rich text
   on the screen and reacting to user actions.
@@ -46,7 +53,7 @@ class MyWidgetState extends State<MyWidget> {
     super.initState();
     // Create an empty document or load existing if you have one.
     // Here we create an empty document:
-    final document = new ZefyrDocument();
+    final document = new NotusDocument();
     _controller = new ZefyrController(document);
     _focusNode = new FocusNode();
   }