Commenting¶

On CDS, reviews are represented as a "request" to include a record in a given community. These requests come with an advanced conversation feature, allowing everyone involved to discuss the submission in detail directly in CDS.

This page showcases some of these features and explains how to use them.

Writing a comment¶

The text editor at the bottom of the page allows you to create a new comment. This is a feature-rich editor with support for many advanced types of content. The majority of content is edited in a "what you see is what you get" manner, where the contents of the editor clearly reflect how the comment will look once it is submitted.

LaTeX equations¶

You can surround LaTeX content with one of two 'delimiters' to ensure it's rendered as a mathematical equation:

$ for equations inline with text
$$ for full-width 'block' equations

The content is not rendered immediately in the editor. However, you can preview it before submitting by clicking the "Preview math equations" button:

This will show the full comment in a dialog box, exactly as it will be shown to readers. It will not save or submit the comment; it's just a temporary preview. Once the comment is submitted, the equations will be shown fully-rendered.

All math-mode TeX/LaTeX features supported by the web-based MathJax rendering engine can be used. Keep in mind that environments are not supported. You may also encounter some other differences to normal TeX.

Quoting other comments¶

When writing a reply to a comment, you can include a "quote" of either all or part of the text. You can also include multiple separate quotes if you want to reply to different sections of the text individually.

To quote the full comment, simply click the action menu (the 3 horizontal dots) on the comment you want to quote, and select "Quote reply":

Alternatively, to quote a part of a comment, highlight the text you wish to quote and click "Quote reply" in the popover that appears:

Auto-saved drafts¶

CDS saves your new comment draft automatically as you type. The draft is saved locally in your browser and is not synchronised to your account. This means your draft will not show up on a different device or browser. It can also be lost if you're using a browser in a temporary session on a kiosk computer or if you clear your browser's storage.

The comment draft is also not deleted when you log out of your account, and will show up once you log in again. It isn't user-specific, so any other user on the same computer and browser will see your draft. If you're using a shared computer, make sure to delete drafts or clear your browser storage after you are done. In-progress edits to existing comments are not saved.

Warning

Don't rely on auto-saving for storing drafts of long comments over an extended period of time. Browser storage can be volatile, and your draft can be lost at any time. This feature is solely intended to help recover recent drafts, e.g. in the case of accidentally reloading the page.

Replying to a comment¶

To better preserve context, we recommend replying directly to comments through the "Write a reply" box instead of simply writing a new comment at the bottom of the page. This helps group related information together and makes the review more readable.

To write a reply, simply click the "Write a reply" box. When clicked, the full rich text editor will appear, and you can use all the same editing tools to compose the reply.

When dealing with requests that have a particularly large number of comments, it can be useful to share a link to a specific comment rather than the entire request. This way, the recipient will always be taken to the exact comment you intended and that it will be clearly highlighted to them.

To copy a link to a comment, click the action menu (the 3 horizontal dots) and select "Copy link":

The link will be copied to your clipboard. Unauthenticated users might not be able to open the link; it's important that the recipient has access to the request. For example, they must be a member of the community, the submitter of the record, or manually added to the request as a reviewer. Copying a link does not change the access restrictions of the request.

Editing or deleting a comment¶

To edit a comment or reply, simply click the action menu (the 3 horizontal dots) and select "Edit". Make your changes, and click the "Save" button. Your changes will be applied immediately, and the comment will be marked with a small "Edited" label visible to all users.

To delete a comment or reply, select "Delete" from the action menu, then confirm your action by clicking "Delete" again in the dialog. The comment will be deleted immediately, and replaced with a "stub". Existing replies will not be deleted and new replies can still be added. A link to the stub can still be copied, and existing links to the deleted comment will continue to work.

Warning

You cannot restore the original comment. The content is deleted permanently.

Locking the conversation¶

In some cases, you may wish to lock the conversation after a certain period of the review is concluded. When a conversation is locked or unlocked, an event appears in the conversation timeline for all viewers:

New comments cannot be created by anyone, including community curators
Existing comments cannot be edited
Existing comments can still be deleted

Replying to existing comments is still allowed (replies can be created and deleted but not edited)

Community curators (and above) can unlock the conversation at any time.

To lock a conversation, click the "Lock conversation" button in the right-hand sidebar:

To unlock, click the "Unlock conversation" button.

Locking and unlocking create an event visible to all viewers in the conversation timeline: