Comments : syntax

[nokome]

Both stencils and sheets would benefit from comments. Currently comments can be included in stencils (e.g. Cila, HTML) but there is no UI representation.

The current model for comments is to group them by their target (e.g. a particular paragraph, a particular sheet cell). In stencils the target is specified by a CSS selector (which may need to be added by the UI widget). In sheets a cell identifier e.g. (A1) could be used.

In stencils, comments are represented in HTML as:

<div data-comments="#target-of-comment">
    <div data-comment="@nokome at 2015-06-08T20:34:45">
        Not sure this part is worded right. Any thoughts?
    </div>
    <div data-comment="@matt at 2015-06-08T20:35:52">
        Get over it, it's fine!
    </div>
</div>

and in Cila as:

comments #target-of-comment
    comment @nokome at 2015-06-08T20:34:45
        Not sure this part is worded right. Any thoughts?
    comment @matt at 2015-06-08T20:35:52
        Get over it, it's fine!

Note that the meta data (target, author, datetime) is optional and usually added by the UI. If you were authoring in Cila and just wanted to write a comment that applied to the following element you could just start a line with comment e.g.

comment Delete this heading?
h1 Silly heading

It may be useful to create shorthand for this e.g. using double slashes

// Delete this heading?
h1 Silly heading

• Add visual user interface for comments. Should be consistent between stencils and sheets and probably inspired by what we're used to seeing in Google Docs, Medium etc.
• Add comments to the sheet file format Sheet file format #175 (just like the block of Cila? for consistency - see Sheet file format #175 (comment))
• Add Cila shorthand for comments

[nokome]

hi @tracykteal, thanks for reminding me about the need for comments - and since you reminded me, comments welcome! 😄