Comments

[monsieurhannes]

This post summarizes the current state of the discussion in this ticket and the plans to implement (original report at the bottom):

Open tasks

• [ ] @max-nextcloud is looking into implementing html comment support as a technical baseline
• [ ] @max-nextcloud will align with @nimishavijay on open design questions

Summary

Initial sketch with available comments indicated in text and a button to create a new comment on the current active section.

Allow comments on block elements (paragraphs, headings, quotes, ...):

• Allow create comments.
• Display existing comments.
• Allow removing ones own comments.

Motivation

Comments are useful in many situation. They allow adding information that directly relates to parts of the document without adding it directly to the document content.

Comments can be particularly helpful when drafting documents and during a review process.

Comments on block elements attach the comment to the relevant section on the document while avoiding the complexity of in line comments such as overlapping comment ranges.

Specification

Comments can be added to all block elements:

• Paragraphs
• Headings
• Quotes
• Callouts
• Code blocks
• Images
• Link Previews
• Tables
• all types of Lists

Alternatives

Inline comments

This draft mainly came out of the discussion of in line comments in #185. In line comments allow commenting on a precise range of text, which is hard to represent in markdown.

Footnotes

While footnotes could also be used to represent comments, they serve a different purpose. #2142 discusses footnotes.

User Interface Elements

• Button to add a comment to a block element
• Indicator that there are comments on an element
• List of comments on an element
• Button to remove ones own comment

Implementation

• Comments will be serialized in markdown.
• They will be implemented using the standard way in text:
  • Markdown-it extension parses them to html.
  • Tiptap nodes represent them in the editor.
  • toMarkdown function to serialize them.
• Comments can contain multiple block nodes themselves.

Out of scope for now (but maybe future)

• Edit my own comments.
• Reply to other comments.
• Suggest changes.
• Integrate with nextcloud comments system.
• Integrate with document chat (talk).
• Notify about comments.

Initial report

Is your feature request related to a problem? Please describe. No, but it would be great to have the ability to comment text directly in the line.

Describe the solution you'd like Similar to gdocs and word, marking a text and writing a comment on the side.

Describe alternatives you've considered Linking a specific part of the text in the comment section in the panel on the right could also be a solution, maybe for the start, being able to link headlines #H2

Just an idea, might be too ambitious, but maybe sth. for the backlogs.

[jancborchardt]

@monsieurhannes yes, this would be very useful. Could you show screenshots from how Google Docs, Word and others do it as examples?

[juliusknorr]

Besides the frontend we of course need to think of a proper way how we represent the comments in markdown.

[tiotrom]

This would be such an awesome thing

[juliusknorr]

Please use the Github Reactions feature instead of commenting that also need a specific feature. That way we can see your support without notifying all users subscribed to a given issue.

[joshp23]

Markdown footnotes would be a possibility to represent in MD

[jtoloe]

HackMD has this functionality. See https://hackmd.io/s/how-to-use-comments for examples. I do not think that the comments are stored in the markdown file.

[juliusknorr]

The issue with not storing it in the markdown file would be that we then loose the comments as soon as someone changes the file from outside (e.g. with a editor synced by the desktop client)

[juliusknorr]

Footnotes would be a possible way, but they limit comments to one cursor position in the text rather than having the possibility to mark a range of text and comment on that.

[jnnkB]

Maybe Critic Markup would be an option: http://criticmarkup.com/users-guide.php

[monsieurhannes]

Any development on this front? It seems like it gets mentioned more often recently. I guess Text is in a bit of competition with the big office suites which provide that feature already and maybe it's an overkill for Text. But at the same time Text is much more lightweight and accessible on all platforms. I'd be happy to help in any way - more in the UI than the programming part. 😆

[juliusknorr]

This would still be a nice to have feature, but is currently blocked by a proper approach to persist comments in markdown files, without impacting readability too much.

The only feasible option seems to be to use footnotes for this, but then you could only comment on cursor positions and not comment on a selected area.

[susnux]

I think range based comments are only possible with custom syntax. I would not use footnotes for this, as they might be added as a stand-alone feature in the future.

When talking about inline comments, how about HTML comment blocks? They are allowed as per markdown spec.

# Header
some text <!-- some comment --> text

But when talking about range comments, then I could not even find one already used syntax for that. So to stick with current style of markdown syntax this could be one option:

# Header
?[some text](with comment)

[badrihippo]

Comments as per CriticMarkup

Since many people have been mentioning CriticMarkup in this and duplicate threads, here's how it looks in practice.

Comment (sticks to a specific point in the text {>> like this <<}):

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

Highlight (highlights {==a specific passage==}{>>like this<<}):

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.

To me this looks like an elegant solution, which will preserve the comments even when edited with an external editor.

One caveat is that the CriticMarkup parser doesn't currently support broken markdown tags: a highlight has to include both the opening and closing of the tag to work properly. They hope to fix this in the future and allow partial tags to be highlighted too.

First steps

I think even the first option (just inline comments at a specific point in the text, not necessarily tied to a specific highlighted passed) will be a great help for collaborative editing. Given that it also looks easier to implement, how about we start with that, and put highlights as a feature later down the line if needed?

Linking to the user

What remains to be standardised is how to link the comment to a NextCloud account. The simplest way is to prepend the commenter's name before adding the actual comment, like this:

NextCloud has a great collaborative editor {>>>[email protected]: and now we have comments!<<<}

If we're only saving these comments directly to the Markdown file, there is obviously no way to verify the identity: anyone can type my username into the text file to make it appear as if I wrote the comment. To prevent this, perhaps we could implement this in multiple stages:

1. Start with identity-less comments: have them simply show up as speech bubbles without specifying who wrote the comment.
2. Start specifying the comment author with the above syntax, but also save the comment information externally so that it can be cross-checked. If the comment doesn't match, we could either remove it (destructive) or display a warning saying that the identity of the commenter could not be verified. (I prefer the second option)
3. (Not sure how feasible this is) scan the Markdown file everytime it is edited, so that if the user has manually inserted a comment with the given syntax, and under their username, then it gets added to the database as "their" comment. This goes hand-in-hand with the "could not be verified" comment handling behaviour

---

That's as far as I've thought so far—is there anything I missed, any concerns, or anything that could be done better? (Tagging @juliushaertl for what you think of the markdown mechanics, and if you have any concerns about using CriticMarkup instead of vanilla markdown or whatever we use right now).

[mejo-]

Thanks a lot @badrihippo for the thorough reply. I like your approach. CriticMarkup doesn't look very active, but the syntax seems sensible nevertheless.

And there is a markdown-it plugin for CriticMarkup (that is very old but then it's only a few lines of code anyway). We would need that for serializing the markdown into HTML.

There's also vimtaai/critic-markup which might help as code inspiration (e.g. for parsing regexes).

[pierreozoux]

This discussion looks a lot like this one: https://github.com/hedgedoc/hedgedoc/issues/2879

I would love that nextcloud/text and hedgedoc agree on the same solution so that I could use hedgedoc and other people text, and this would be compatible :)

It is probably utopia, but this is the way I feel, a common internal standard to collaborate between different tools, and different UI according to preferences.

Sorry to open the scope of the discussion, don't hesitate to label it as offtopic.

Have a nice day!

[codedust]

To get a better feeling for this solution, here are some screenshots of popular text editors, as @jancborchardt suggested:

Google Docs

LibreOffice Text

HackMD

see https://hackmd.io/s/how-to-use-comments

OnlyOffice