Giter VIP home page Giter VIP logo

criticmarkup-toolkit's Introduction

CriticMarkup

Welcome to the CriticMarkup Toolkit

Critic Markup is intended to provide basic editorial change tracking in plain text files. The syntax is compatible with Markdown, MultiMarkdown and HTML.

PanDiff is a diff generator with CriticMarkup output support.

The Three Laws

  1. Critic Markup shall be human readable. A human with a simple text editor can easily read and comprehend any text containing Critic Markup.
  2. Critic Markup shall be computer readable except where it conflicts with rule 1. Markup syntax should be easily parsed with simple regular expressions to support a wide variety of implementations.
  3. Critic Markup shall be compatible with existing markup syntax for Markdown, MultiMarkdown and HTML except where it conflicts with rules one or two. Many users of plain text write in combinations of Markdown and HTML. Critic Markup should work alongside that syntax.

The Goal

Critic Markup can be used in any writing environment without special applications or tool kits. While we have supplied processors and plugins that are compatible with popular apps, they are not required.

Critic Markup should be readable inline and clearly indicate the intent of the editor and author.

Critic Markup should support change tracking with multiple authors and editors through the use of comments.

Plain Text and HTML

Critic Markup may be used without a conversion to HTML. However, as with Markdown, HTML may be a desirable format for a more stylized presentation. We have several recommendations for how Critic Markup may be converted to HTML. The intent is to allow the HTML to be used without custom CSS. However, custom CSS may be used to enhance the review process.

The Basic Syntax

There are five types of Critic marks:

  • Addition {++ ++}
  • Deletion {-- --}
  • Substitution {~~ ~> ~~}
  • Comment {>> <<}
  • Highlight {== ==}{>> <<}

Using these five basic marks you can successfully copy edit in plain text.

Additions

Additions are inserted inline by surrounding the desired text with curly braces and double plus marks as shown:

Lorem ipsum dolor{++ sit++} amet...

A space character and "sit" are to be added at the position of the left (or right) most curly brace. The additions may be rendered as <ins> tags in the processed HTML:

Lorem ipsum dolor<ins> sit<ins> amet…

Paragraphs may be inserted in the same manner.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.{++

++}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero,
quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros
accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus.
Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras
tincidunt auctor varius.

To ensure the Markdown processor outputs valid HTML, the <ins> tag encloses a non-breaking space and is followed by two newlines. The result is that both paragraphs render separately. The non-breaking-space gives the tag enough content to render properly, and we assign class=break to allow for custom styling.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

<ins class=”break”>&nbsp;</ins>

Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero,
quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros
accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed
neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt
auctor varius.

Rules for proper use of the <ins> element can be found in the HTML 4 spec.

Deletions

Deletions are denoted with a similar syntax. The text to be deleted is surrounded with curly braces and double hyphens.

Lorem{‐‐ ipsum‐‐} dolor sit amet…

The word "ipsum" and a space character are marked for deletion in the above example. These deletions are rendered as <del> tags in the processed HTML.

Lorem<del> ipsum</del> dolor sit amet…

Paragraphs may also be deleted.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.{‐‐

‐‐}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero,
quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros
accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus.
Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras
tincidunt auctor varius.

The newlines will be removed by the processor and replaced by an inline <del> tag. Again, the non-breaking-space gives the tag enough content to render properly.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
Mauris massa sem, tempor sed cursus et, semper tincidunt lacus. 
<del>&nbsp;</del> Praesent sagittis, quam id egestas consequat, nisl
orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget
orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet
vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc.
Cras tincidunt auctor varius.

Rules for proper use of the <del> element can be found in the HTML 4 spec.

Substitutions

Substitutions combine a delete with an insert in one snippet, and are written as curly braces and double tildes. A squiggly arrow made up of a tilde and greater-than symbol separates the old and new text. The characters to be deleted always occur to the left of the squiggly arrow.

Lorem {~~hipsum~>ipsum~~} dolor sit amet…

Despite the unique syntax, substitutions should render as a deletion followed by an insertion.

Lorem <del>hipsum</del><ins>ipsum</ins> dolor sit amet…

Newlines are treated the same as a deletion or insertion, depending on where they're located.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
{~~Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.~>

~~}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero,
quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros
accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus.
Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras
tincidunt auctor varius.

After rendering this example, the deletion and insertion are added to the end of the first paragraph and two newlines ensure the proper paragraph break.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci
magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.
<del>Mauris massa sem, tempor sed cursus et, semper tincidunt
lacus.</del><ins class=”break”>&nbsp;</ins>

Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero,
quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros
accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed
neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt
auctor varius.

Comments

Critic Markup supports generic comments for metadata. A comment may include a note, time stamp, author initial or similar annotation.

Comments are added via a set of curly braces and double greater-than/less-than symbols.

Lorem ipsum dolor sit amet.{>>This is a comment<<}

The contents of a metadata field should render as <span class="critic comment"> after the relevant change.

Lorem ipsum dolor sit amet.<span class=”critic comment”>This is a comment</span>

Metadata may be used however you like, whether as explanations for the changes, time stamps or more. The <span> element is for inline content only, so all newlines will be stripped during conversion to HTML.

Rules for proper use of the <span> element can be found in the HTML 4 spec.

Highlights

Highlights may be added as required by an editor or author, and are noted by curly braces and double equal signs. While a highlight can be used on it's own, we recommend that it always be followed by a comment related to the highlighted passage.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.==}{>>confusing<<} Mauris massa sem, tempor sed cursus et, semper
tincidunt lacus.

Highlights should be rendered as <mark> tags in the processed HTML.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. <mark>Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.</mark><span class=”critic metadata”>confusing</span> Mauris massa
sem, tempor sed cursus et, semper tincidunt lacus.

Rules for proper use of the <mark> element can be found in the HTML 5 spec.

Putting it all together

When used in combination the marks can indicate more complex changes.

Don’t go around saying{‐‐ to people that‐‐} the world owes you a living. The
world owes you nothing. It was here first. {~~One~>Only one~~} thing is
impossible for God: To find {++any++} sense in any copyright law on the
planet. {==Truth is stranger than fiction==}{>>true<<}, but it is because
Fiction is obliged to stick to possibilities; Truth isn’t.

The above paragraphs should render to HTML in the following manner.

Don’t go around saying<del> to people that</del> the world owes you a
living. The world owes you nothing. It was here first.
<del>One</del><ins>Only one</ins> thing is impossible for God: To find
<ins>any</ins> sense in any copyright law on the planet. <mark>Truth is
stranger than fiction</mark><span class=”critic comment”>true</span>, but it
is because Fiction is obliged to stick to possibilities; Truth isn’t.

Caveats

There are a few limitations to consider when using CriticMarkup.

Avoid Newlines in CriticMarkup

Newlines should be avoided as much as possible within CriticMarkup tags. Many of the HTML elements we use are inline elements only. While we've crafted CriticMarkup with as much care as possible, it is possible for you to break the syntax and output invalid HTML if you try hard enough.

Wrap Markdown Tags Completely

While it may support incomplete Markdown tags in the future, the CriticMarkup processor currently chokes on them. Avoid this:

I really love *italic {~~fonts*~>font-styles*~~}.

Instead, wrap the asterisks completely:

I really love {~~*italic fonts*~>*italic font-styles*~~}.

Copyright 2013 Gabe Weatherhead and Erik Hess

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

criticmarkup-toolkit's People

Contributors

5thwall avatar behinder avatar divinedominion avatar gguillotte avatar hoijui avatar macdrifter avatar ttscoff avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

criticmarkup-toolkit's Issues

cli shebang

Regarding the cli script:

On a mac !#/usr/local/bin/python works by pointing to the system install. However, on my linux distro with pythonbrew using #!/usr/bin/env python seems to handle the alternative install locations without choking. This seems especially important for people using the cli inside of virtualenv.

Apologies if this isn't the proper way to raise this issue; I am not really a programmer. This also means that I'm not completely sure how the shebang works.

Old links redirect to nonexistent repos

Not a huge deal, but some people (like me) who may have saved or shared a link to your spec may be surprised to find it was moved.

Visiting http://criticmarkup.com/spec.php
redirects the user to https://github.com/CriticMarkup/spec.php
which doesn't exit.

While visiting http://criticmarkup.com
redirects to https://github.com/CriticMarkup/CriticMarkup-toolkit
which is fine.

I said links and repos (plural) because any link that matches http://criticmarkup.com/:whatever is redirecting to https://github.com/CriticMarkup/:whatever

RFC: CriticMarkup Syntax v0.3a

Critic Markup is intended to provide basic editorial change tracking in plain text files. The syntax is compatible with Markdown, MultiMarkdown and HTML.

The Three Laws

  1. Critic Markup shall be human readable. A human with a simple text editor can easily read and comprehend any text containing Critic Markup
  2. Critic Markup shall be computer readable except where it conflicts with rule 1. Markup syntax should be easily parsed with simple regular expressions to support a wide variety of implementations.
  3. Critic Markup shall be compatible with existing markup syntax for Markdown, MultiMarkdown and HTML except where it conflicts with rules one or two. Many users of plain text write in combinations of Markdown and HTML. Critic Markup should work alongside that syntax.

The Goal

Critic Markup can be used in any writing environment without special applications or tool kits. While we have supplied processors and plugins that are compatible with popular apps, they are not required.

Critic Markup should be readable inline and clearly indicate the intent of the editor and author.

Critic Markup should support change tracking with multiple authors and editors.

The Basic Syntax

There are three types of Critic marks: Addition, Deletion and Comment. Copy editing is enabled by the application of these three basic marks.

Additions

Additions are inserted inline by surrounding the desired text with curly braces and double plus marks as shown:

Lorem ipsum dolor{++ sit++} amet...

A space character and "sit" are to be added at the position of the left (or right) most curly brace. The additions are rendered as <ins> tags in the processed HTML:

Lorem ipsum dolor<ins> sit</ins> amet...

Paragraphs may be inserted in the same manner.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.{++

++}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

To ensure the Markdown processor outputs valid HTML, the <ins> tag encloses a non-breaking space and is followed by two newlines. The result is that both paragraphs render separately. The non-breaking-space gives the tag enough content to render properly, and we assign class=break to allow for custom styling.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.<ins class="break">&nbsp;</ins>

Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

Rules for proper use of the <ins> tag can be found in the HTML 4 spec.

Deletions

Deletions are denoted with a similar syntax. The text to be deleted is surrounded with curly braces and double dashes.

Lorem{-- ipsum--} dolor sit amet...

The word "ipsum" and a space character are marked for deletion in the above example. These deletions are rendered as <del> tags in the processed HTML.

Lorem<del> ipsum</del> dolor sit amet...

Paragraphs may also be deleted.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.{--

--}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

The newlines will be removed by the processor and replaced by an inline <del> tag. Again, the non-breaking-space gives the tag enough content to render properly.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.<del>&nbsp;</del> Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

Rules for proper use of the <del> tag can be found in the HTML 4 spec.

Substitutions

Substitutions combine an insertion and a deletion. The syntax reflects this.

Lorem {--hipsum~>ipsum++} dolor sit amet...

Despite the shortened syntax, substitutions render just like a deletion followed by an insertion.

Lorem <del>hipsum</del><ins>ipsum</ins> dolor sit amet...

Newlines are treated the same as a deletion or insertion, depending on where they're located.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. {--Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.~>

++}Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

After rendering this example, the deletion and insertion are added to the end of the first paragraph and two newlines ensure the proper paragraph break.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla. del>Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.</del><ins class="break">nbsp;</ins>

Praesent sagittis, quam id egestas consequat, nisl orci vehicula libero, quis ultricies nulla magna interdum sem. Maecenas eget orci vitae eros accumsan mollis. Cras mi mi, rutrum id aliquam in, aliquet vitae tellus. Sed neque justo, cursus in commodo eget, facilisis eget nunc. Cras tincidunt auctor varius.

Metadata

Metadata may be added to any change via a set of square brackets prior to the closing brace of the tag.

{++Lorem ipsum dolor sit amet.++[This is a comment]}

{--Lorem ipsum dolor sit amet.--[This is a comment]}

{--Lorem hipsum dolor sit amet.~>Lorem ipsum dolor sit amet.++[This is a comment]}

The contents of a metadata field render as <span class="critic metadata"> after the relevant change. In the case of substitutions, the <span> will be attached to the <ins> element.

<ins>Lorem ipsum dolor sit amet.<span class="critic metadata">This is a comment</span></ins>

<del>Lorem ipsum dolor sit amet.<span class="critic metadata">This is a comment</span></del>

<del>Lorem hipsum dolor sit amet.</del><ins>Lorem ipsum dolor sit amet.<span class="critic metadata">This is a comment</span></ins>

<mark>Lorem ipsum dolor sit amet.<span class="critic metadata">This is a comment</span></mark>

Metadata may be used however you like, whether as explanations for the changes, timestamps or more. The <span> element is for inline content only, so all newlines will be stripped.

Rules for proper use of the <span> element can be found in the HTML 4 spec.

Comments

Comments may be added as required by an editor or author, and may be anchored to existing text or stand on their own.

For an anchored comment, the text to be referenced is surrounded by curly braces and double tilde (a.k.a twiddle) as shown:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {~~Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.~~[confusing]} Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

Comments are rendered as <mark> tags in the processed HTML.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. <mark>Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.<span class="critic metadata">confusing</span></mark> Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

Unanchored comments can be placed without reference to any existing text, and don't require the tilde characters. The CriticMarkup processor will insert a non-breaking space to ensure proper rendering.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.{[confusing]} Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

Unanchored comments render in the same way:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.<mark>&nbsp;<span class="critic metadata">confusing</span></mark> Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

Rules for proper use of the <mark> tag can be found in the HTML 5 spec.

Putting it all together

When used in combination the marks can indicate more complex changes.

{--Eighty-seven~>Four score and seven++[Has greater weight]} years ago our fathers brought forth on this continent a new {--state~>nation++[More inclusive]}, conceived in liberty, and dedicated to the proposition that all men {--and women--[Not THAT inclusive - we'll tackle this issue after the war]} are created equal.{++

++}Now we are engaged in a great {--struggle~>civil war++[Let's call this what it is]}, testing whether that nation, or any nation, so {--concieved~>conceived++[I before E except after C]} and so dedicated, can long endure. We are met on a great battle-field of that war. We have come to {--consecrate~>dedicate++[They consecrated it, we can't do much more than dedicate now]} a portion of that field, as {--an ultimate~>a final++[simpler,clearer]} resting place for those who here gave their lives {~~that that~~[OK, but avoid if possible]} nation might live. It is {--all together~>altogether++[NB: Stop writing on trains]} fitting and proper that we should do this.

The above paragraphs should render to HTML in the following manner.

<del>Eighty-seven</del><ins>Four score and seven<span class="critic metadata">Has greater weight</span></ins> years ago our fathers brought forth on this continent a new <del>state</del><ins>nation<span class="critic metadata">More inclusive</span></ins>, conceived in liberty, and dedicated to the proposition that all men <del>and women<span class="critic metadata">Not THAT inclusive - we'll tackle this issue after the war</span></del> are created equal.<ins>&nbsp;</ins>

Now we are engaged in a great <del>struggle</del><ins>civil war<span class="critic metadata">Let's call this what it is</span></ins>, testing whether that nation, or any nation, so <del>concieved</del><ins>conceived<span class="critic metadata">I before E except after C</span></ins> and so dedicated, can long endure. We are met on a great battle-field of that war. We have come to <del>consecrate</del><ins>dedicate<span class="critic metadata">They consecrated it, we can't do much more than dedicate now</span></ins> a portion of that field, as <del>an ultimate</del><ins>a final<span class="critic metadata">simpler, clearer</span></ins> resting place for those who here gave their lives <mark>that that<span class="critic metadata">OK, but avoid if possible</span></mark> nation might live. It is <del>all together</del><ins>altogether<span class="critic metadata">NB: Stop writing on trains</span></ins> fitting and proper that we should do this.

Caveats

There are a few limitations to consider when using CriticMarkup.

Avoid Newlines in Comments

As mentioned earlier, you should avoid newlines in comments they'll be stripped in the final HTML.

Wrap Markdown Tags Completely

While it may support incomplete Markdown tags in the future, the CriticMarkup processor currently chokes on them. Therefore, you should strive to avoid this:

I really love *italic {++fonts*~>font-styles*++}.

Instead, you should wrap the asterisks completely:

I really love {--*italic fonts*~>*italic font-styles*++}.

No highlight for critic syntax in "Markdown + Critic"

I know there was a commit a few months ago about "fixing highlight syntax", but I was not using Sublime Text 3 at this time so I cannot say if it was working at this time. Here, critic syntax is not highlighted with the Markdown + Critic language, whatever the color scheme used (Critic or Monokai Soda + Critic).

Critic syntax highlight does appear when I select the Critic language from the bottom right list, but this language lacks all Markdown highlights and is very simple, and not as good as Markdown + Critic (at least in my opinion).

What should I do to enable critic syntax highlights with Markdown + Critic language? I have checked the .tmLanguage files, and the content of Critic.tmLanguage is included in Markdown + Critic.tmLanguage, just it seems to be ineffective.

Thanks for your help.

CriticMarkup conflicts with lists

The following snipped does not correctly create bullet lists:

Some text:
{++

* new entry 1;
* new entry 2;
* new entry 3.

++}{--

* old entry 1;
* old entry 2.

--}

The markup generated by CriticMarkup's processor in this case looks like:

Some text:
<ins> * new entry 1; * new entry 2; * new entry 3. </ins><del>
* old entry 1;
* old entry 2.
</del>

Is this a bug, or should CriticMarkup only be used inside the bullet? How then remove an entire section that has bullets inside of it?

Filip.

Highlights Example

In the specification under the highlights section the comment has class="critic metadata". Should this not be class="critic comment"?

No emacs support

Adding and emacs mode like this be cool:

File Edit Options Buffers Tools Emacs-Lisp Help
(require 'generic-x) ;; we need this

(define-generic-mode
'critic-mode
nil
nil
'(("{--.--}" . 'font-lock-warning-face)
("{~~.
~~}" . 'font-lock-constant-face)
("{{.}}" . 'font-lock-keyword-face)
("{>>.
<<}" . 'font-lock-function-name-face)
("{++.*++}" . 'font-lock-type-face)
)
nil
nil
"A mode for critic markup"
)

Is there a diff generator?

.. as in: two files go in, one CriticMarkup "annotated" file comes out.

This would be very useful for an alternative diff view on GitHub, GitLab and the like.

State?

Just wondering if there's a maintainer still around. I'm happy to participate as I can. I see there are issues and PRs laying around. I'm looking at creating a Word plugin for exporting/importing critic markup. But if there's nobody around to update the docs, or the standard has just been abandoned (or superseded?), then I'll look elsewhere. Thanks!

Add support for CriticMarkup in ACE editor

Seeing that this toolkit supports various editors, I would love to see CriticMarkup take a crack at support in the ACE editor (https://github.com/ajaxorg/ace/)

The import page:

https://github.com/ajaxorg/ace/wiki/Importing-.tmtheme-and-.tmlanguage-Files-into-Ace

seems to suggest that it is a straight forward process, given the textmate support.

To me, it is unclear if this could be a "plugin" to existing markdown styling, or if the addition of a .critic file is more appropriate.

Anyway, thanks for your consideration.

Elliott

[Proposal] Extensions to the Critic Markup standard

Hello, I am in the process of developing a CriticMarkup renderer and editor plugin for Obsidian, a Markdown notetaking tool -- the plugin itself can be found here.

During development, users have brought up that they would like to have support for collaborative workflows, by having notions of authorship, completedness, ..., and comment replies using the CriticMarkup syntax.

This, however, is not possible with the syntax detailed within this repository, and would instead require additions to the specification itself, both on a structural and syntatic level.

Below is a proposal for potential extensions I've settled on, after exploring the different possibilities, and some discussion with end users of the plugin. These extensions would make the CriticMarkup syntax functionally on par with the suggestion systems found in Google Docs and Word, and would allow for better interoperability between rich-text formats (related: jgm/pandoc#2873)

Any critiques, comments, ideas, suggestions would be very much appreciated.

EDIT 1: Fix typo's and improved language, changed metadata 'colour' field to 'color', notes on backwards compatibility with previous versions of the standard
EDIT 2: Add links to related issues from this repository related to the design of the extensions and issues it attempts to address, small note about multimarkdown compatibility w.r.t. the metadata separator
EDIT 3: Metadata is now stored in JSON for more reliably parsing, the plugin has now been updated to support the processing of metadata and rendering of adjacent comments as replies


Note

Some nomenclature: {** **} will be used throughout this issue as a shorthand to indicate any Critic marking (i.e. {++ ++}, {-- --}, {~~ ~> ~~}, {>> <<}, {== ==})

Note

The extensions below have been designed with backwards compatibility in mind, the extended markup will still render properly in editors that do not support these extensions

Replies

Concept

For enabling collaborative editing with other people, the user would want to be able to reply to comments and suggestions made within the program.

This solution addresses points brought up in #35.

Proposal

Any comments directly adjacent to suggestions and comments, will be considered as 'replies' to said suggestion or comment.
In general, the structure would look something like:

{** SUGGESTION **}{>> REPLY <<}

Some examples:

This is some {++added++}{>>reply 1<<} text
Lorem ipsum {>>a comment<<}{>>reply 1<<}{>>reply 2<<}
Some words being {--removed--}{>>reply 1<<}{++added++}{>>reply 1<<}

Important

Any whitespaces between the brackets (i.e. {>>a comment<<} {>>reply 1<<}), will result in the two markings to be considered as separate entities again.

Note

This behaviour is modelled after the {==highlight==}{>>comment<<} structure. With these extensions, this too can be extended as: {==highlight==}{>>comment<<}{>>reply 1<<}.

EDIT: According to #34, this behaviour was planned from the start, though it does not seem to be codified yet. There is no mention either of how replies would work.


Custom Metadata

Concept

The markup itself only specifies information on what type of marking should be applied. However, the user might want to be able to add more information about each individual marking, similar to how YAML frontmatter functions in markdown documents.

This metadata for comments and suggestions can in turn be used to denote the following:

  • Author: e-mail, unique identifier, name, ... for the person who created the comment and suggestion
  • Timestamp: UNIX timestamp for when the suggestion/comment was made
  • Completedness: A boolean value indicating whether a suggestion/comment has been accepted
  • ...

Editors may use this metadata to display the suggestion/comment in a particular way, allow filtering, additional processing, etc.

This solution addresses points brought up in #17.

Proposal

At the start of each marking's contents, a JSON object containing arbitrary information may be added for simple and cross-platform parsing.
Specifically, this means that when adding a separator (@@ chosen for this particular example) between the metadata and the contents, the editor can parse all the contents before as metadata:

{** METADATA @@ CONTENTS **}

And a specific example of the metadata:

{++{"type1":"abcdefg", "type2":1234.56, "type3":[1, 2, 3]} @@ an addition with metadata++}

Important

If the editor supports it, the metadata should be hidden to the user by default. This reduces the amount of noise within the text, and prevents malformation of the metadata due to accidental edits

Warning

A suitable notation is required for the metadata separator. This should be a string of characters that is:

  • easy to type on a variety of keyboard layouts (symbols like é, ¤, ... only exist in a small subset of keyboards or require multiple keypresses to type)
  • does not conflict with existing markdown syntax (i.e.: **, $$, ...)
  • is not something the user would often type (&&, <>, ...)

For the moment, @@ seems to be a reasonably good separator string that fits above criteria, though this has not been tested rigorously yet. However, it does not seem to conflict with any of the existing MultiMarkdown syntax


In addition, I would also like to propose some basic metadata types, such that these markings are interoperable between editors:

  • author:"Fevol" (string, denotes author of marking)
  • time:1695214491 (UNIX timestamp, when the marking was made)
  • done:true (boolean, whether the marking is considered completed)
  • color:"2F81F7" (hex code, for highlights specifically: which colour the highlight should have)
  • style:"my-custom-class" (string, additional CSS class that is applied to the marking)

If the names of these metadata fields are deemed to be too long, a shorthand notation could be used instead for some of the most important fields:

{>>{"author":"Fevol","time":1695214491}@@comment<<}
{>>{"a":"Fevol","t":1695214491}@@comment<<}

Proposal for Referenced Comments

Use case

Primarily to accommodate comments from different users when soliciting feedback from multiple people at the same time.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.==}{>>[1,2,3,4,5]<<} Mauris massa sem, tempor sed cursus et, semper
tincidunt lacus.

<!-- At the end of markdown document -->
{[1]}: @gsw This is the first comment.
{[2]}: @abc Another comment.
{[3]}: @xyz Yet another comment.
{[4]}: Fourth comment.
{[5]}: Last comment.

Pros

  1. Terseness

Less visual noise in case of multi-user comment situation.

Compare this

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.==}{>>@gsw This is the first comment.<<}{>>@abc Another comment.<<}
{>>@xyz Yet another comment.<<}{>>Fourth comment.<<}{>>Last comment.<<}
Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

to this

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.==}{>>[1,2,3,4,5]<<} Mauris massa sem, tempor sed cursus et, semper
tincidunt lacus.

{[1]}: @gsw This is the first comment.
{[2]}: @abc Another comment.
{[3]}: @xyz Yet another comment.
{[4]}: Fourth comment.
{[5]}: Last comment.

Cons

  1. Visual Decontextualization

    User has to scroll down to see the comment.

    Possible solution: Good tooling support in the editor can mitigate the situation. In markdown or HTML editors, hovering over highlighted section can display the associated comments in a floating frame. More sophisticated tools might allow in-frame editing of the comment as well.

installing and adding a comment causes an error

I installed via BRAT and added a comment ({>>test<<}) to an existing note. When nothing seemed to change I opened dev tools and saw this error:

image

Any other config or incantations I need to do to get it working?

Doesn't work with cyrillic texts

The current version doesn't work with cyrillic texts. It gives a Unicode error.

More specifically:

  • with markdown
Unexpected Error:  <type 'exceptions.UnicodeDecodeError'>
Traceback (most recent call last):
  File "criticParser_CLI.py", line 348, in <module>
    h = markdown.markdown(h, extensions=['extra', 'codehilite', 'meta'])
  File "/usr/lib/python2.7/dist-packages/markdown/__init__.py", line 396, in markdown
    return md.convert(text)
  File "/usr/lib/python2.7/dist-packages/markdown/__init__.py", line 266, in convert
    source = unicode(source)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xd0 in position 0: ordinal not in range(128). -- Note: Markdown only accepts unicode input!
  • with markdown2
Using the Markdown2 module for processing
/path-to-program/CriticMarkup-toolkit/CLI/1.html
Unexpected Error:  <type 'exceptions.UnicodeEncodeError'>
Traceback (most recent call last):
  File "criticParser_CLI.py", line 371, in <module>
    filesource.write(h)
UnicodeEncodeError: 'ascii' codec can't encode characters in position 3667-3670: ordinal not in range(128)

I found a workaround after some googling. It may not be very elegant, but it does the job. It applies to the command line tool criticParser_CLI.py. I am not a programmer, so maybe there is a better way to do it.

First, this section

#!/usr/bin/env python

import codecs
import sys
import os
import re
import argparse
import subprocess

should become

#!/usr/bin/env python

import codecs
import sys

reload(sys)
sys.setdefaultencoding('utf8')

import os
import re
import argparse
import subprocess

Then this section

jq = '''<!DOCTYPE html>
<html>
<head><script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<title>Critic Markup Output</title>'''

head = '''<!DOCTYPE html>
<html>
<head>
<title>Critic Markup Output</title>'''

Should become

jq = '''<!DOCTYPE html>
<html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<head><script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<title>Critic Markup Output</title>'''

head = '''<!DOCTYPE html>
<html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<head>
<title>Critic Markup Output</title>'''

Comments with Additions, Deletions, and Substitutions

Can comments be used with Additions, Deletions and Substitutions or only with Highlights? Are the examples below valid uses of CriticMarkup?

Lorem ipsum dolor{++ sit++}{>>The reason I added this<<} amet...
Lorem{‐‐ ipsum‐‐}{>>The reason I deleted this<<} dolor sit amet…
Lorem {~~hipsum~>ipsum~~}{>>The reason I changed this<<} dolor sit amet…

Thanks!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.