Home Download Buy Blog Forum Support

Comments - not inline

Comments - not inline

Postby agibsonsw on Mon May 07, 2012 8:23 pm

I've developed this feature, described next, and I'm quite happy for anyone to use it - although I'm not sure how much interest there might be in it (other than my own :D )

GitHub [There are a number of images, but these are not needed - they are just screenshots during development.]

I was encouraged by someone stating that they were restricted as to the number, and content, of comments that they can create. I assumed that they might be adding comments, but then have to go back through the file and ensure that they were deleted, before publishing their work.

So my feature creates comments that are attached to a word in the view, but do not appear within the view. The comments are added, viewed, and managed using an input-panel. The comments can be highlighted in the view, and jumped to using a quick-panel. They can also be saved with the view (as a new file, just adding 'cmts' to the current file-name). I suppose it could be considered a TO-DO feature, or 'Bookmarks with notes' 8-)

My key-bindings:

Code: Select all
   { "keys": ["ctrl+alt+k"], "command": "comment_html" },
   { "keys": ["ctrl+alt+q"], "command": "quick_comments" },
   { "keys": ["ctrl+alt+m"], "command": "print_html", "args": { "numbers": false } },
   { "keys": ["ctrl+alt+n"], "command": "print_html", "args": { "numbers": true } },
   { "keys": ["ctrl+s"], "command": "save_with_comments" }

CommentHtml is the main command, that produces the input panel. QuickComments shows the comments in a quick-panel (for jumping to).
PrintHtml is a version of the ExportHtml plug-in that will create an HTML document for the view, with any comments displaying as tooltips.

SaveWithComments will save any comments, run the normal save command, then reload the comments. (Of course, you might choose a different key-binding.)

If you close the file you should first type 'SAVE' in the comments-input-panel. Then, when you re-open the file, type 'LOAD' (in the input/comments-panel) to re-load the saved comments. [It would be possible to add extra code to have this happen automatically.]
To delete a comment, click into it (or highlight an area including it/them) and type 'DELETE' in the comments-panel. DO NOT just delete the area that includes the comment(s).

It does not attempt to (fully) track the comments. However, if you issue the command 'HIGHLIGHT' the comments will be highlighted, with any that are no longer under the same word appearing in a different colour. You can then 'PUSH' or 'PULL' them to different positions. If comments are highlighted then the command 'FOLLOW' will attempt to correct any comments that are in the wrong position.

Anyway, there are a lot more commands, with more information in my GitHub-Wiki section.

I'm on Windows and haven't tested on other oses - but it should work :lol:
Attachments
CommentsJump.png
The quick panel to jump to comments
CommentsJump.png (26.32 KiB) Viewed 1676 times
CommentsErr.png
Comments are highlighted in the view
CommentsErr.png (25.88 KiB) Viewed 1678 times
"I'm here to save your life. But if I'm going to do that, I'll need total uninanonynymity." Me Myself & Irene.
agibsonsw
 
Posts: 901
Joined: Fri Jan 27, 2012 9:11 pm

Re: Comments - not inline

Postby agibsonsw on Mon May 07, 2012 10:11 pm

I've added an rtf to my Repo that gives the fullest description yet of how this works, and its feature-set. I can't attach it, so the text of the rtf is reproduced below.

I will tidy up my repo - when I work out how to delete the images/screenshots :?:

PrintHtmlFullest.rtf

Copy the files to a folder named PrintHtml in your Packages area. The images are not needed though; they are just screenshots during development.

This Sublime Text 2 feature allows the creation, and management, of comments within a view. The comments do not appear in-line within the view. An HTML document can also be created (with or without line numbers) with any comments being displayed as tooltips on hover. Key Bindings:

Code: Select all
   { "keys": ["ctrl+alt+k"], "command": "comment_html" },
   { "keys": ["ctrl+alt+q"], "command": "quick_comments" },
   { "keys": ["ctrl+alt+m"], "command": "print_html", "args": { "numbers": false } },
   { "keys": ["ctrl+alt+n"], "command": "print_html", "args": { "numbers": true } },
   { "keys": ["ctrl+s"], "command": "save_with_comments" }

CommentHtml is the main command that produces an input-panel. Comments can be added here and they are attached to the current word in the view. (It needs to be a mainly alphabetic word.) If you already on a commented word, then the comment text will appear in the input-panel. It can be edited here, or just press Enter (in the input-panel) to move to the next comment - it will also then cycle to comments from the beginning of the file.

QuickComments shows a quick-panel listing the comments; click one and it will take you to that line, displaying the comment in the status-bar.

PrintHtml will produce an HTML document for the current view, with any comments displaying as tooltips (on hover). The 'numbers' argument will optionally generate line-numbers in the HTML output. You can also select an area within the view and only this area will be output to HTML.

SaveWithComments will save any current comments, save the file, then re-load the comments. (A normal save will not save any existing comments - and will, in fact, delete them.) However, if you want to close the file and wish to keep the comments then: first issue the 'SAVE' command in the comments-input-panel; save the file as normal; close the file; then issue the 'LOAD' command to retrieve the saved comments when you next open the file. [This process could be automated.]

The following commands can be typed in the comments-input-panel:
'SELECT' (or 'SEL', 'SELECT ALL') will select all existing comments. Any that are no longer under their original word, or are beyond the current view-size, will be deleted.
'NEXT' (or 'DOWN', etc.) will select the next comment after the cursor. It will also indicate (with a status-message, and in the Console) whether the comment is on a different word (from its original word), or that the comment is beyond the current view-size.
'PREV' (or 'PREVIOUS') will select the previous comment to the cursor position (see 'NEXT').
'FIRST' or 'LAST' will select the first or last comment in the view. Again, it will indicate if the comment is mis-positioned.
'HIGHLIGHT' (or 'HIGH') will highlight (with an outline) all comments. Any that are mis-positioned will appear in a different colour. Highlighting remembers the word that the comment was previously under, so that it can subsequently be 'PUSH'-ed to a different position.
'REMOVE' will remove the current comment-highlighting.
'FOLLOW' If comments are highlighted, this will attempt to move any mis-positioned comments to their highlighted positions. This relies on their being the same number of comments as highlighted regions. Using this command, it should be possible to highlight the comments, edit your code, then 'FOLLOW' should correct their positions. However, do not delete any code that includes comment(s) - use the 'DELETE' command instead. Like 'HIGHLIGHT', it will indicate where comments are still mis-placed.
'CORRECT' is very similar to 'FOLLOW', but will work even if the comments are not currently highlighted. However, it will not attempt to move comments if they would fall onto a different word - use 'HIGHLIGHT' to achieve this.
'DELETE' (or 'DEL') will delete the comment that is attached to the word under the cursor, or all comments contained within the selected area.
'DELETE ALL' - as it says!
'PUSH' (or 'PUSH DOWN', etc.) will move the comment under the cursor (or comments within the selected area) down to the next occurrence of the comment-word that it was under. If the next word already has a comment attached then it will be skipped.
'PULL UP' or 'PULL DOWN' will pull the next or previous comment to the current cursor position (regardless of the word it was previously attached to). It does not work with a selected area, or multi-select regions.

'RECOVER' will bring back any comments that have gone beyond the current view-size. It will attach them to the first occurrence of their original comment-word (starting from the end of the file/view).
'SAVE' (or 'SAVE COMMENTS') will save the current comments. It creates a file using the current filename and location, with 'cmts' added at the end. It is necessary to use this command (or the SaveWithComments TextCommand) before saving the file itself, otherwise the comments will be lost. If you use this command, you should then save the file and use the 'LOAD' command to re-load the comments.
'LOAD' will re-load saved comments - from a file with the same name, with 'cmts' added to the end. If you have edited the file in the meantime then the comments will probably be mis-positioned: use 'HIGHLIGHT' to help correct this.

An additional feature is that you can double-click a word in the HTML-output to create a new (temporary) comment. This would only be useful if a screenshot is subsequently taken, showing the new comments. And, again in the HTML-output, there is an option to 'tidy spaces'. This will attempt to align sequences of spaces. However, if it doesn't achieve a desired result, it can be un-checked to return the HTML to its original state.

At various points some information is sent to the Console: this might prove helpful.

There are a number of settings that can be used - in particular, an alternative colour-scheme can be specified. However, I haven't checked, or fully implemented these. It was based on facelessuser's version of my original PrintHtml - called ExportHtml (and available via Package Control). I would be happy to check/correct this if anyone makes a request. Similarly, I haven't checked it for oses other than Windows, and it may require a little 'tweaking' for these.

Future: I haven't any immediate plans. However, I'm open to suggestion. In particular, if anyone uses it as a kind-of TODO or task-list, then I could consider options to mark items as 'complete', perhaps colour them differently, and perhaps to produce some kind of task-history document.
"I'm here to save your life. But if I'm going to do that, I'll need total uninanonynymity." Me Myself & Irene.
agibsonsw
 
Posts: 901
Joined: Fri Jan 27, 2012 9:11 pm

Re: Comments - not inline

Postby agibsonsw on Mon May 07, 2012 11:27 pm

Actually, closing a file needn't be so tricky. Use a key-binding to run the SaveWithComments command; close the file; when you re-open it ensure that you issue the 'LOAD' command in the comments-input-panel, to re-load your saved comments.

I should considered renaming this from PrintHtml as the HTML output is perhaps secondary to the comments. Perhaps BookmarkText? Or PushComments?

Andy.
"I'm here to save your life. But if I'm going to do that, I'll need total uninanonynymity." Me Myself & Irene.
agibsonsw
 
Posts: 901
Joined: Fri Jan 27, 2012 9:11 pm

Re: Comments - not inline

Postby agibsonsw on Tue May 08, 2012 11:48 am

I've amended it so that a line number can by typed in the comments-panel and it will 'goto' that line. This seems a convenient, and relevant, option.

A new comments'-command 'CODE' will use the current lines' code as the comment-text. This is convenient if using this as an enhanced bookmarking feature.

I won't keep updating this thread (unless someone expresses an interest). Andy.
"I'm here to save your life. But if I'm going to do that, I'll need total uninanonynymity." Me Myself & Irene.
agibsonsw
 
Posts: 901
Joined: Fri Jan 27, 2012 9:11 pm

Re: Comments - not inline

Postby agibsonsw on Mon May 14, 2012 11:52 pm

Here's a screencast which provides an overview.
"I'm here to save your life. But if I'm going to do that, I'll need total uninanonynymity." Me Myself & Irene.
agibsonsw
 
Posts: 901
Joined: Fri Jan 27, 2012 9:11 pm


Return to Plugin Announcements

Who is online

Users browsing this forum: Yahoo [Bot] and 10 guests