Txt uses CriticMarkup to track changes within a document. This is because each document created or edited with Txt must be inter-operable in other applications with minimal data loss. Embedding comments, changes, substitutions and other simple document edits in a plaintext document fits the scope of this philosophy.
As per the spec, CriticMarkup uses a simple set of actions for editing and annotating plain text: addition{++ ... ++}, deletion{-- ... --}, substitution{~~ ... ~> ... ~~}, comment{>> <<}, and highlight{== ... ==}{>> ... <<}
Desired Behaviour
Enabling Tracked Changes
Tracking Changes is enabled via a keyboard shortcut, or via the application menu Edit > Track Changes. This send a command via IPC to the renderer to trigger an context:update event with the flag trackChanges in Txt's context state updated to represent enabling or disabling this editing mode.
When trackChanges is true in Txt's context, the doc state should immediately create a copy of contents, as trackedContents. Importantly, this is not a copy of staleContents - which is the state of the document since last save.
Disabling Tracked Changes
When trackChanges switches to false, Txt maintains all of the syntax highlighting and any existing CriticMarkup syntax within the document. However, trackedContents is erased from the doc state.
Handling cursor positioning and syntax
When trackChanges is ON, the cursor should always jump past CriticMarkup syntax. If the user clicks on syntax directly, jump to the nearest available space on either side of the syntax. Always leave 1 white space character on either side of the syntax.
When trackChanges is OFF, the editor should treat CriticMarkup syntax as normal text.
Editing with Tracked Changes
Once created, the user's text interactions should be compared against trackedContents and make decisions about what to add into the document relevant to the user's cursor and their action.
Additions
If the user ADDS a keystroke and the keystroke does NOT match trackedContents at the current position, INSERT prepend/appended addition syntax {++ ++} with one whitespace between the insertion point.
For example,
The sturdy shiba outwits the | corgi
The sturdy shiba outwits the {++ c| ++} corgi
The sturdy shiba outwits the {++ cunning| ++} corgi
If the user DELETES characters AND as a result trackedContents matches the current position, REMOVE the {++ ++} that has been created.
For example,
The sturdy shiba outwits the {++ cu| ++} corgi
The sturdy shiba outwits the {++ c| ++} corgi
The sturdy shiba outwits the | corgi
If the user ADDS a keystroke and the keystroke does not match trackedContents AND the user's cursor is already between a {++ ++} syntax, suppress the creation of new CriticMarkup syntax.
The sturdy shiba outwits the {++ cunning| ++} corgi
The sturdy shiba outwits the {++ cunning, sly| ++} corgi
Deletion
If the user DELETES text and the result does NOT match trackedContents at the current position, REINSERT the deleted text and prepend/append the deletion syntax {-- --} with one whitespace.
For example:
The sturdy shiba outwits the [cunning] corgi
The sturdy shiba outwits the {-- cunning --} corgi
if the user presses BACKSPACE or DELETE, REINSERT the deleted character and prepend/append the deletion syntax {-- --} with one whitespace.
For example:
The sturdy shiba outwits the cunning| corgi
The sturdy shiba outwits the cunnin| {-- g --} corgi
if the user presses BACKSPACE or DELETE repeatedly to remove characters, REINSERT each character and move the corresponding CriticMarkup syntax one character before or after the deletion point.
The sturdy shiba outwits the cunning| corgi
The sturdy shiba outwits the cunnin| {-- g --} corgi
The sturdy shiba outwits the cun| {-- ning --} corgi
The sturdy shiba outwits the | {-- cunning --} corgi
Substitution
If a user highlights text, and then begins typing, ADD a CriticMarkup substitution. Reinsert the deleted text, append the ~> and insert their text in the
For example,
Shibas are [lovely] dogs
Shibas are {~~ lovely ~> b| ~~} dogs
Shibas are {~~ lovely ~> beautiful| ~~} dogs
In a deletion example, the cursor should always jump to the end of the deleted portion of the substitution:
Shibas are [lovely] dogs
Shibas are {-- |lovely --} dogs
Shibas are {~~ lovely ~> b| ~~} dogs
Shibas are {~~ lovely ~> beautiful| ~~} dogs
If a user deletes their substitution, revert the substitution to a deletion. For example:
For example,
Shibas are {~~ lovely ~> beautiful| ~~} dogs
Shibas are {~~ lovely ~> be| ~~} dogs
Shibas are {-- lovely| --} dogs
Substitutions are only possible when a deletion and addition happen in the same text.
Comments
Comments behave similarly to additions. Post v1.0, they will be parsed and presented slightly differently within Txt, and also maintain authorship.
If a user wishes to comment with highlight, they select the text they wish to comment, invoke the "comment" action, and a new comment is placed after the selection.
For example,
Shibas are [lovely dogs], and are very loyal to individual people and their pack.
Shibas are {== lovely dogs ==}{>> | <<}, and are very loyal to individual people and their pack.
Shibas are {== lovely dogs ==}{>> Are they?| <<}, and are very loyal to individual people and their pack.
--
This is a living issue, and behaviour will be added to and tweaked over time!
Txt uses CriticMarkup to track changes within a document. This is because each document created or edited with Txt must be inter-operable in other applications with minimal data loss. Embedding comments, changes, substitutions and other simple document edits in a plaintext document fits the scope of this philosophy.
As per the spec, CriticMarkup uses a simple set of actions for editing and annotating plain text: addition
{++ ... ++}
, deletion{-- ... --}
, substitution{~~ ... ~> ... ~~}
, comment{>> <<}
, and highlight{== ... ==}{>> ... <<}
Desired Behaviour
Enabling Tracked Changes
Tracking Changes is enabled via a keyboard shortcut, or via the application menu
Edit > Track Changes
. This send a command via IPC to the renderer to trigger ancontext:update
event with the flagtrackChanges
in Txt's context state updated to represent enabling or disabling this editing mode.When
trackChanges
istrue
in Txt's context, thedoc
state should immediately create a copy ofcontents
, astrackedContents
. Importantly, this is not a copy ofstaleContents
- which is the state of the document since last save.Disabling Tracked Changes
When
trackChanges
switches tofalse
, Txt maintains all of the syntax highlighting and any existing CriticMarkup syntax within the document. However,trackedContents
is erased from thedoc
state.Handling cursor positioning and syntax
When
trackChanges is ON
, the cursor should always jump past CriticMarkup syntax. If the user clicks on syntax directly, jump to the nearest available space on either side of the syntax. Always leave 1 white space character on either side of the syntax. WhentrackChanges is OFF
, the editor should treat CriticMarkup syntax as normal text.Editing with Tracked Changes
Once created, the user's text interactions should be compared against
trackedContents
and make decisions about what to add into the document relevant to the user's cursor and their action.Additions
If the user ADDS a keystroke and the keystroke does NOT match
trackedContents
at the current position, INSERT prepend/appended addition syntax{++ ++}
with one whitespace between the insertion point. For example,If the user DELETES characters AND as a result
trackedContents
matches the current position, REMOVE the{++ ++}
that has been created. For example,If the user ADDS a keystroke and the keystroke does not match
trackedContents
AND the user's cursor is already between a{++ ++}
syntax, suppress the creation of new CriticMarkup syntax.Deletion
If the user DELETES text and the result does NOT match
trackedContents
at the current position, REINSERT the deleted text and prepend/append the deletion syntax{-- --}
with one whitespace. For example:if the user presses BACKSPACE or DELETE, REINSERT the deleted character and prepend/append the deletion syntax
{-- --}
with one whitespace. For example:if the user presses BACKSPACE or DELETE repeatedly to remove characters, REINSERT each character and move the corresponding CriticMarkup syntax one character before or after the deletion point.
Substitution
If a user highlights text, and then begins typing, ADD a CriticMarkup substitution. Reinsert the deleted text, append the
~>
and insert their text in the For example,In a deletion example, the cursor should always jump to the end of the deleted portion of the substitution:
If a user deletes their substitution, revert the substitution to a deletion. For example: For example,
Substitutions are only possible when a deletion and addition happen in the same text.
Comments
-- This is a living issue, and behaviour will be added to and tweaked over time!