• View
• Edit
• History
• Print
• Backlinks

CommentMarkup

This page discusses various forms of comments and how to achieve them for wiki pages.

Types and kinds of comment

The word comment can mean many things. Here are some possible interpretations:

Source comment or markup comment

This kind of comment is only supposed to show up in the source of a wiki page. They are useful for giving instructions to an author who edits a page. See below for an example.

Page comments

These kind of comments are readers' notes on the contents of a page and take various forms. They might be embedded in the page or kept separate. See below for an example using wiki styles.

HTML comment

A piece of text that is output as a HTML comment, i.e. marked as a comment according to the HTML syntax in the resulting output.

Other types

I'm sure there are more aspects to this...

Examples of source comments

A source comment is typically only intended to show up when an author edits a page. Conditional markup is one method of writing such a comment that is easy to create. Here is an example:

Bla...
(:if false:)
	This text is a comment. It won't be shown,
	nor appear in the HTML output
(:ifend:)
bla.

In this case the source comment will not be exported to the HTML. If you want the comment to appear in the html source of the page, you should instead make the comment invisible. You could use the predefined wiki style %comment% for this purpose. Here are examples.

Bla...
%comment% This will be hidden/invisible in the resulting output
bla.

or

* Bla...
* This will be hidden as well %item comment%
* bla.

Note that someone who looks at the HTML output of this page will see the above comments.

An alternative to using %comment% is to write it as follows:

Bla...
>>comment<<
This text will be hidden/invisible in the resulting output.
You can have several lines of comments when writing like this.
>><<
bla.

As a final alternative, it is also possible to use the special directive (:comment:) for comments that produces no output. Here is an example:

Bla...
(:comment Here is a comment that produces no output:)
bla.

Example of a visible comment in a page using wiki styles

Here is an example of using a wiki style to mark text as being a comment that appears with a special style.

Bla...

%commentary% This is a comment created using a wiki style %%

bla.

The commentary wiki style used in the previous example was defined

	%define=commentary apply=block 			\
			   background-color=#f8dce1	\
        	           margin=1em			\
			   border="1px dotted #ea97a4"%%%

As an alternative, it could have been defined by adding the following to the

$WikiStyle['commentary']['apply'] = 'block';
$WikiStyle['commentary']['background-color'] = '#f8dce1';
$WikiStyle['commentary']['margin'] = '1em';
$WikiStyle['commentary']['border'] = '1px dotted #ea97a4';

Information found here

Kale Stutzman? - Coming from a C background (but really this could apply to anyone) I have found the above methods unfamilar, hard to read, as well just too much extra code to type. By adding the following line to config.php and editing it accordingly, any sequence of charactors can be used for comments.

Markup("user-comment", "directives", "/front bracket code(.*?)end bracket code/", "");

Special characters need to have two backslashes - \\ - in front of them, so C-style comments /* comment */ would be coded like this:

Markup("user-comment", "directives", "/\\/\\*(.*?)\\*\\//", "");

HTML comment

You can use the directive described below in case you would like to use markup to create a comment that appears as an HTML comment (i.e. it is embedded in <!-- and --> in the resulting HTML output.

You can create the directive (:HTML-comment:) by adding the following to

 ## (:HTML-comment:)
 Markup('HTML-comment', 'directives',
	'/\\(:HTML-comment (.*?):\\)/i', '<!-- $1 -->');

Then simply use the directive as follows:

	(:HTML-comment This text will become an HTML comment:)

Note: This information was modified from Cookbook:GeneratePDF and has not been tested.

ccox - I use it and depend upon it.. I wrote that little blurb of a recipe. It works. However, I override the (:comment:) directive. It simply makes your wiki comments show up as HTML comments. I did this to allow the htmldoc processor used by the Cookbook:GeneratePDF to use the comments to control the PDF output (e.g. page breaks).

Links and related information

• WikiStyles
• ConditionalMarkup
• Cookbook recipes (mostly for page comments)
  • Cookbook:CommentBox
  • Cookbook:CommentPageLink
  • Cookbook:Comments — uses separate file to store (page) comments
  • Cookbook:GeneratePDF — origin of the HTML comment
• MarkupMasterIndex

Contributors

• chr