De Redes de Computadores

PmWiki: 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.

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'

Warning

This actually isn't a comment at all, PmWiki markupup, directives, etc are all active and functional, the results are simply not shown (as opposed to being embedded in an HTML comment tag).

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

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?