Comments

Encouraging a transparent curation process is one of the goals of the CIViC knowledgebase. To that end, it is possible (and encouraged) to record relevant curation details, motivations, and questions for other curators or editors in the form of comments on primary CIViC entities.

Each CIViC entity capable of accepting suggested changes also includes a comment thread. These comments can be viewed by clicking on an entity’s ‘Revisions’ tab, then hovering over the text bubble next to the specific revision..

Initial Comments

The forms for adding new evidence or assertions include a comment field, so that a curator can describe why the record should be included in CIViC. This comment will be displayed at the top of the comment thread. Note that this comment is not required so many records will not include an initial comment.

Creating and Previewing Comments

To create a comment, ensure you are logged in, navigate to the entity you wish to comment upon, click the entity’s Comment tab.

Above the comment area are two buttons, ‘Write’ and ‘Preview’, with Write being selected by default. Click Preview to see how your message will appear with all the formatting and links applied.

When you are satisfied with your comment, press ‘Add Comment’, and your message will be immediately appended to the entity’s comment thread.

Deleting Comments

You may delete your own comments by clicking the ‘Delete’ button at the bottom-right corner of its comments box. It is not possible to undo the deletion of a comment.

Comment Formatting

Emphasis, styling, images and links may be added to comments using a subset of Markdown syntax:

Effect

Syntax

Headers

 

# This is an <h1> tag

## This is an <h2> tag

###### This is an <h6> tag

Emphasis

 

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

*Italics and boldface **can be** combined*

Lists

Ordered 

* Item 1
* Item 2
* Item 2a
* Item 2b
* Item 3
Unordered 
1. Item 1
2. Item 2
3. Item 3
* Item 3a
* Item 3b

Images

 

![this cool diagram](http://site.com/images/cool.png)

Format: ![Alt Text](url)

Blockquotes

 

As Charles Darwin said:
>It is not the strongest
>of the species that survive,
>nor the most intelligent,
>but the one most responsive to change.

Inline code

I think you should use an `<addr>` element here instead.

Comment Macros

Using macros, you may easily insert links to CIViC entities, mention and notify users.

@username mention macro

‘@’ followed by a user’s display name will be displayed as a link to the user’s profile page, and generate a notification to the mentioned user. This is useful for calling a user’s attention to a particular comment.

Type ‘@’, and the first couple letters of a user’s name, and CIViC will show you a dropdown menu of users with matching display names. Hit enter to insert an user mention link, which will display in the rendered comment as a link to the user’s profile page, and generate a notification to the mentioned user.

@admins and @editors mention macros

Adding ‘@admin’ or ‘@editor’ to your message will generate a mention notification for all users with the admin or editor role, respectively:

Hey @admins, could I please get someone to approve this new evidence item?

#ENTITY link macro

‘#’ followed by an entity type abbreviation, and an entity ID will be displayed as a link to that entity’s summary view:

For example with #V123 we see the opposite effect.

Use the following syntax for the target entity:

#MP123

Molecular Profile link

#V123

Variant link

#G123

Gene link

#E123

Evidence Item link

#VG123

Variant Group link

#R123

Revision link

hash (#) entity link suggestions macro

CIViC can inline substring searching for entity link macros. Enter an entity type as above, plus a colon, e.g. #V:. Then begin typing the name of the entity, or a substring. CIViC will display a dropdown of entities that contain matching text in their names. Select an entity, and the correct macro link with the ID will be entered into the comment.