• 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 or reader 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...

Source comments

A source comment is typically only intended to show up when an author edits a page. Source comments are not included in the generated page output. 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 generated HTML output
(:ifend:)
bla.

In this case the source comment will not be exported to the HTML.

The other method is to 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.

HTML comments

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 present, but hidden or invisible in the resulting
output.
>>comment<<
This text will be hidden or invisible in the resulting output.
You can have several lines of comments when writing like this.
>><<
bla.

or

# Bla...
# This will be present, but hidden as well %item comment%
# bla.

Note

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

technically this is achieved by the use of style='display:none'

Visible reader comments

An example of a visible reader comment in a page using a wiki style to mark text as being a comment that appears with a special format.

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

%commentary% This is a comment created using a wiki style %%
>>commentary<<
so is this
>><<

bla.

As an alternative to the commenty style defined above, it could have been defined by adding the following to the local configuration file:

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

Information found here

Other types

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.

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

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 your local configuration file.

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

Then simply use the directive as follows:

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).

Questions

Why doesn't the following work?

(:div class="comment":)
Bla...
Another form of block comment.
(:divend:)
bla.

or

(:table:)
(:cellnr:)Row one
>>comment<<
(:cellnr:)Row two - should be commented out
>><<
(:cellnr:)Row three
(:tableend:)

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