MarkupTricks

Summary: Markup tricks
Version:
Prerequisites: Should work on any v 2.0 PmWiki
Status:
Maintainer:
Categories: MarkupOnly
Discussion: MarkupTricks-Talk

This page provides "markup tricks". Some workarounds to get to certain display results using existing markup.

Do not confuse this page with MarkupExtensions, which adds new markup to PmWiki.

Commenting out long blocks on a page

Also known as: multiline comments

If you want to put many lines of comments on a page that are only visible in edit view and that can include directives that you don't want processed, use the "if false" trick:

this text will be visible
(:if false:)
here is some
text
(:searchbox:)
with other directives
(:ifend:)
but the intervening lines will only show in edit view

this text will be visible but the intervening lines will only show in edit view

Using a new wiki markup {# ... #}

Here is another way to comment out long blocks on a page which is shorter than (:if false:) ... (:ifend:). You can add new wiki markup by adding this code to your local/farmconfig.php or local/config.php:

Markup('{#','>[=','/\\{#(.*?)#\\}/s','');

Then, in the page, you write

 '''Hello {# This text 
will be removed. It 
could be multiline too.#} World'''

Which displays "Hello World".

If you wish to add a toolbar button for the markup in your edit form, copy this picture to your pub/guiedit directory, then add to config.php this line:

 $GUIButtons['wikicomment'] = array(360, '{#', '#}', '$[Comment out]',
        '$GUIButtonDirUrlFmt/wikicomment.png"$[Comment out blocks]"');

Comment markup

You can add a wiki [[PmWiki/CommentMarkup | comment]]
>>comment<<
within which text will not display on a page
>><<
to hide text

You can add a wiki comment

within which text will not display on a page

to hide text

Note that text "hidden" with this markup actually appears in the HTML page and in the page source. Some browsers will display it, search engines will see it and will show it in search results, and a reader can retrieve it by disabling page styles (CSS) or by viewing the page source.

Spaceless block preformat

How can I do spaceless block preformat - that is, preformat multiple lines without prefixing each line with a single space? For instance, I want to display a code block in the wiki.

The answer is our old friend, [=...=], but with a space on the line before the opening bracket. Here is an example:

 [= 
int main(int argc, char** argv)
{
  time_t epoch;
  char sdate[MAXS];
  struct tm* tmP;
  if (argc<2) {
    USAGE(NULL);
  }
} =]
  
int main(int argc, char** argv)
{
  time_t epoch;
  char sdate[MAXS];
  struct tm* tmP;
  if (argc<2) {
    USAGE(NULL);
  }
} 

In newer releases (~beta52) this is a good markup for code

-> [@ 
  a=b;
  c=b;
@]
 
  a=b;
  c=b;

If you are marking up a lot of code samples, you should check out SourceBlock.

Preformatted text

The "pre"formatted
markup [[wiki style(s)]] 
(from version 2.2.0-beta41)
>>pre<<
can be 
used to
-> (including indented text)
>><<
format text on a page
where line breaks are required

The "pre"formatted markup wiki style (from version 2.2.0-beta41)

can be used to

(including indented text)

format text on a page where line breaks are required

Indenting blocks of text with line breaks

Blocks of text to which (:linebreaks:) has been applied can be indented by preceding the first line of the block with indention arrows (->) and aligning subsequent lines under the first. An unindented line stops the block indentation.

(:linebreaks:)

This is normal text, no indentation.

-> Here is some indented
   text with line breaks
   in the middle of the text.

   We can even continue the indentation 
   across paragraphs.

Now we're back to normal again.

(:nolinebreaks:)

This is normal text, no indentation.

Here is some indented
text with line breaks
in the middle of the text.
We can even continue the indentation
across paragraphs.

Now we're back to normal again.

Displaying directives

I tried to post a note to my authors saying:

If you enter 3 tildes (~~~) in a row, PmWiki will automatically insert your name. My markup was:

 ... 3 tildes [=(~~~)=] in a row ...

which renders exactly the way I want in preview, but renders when saved as:

 ... 3 tildes (NeilHerber) in a row ...

The problem is that the 3 tildes are a "replace on save" markup -- the tildes are replaced with the author's name at the time the page is saved. For a variety of reasons, it's not a trivial matter to preserve them when they appear inside of [=...=].

The workarounds are anything that causes the three tildes to not directly appear together, such as:

    [=~~=]~
    ~&#126;~

This trick can be generalized to display any markup that you don't want rendered. The rule of thumb is to break up the markup with the [=...=] construct. WARNING: Reading the markup on this page in edit mode makes my head hurt!

Insert spacing within a text line

To insert additional spacing in a textline you can use space characters from the Special Characters List like &ensp; &emsp; &thinsp; &nbsp; .

Some &ensp; &nbsp; spacing

Some     spacing

Spaces in file descriptors and URLs

For spaces in URLS simply enclose the URL in Link markup

http://example.com/~user/my website/

[[http://example.com/~user/my website/]]

http://example.com/~user/my website/

http://example.com/~user/my website/

For spaces in attachments (other than images)

Attach:Cookbook.MarkupTricks/The importance of being earnest.odt

[[Attach:Cookbook.MarkupTricks/The importance of being earnest.odt]]

Attach:Cookbook.MarkupTricks/The Δ importance of being earnest.odt

Attach:Cookbook.MarkupTricks/The importance of being earnest.odtΔ

For spaces in Images there is no really good solution. It is to be hoped that an enhancement[1] will be added to a future version of PmWiki to solve this issue. The following kludge can be used

Attach:image space.jpeg
Attach:image space.jpeg

[[#blank | Attach:image space.jpeg]]
[[#1 | Attach:image space.jpeg]] 

Attach:image Δ space.jpeg Attach:image Δ space.jpeg

Parentheses in URLs

PmWiki parses out parentheses, ( and ), from links and URLs. To use in a URL replace ( with %28 and ) with %29 (percent-encoding). For example, change http://maps.google.com/maps?q=Vancouver,+BC%20 to http://maps.google.com/maps?q=Vancouver,+BC%20%28Vancouver,%20Canada%29 in order to have the bubble text display properly in Google Maps.

Notes

See Also

Contributors

  • NeilHerber March 16, 2005, at 12:24 PM
  • Petko October 26, 2008, at 07:32 AM (section "Using a new wiki markup {# ... #}")
  • Simon spaces in file names

Comments

See discussion at MarkupTricks-Talk