PrintHtmlFullest.rtf

{\rtf1\ansi\ansicpg1252\deff0\deflang2057{\fonttbl{\f0\fnil\fcharset0 Calibri;}}
{\*\generator Msftedit 5.41.21.2510;}\viewkind4\uc1\pard\sa200\sl276\slmult1\lang9\b\f0\fs28 Guidance Notes\par
\b0\fs22 Copy the files to a folder named PrintHtml in your Packages area. The images are not needed though; they are just screenshots during development.\par
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:\par
\pard\sl276\slmult1\tab\{ "keys": ["ctrl+alt+k"], "command": "comment_html" \},\par
\tab\{ "keys": ["ctrl+alt+q"], "command": "quick_comments" \},\par
\tab\{ "keys": ["ctrl+alt+m"], "command": "print_html", "args": \{ "numbers": false \} \},\par
\tab\{ "keys": ["ctrl+alt+n"], "command": "print_html", "args": \{ "numbers": true \} \},\par
\pard\sa200\sl276\slmult1\tab\{ "keys": ["ctrl+s"], "command": "save_with_comments" \}\par
\b CommentHtml \b0 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.\par
\b QuickComments \b0 shows a quick-panel listing the comments; click one and it will take you to that line, displaying the comment in the status-bar.\par
\b PrintHtml \b0 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. If the HTML is unable to be opened in a browser for any reason then it will open in an ST-tab.\par
\b SaveWithComments \b0 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 close the file and wish to keep the comments then: issue the 'SAVE' command in the comments-input-panel; save the file as normal; then issue the 'LOAD' command to retrieve the saved comments. [This process could be automated.]\par
\b Comments' Input-Panel Commands\par
\b0 The following commands can be typed in the comments-input-panel:\par
\pard\sl276\slmult1 '\b SELECT\b0 ' (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.\par
'\b NEXT\b0 ' (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.\par
'\b PREV\b0 ' (or 'PREVIOUS') will select the previous comment to the cursor position (see 'NEXT').\par
'\b FIRST\b0 ' or '\b LAST\b0 ' will select the first or last comment in the view. Again, it will indicate if the comment is mis-positioned.\par
'\b HIGHLIGHT\b0 ' (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.\par
'\b REMOVE\b0 ' will remove the current comment-highlighting.\par
'\b FOLLOW\b0 ' 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.\par
'\b CORRECT\b0 ' is very similar to 'FOLLOW', but will work even if the comments are not currently highlighted. It will move the comments even if the word has changed: use 'HIGHLIGHT' to see which attached words have changed.\par
'\b DELETE\b0 ' (or 'DEL') will delete the comment that is attached to the word under the cursor, or all comments contained within the selected area.\par
'\b DELETE ALL\b0 ' - as it says!\par
'\b PUSH\b0 ' (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.\par
'\b PULL UP\b0 ' or '\b PULL DOWN\b0 ' 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.\par
'\b RECOVER\b0 ' 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).\par
'\b SAVE\b0 ' (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.\par
'\b LOAD\b0 ' 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.\par
\pard\sa200\sl276\slmult1 '\b CODE\b0 ' will use part of the current line's code as the comment-text. This is useful if using this tool as an enhanced bookmarking feature. Can also just use a semi-colon ';' for this command.\par
You can also type a line number in the comments' panel and it will run the \b goto\b0  command to go to that line. This also means that you can type, for example, -10 to go to the 10th line from the end of the view. (It seems sensible, and convenient, to include this feature.)\par
At various points some information is sent to the \b Console\b0 : this might prove helpful.\par
\b Additional HTML Features\par
\b0 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.\par
\b Custom Settings\par
\b0 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 this. 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.\par
Three settings I have enabled:\par
\pard\sl276\slmult1     "use_outline": true, \tab\tab // when highlighting comments - defaults to true\par
    "use_icon": true,\tab\tab // a small icon appearing in the gutter: default true\par
\pard\sa200\sl276\slmult1     "icon_scope": "keyword"\tab // default - comment\par
Setting \b use_outline \b0 to false will display highlighted comments as a block, rather than an outline. Setting \b use_icon \b0 to false will not show a small comment icon in the gutter. It is cute, but it can interfere if you also use, for example, ST's Bookmark feature. You could replace the file 'icon.png' with your own, small, .png icon - just ensure it is called 'icon.png' and remains in the 'PrintHtml' folder. \b icon_scope \b0 will determine the colour for the icon.\par
\b Future Plans\par
\b0 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.\par
}