create a way to add comments to documents, especially Jupyter notebooks and LaTeX documents

[timothyclemansinsea]

Google Docs has one, which may be inspiring...

Right now we're writing comments in the documents. I'm thinking this is problematic. http://digitalwriting101.net/content/inserting-comments-on-google-docs/

[williamstein]

Please clarify, since to me this feature request makes little sense. Our documents are plain text, but Google Docs are some internal complicated structure that is presented like a word document (e.g., maybe secretly they are XML). There's no possible meaningful way to add comments into a plain text document without just editing the document, as we're doing, or say adding visible explicit reference codes (that maybe render in a different way). We might add something to enforce some conventions like a toolbar.

[haraldschilly]

what you want is to embed comments into a rich-text document, but with the .md files you are editing the source code of it -- that's where such comments would be stored -- and not the result! what you really need is a rich text document, that has support for comments. xml, latex, html, etc. have this. markdown doesn't have it explicitly, but you can do html comments (since it is converted to html) or hijack url links.

[//]: # (This is a comment)

or

<!---
I am also a comment
-->

[williamstein]

Something like this which would address commented on tex files and grading homework assignments should be very high priority.

[mforbes]

Another extremely useful feature would be a way of annotating PDF or similar files. Google provides rudimentary support for this, but most other platforms do not.

As for commenting on plain-text files: people might also expect something like this for LaTeX files since Overleaf provides this feature. In principle, these can just be inserted in the document as a comment, but people find it useful to add these in a transient way where they can be resolved with the click of a button, and in a way that highlights the existing "code" without interfering. For example, the following comment at the point of use actually breaks the typesetting (since trailing comments suppress space in LaTeX):

Our approach leverages% Please use a different word - the verb is to lever
the strategy of...

An "external" comment system would allow directed comments at the point of need without potentially altering the meaning of the "code". (A plus not found at Overleaf would be if this could connect with the PDF output in the case of LaTeX, but that is probably quite challenging?)

[williamstein]

a way of annotating PDF or similar files.

I have a pretty strong personal interest in this as well, since I have found that annotating PDF's fits my "research workflow" very well (and saves trees), and of course is super useful for student feedback...

CodeMirror has a notion of "marks" for a document, which are hidden locations with extra data. That could be used to store and transparently move annotations around while editing. Of course, they would still get persisted to a (synchronized) file...

[williamstein]

For Jupyter notebooks, we want to be "at least as good" as this: https://www.reviewnb.com/

[williamstein]

See https://github.com/jupytercalpoly/jupyterlab-comments

jupyterlab/jupyterlab#9885

[williamstein]

https://www.w3.org/TR/annotation-model/#selectors

[williamstein]

Pete Blois of Colab/Google says:

often comments are stored outside of the document being commented on- the commenters won't have write access to the document

They also use some general Google docs annotations system -- "For Drive-based notebooks we use https://developers.google.com/drive/api/v3/manage-comments"

[williamstein]

More here: jupyterlab/frontends-team-compass#145

[williamstein]

Note -- the current work but Jupyter upstream does NOT store comments in the ipynb file. I'm encouraging them to define a spec that does do so during the video chat right now, and saying I would lobby for CoCalc respecting/using this, and encouraging colab, vscode, etc., to do so as well.

[e-dervieux]

It would be a really great feature to have a comment system for all text-based documents, and especially LaTeX ones, as the one that Overleaf offers. It is extremely useful for paper reviewing and there is no workaround at the moment:

• using the chat is not practical since there is no way to link a given message to a certain place in the .tex file, and messages quickly get lost in the sands of time.
• using packages like todonotes is very visual / noticeable, but really ugly, and does not allow for long messages, nor does it allow for debate between different users
• using plain LaTeX commentaries - i.e. Some text. % some commentary - do work to some extend, but is not noticeable at all when reviewing a given .tex document

This is the only main and indispensable feature that Overleaf has and Cocalc has not. If someone could look into this, it would be awesome!

[williamstein]

Hi @mranvick thanks for posting this. Coincidentally, I have been thinking a lot lately about adding functionality to tie chat to specific places in a file. I'm thinking of doing it via the TimeTravel information, which provides a pretty sophisticated way to compute where a chunk of highlighted text has moved to as the document evolves, without having to add any special hidden codes to the document itself (I assume Overleaf does something very similar behind the scenes).

[e-dervieux]

@williamstein, if it is of any help - and supposing that you do not have a pro Overleaf account - I think that you may find the videos available on this link interesting for the design of a (possibly upcoming) comment feature: https://www.overleaf.com/learn/how-to/How_to_make_comments_in_an_Overleaf_LaTeX_project

EDIT: I may not be skilled / familiar with the project enough to help you with this, however, I would be glad to help by testing / bugreporting on the new functionality if you do it on a separate branch...