====== Comment Syntax Plugin ======

---- plugin ----
description: Allow to use source comment syntax to leave edit instructions of the page. Comments are visible only in the source view, not rendered as any page elements.
author     : Satoshi Sahara
email      : sahara.satoshi@gmail.com 
type       : syntax
lastupdate : 2022-01-01
compatible : Ponder Stibbons, Hrun, Detritus, Elenor Of Tsort, Frusterick Manners, Greebo+
depends    : 
conflicts  : 
similar    : comment, commentsrc, wrap
tags       : annotations, hide, comment

downloadurl: https://github.com/ssahara/dw-plugin-commentsyntax/zipball/master
bugtracker : https://github.com/ssahara/dw-plugin-commentsyntax/issues
sourcerepo : https://github.com/ssahara/dw-plugin-commentsyntax
donationurl: 

screenshot_img : 
----


===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Feature =====

The **Comment Syntax** plugin brings a CSS-like comment syntax to your DokuWiki. The comment is not shown in the page, but visible when you edit the page.

Comments are used to explain your [[:wikitext|Wiki source text]], and may help you when you edit it, especially which is using complex syntax markups, at some future. Comments are ignored when converting source text to html.

===== Examples/Usage =====

==== 1. 'C' style comments ====
'C' style comments start with ''%%/*%%'' and ends with ''%%*/%%''. The comment-start markup ''%%/*%%'' must be placed at the start of line, or after a white-space letter. Comments can also span multiple lines:

  /* This is a comment */

  /* This is 
  a multi-line
  comment */

The **comment syntax** mode has priority to list block mode. You may comment-out some list item without breaking the whole list structure.

<file>
  - item 1 /* A white space is necessary before comment-start markup */
/*- item 2    will be eliminated from this list without breaking it */
  - item 3 /* will be numbered as 2 in the list */ 
</file>
  - item 1
  - item 3 

Note that 'C' style comments end at the first ''%%*/%%'' encountered. If you however wish that **nested comments** should be treated correctly, you can change the behavior through the configuration. In case the ''use_cstyle_nest'' option is enabled (default off), the whole part enclosed in outmost pair of ''%%/*%%'' and ''%%*/%%'' recognized as a comment:
  /* There is an another comment /* in this comment */ (nested comment)*/

==== 2. one-line comment ====
The "one-line" comment syntax will be available if the ''use_oneline_style'' option is enabled (default off).
<file>
  * non-ordered list item // comment 
</file>

  * non-ordered list item

<file>
  - item 1 // A white space is necessary before One-line comment markup
//- item 2    will be eliminated from this list without breaking it
  - item 3 // will be numbered as 2 in the list
</file>
  - item 1
  - item 3 

:!: **Adverse effect:** The one-line comment syntax ''%%//%%'' may interfere with the markup for //italics//. The use of //italic// formatting markup ''%%//...//%%'' will be restricted so that it can not go over next line.  
<file>
This text //in italics. 
is rendered as normal // due to broken double-slash pairs
</file>

This text is rendered as normal

==== 3. Control Macro like Comments ====
There are so-called [[wiki:syntax#control_macros|control macros]] syntax, such as ''%%~~NOCACHE~~%%''. It may be convenient if you put a white space between ''%%~~%%'' and ''%%NOCACHE~~%%'', it becomes a comment without displaying ''~~ NOCACHE~~'' in the page.

  ~~ This is a comment without affecting other macros in the page. ~~ 


==== 4. HTML comment syntax ====
The HTML comment will not rendered by the browser, but can be viewed with “View source code” command.

  <!-- This is a HTML comment -->

===== Configuration and Settings =====

^ Config key            ^ Description  ^
|''toolbar_button''     |enable toolbar button {{https://raw.githubusercontent.com/ssahara/dw-plugin-commentsyntax/master/images/comment.png|toolbar icon}} (default off)|
|''use_cstyle_nest''    |use nested C-style comments syntax (default off)|
|''use_oneline_style''  |use one-line style comments syntax (default off)|

===== Development =====

=== Change Log from github repository ===
{{rss>https://github.com/ssahara/dw-plugin-commentsyntax/commits/master.atom date 5}}

=== ToDo/Wish List ===

===== FAQ =====
=== Different syntax patterns of similar plugins === 
^ plugin name    ^ mode type ^  regular expressions  ^^
|[[plugin:comment]]         | substition |special pattern |''%%^/\*.*?\*|\s+/\*.*?\*/%%'' |
|[[plugin:commentsrc]]      | substition |special pattern |''%%!-.*-!%%''  |
|commentsyntax   | protected   |entry pattern   |''%%[ \t]*\n?/\*(?=.*?\*/)%%''  |
| :::            | :::         |exit pattern    |''%%\*/%%''              |
| :::            | substition  |special pattern |''%%\s//(?:[^/\n]*|[^/\n]*/[^/\n]*)(?=\n)%%''  |
| :::            | substition  |special pattern |''%%~~[^\r\n]+?~~%%''  |


===== Known Bugs and Issues =====



===== Discussion =====

Is there plans to fix the current issues?

> Which issues? There are none listed here nor in the bug tracker. --- [[user>ach|Anika Henke]] //2016-07-31 15:42//