Formatting Rules

To keep the wiki database lean, mean, and clean, please use the Graffiti page for formatting practice.

Classic Markup:

Wiki text is seen as one of 3 types of lines: Normal, Indented, or Special lines.

1. Normal lines are sentences which start in the first column. A series of sentences without intervening newlines, empty, indented or special lines is displayed as a paragraph and always rendered as one logical line. It is left to the browser to wrap this logical line according to the screen or window width. Embedded page and URL references are detected and rendered appropriately.
2. Indented lines are text lines indented by spaces and/or tabs, and are always rendered as single lines. A writer who wants to control the exact setting of newlines has to indent each section of text by at least one space or tab. The disadvantage is that embedded references and italic/bold markings are not recognized. The primary purpose for indented lines is the embedding of scripts and other verbose information into a page.
3. Special lines are recognized through the usage of special patterns at the beginning of a line. These are explained below. They are always rendered as single lines (possibly wrapped by the browser), but without surrounding vertical whitespace (in contrast to 2 and 3). Multiple newlines between special lines are simply gobbled. The only way to introduce separation is by usage of horizontal rules, normal or indented lines. Special lines always form a paragraph by themselves. Cutting a special line into multiple physical lines creates during rendering one special line and one or more paragraphs from the rest, depending on the indentation.

List Types

1. Numbered list items (such as this) are done using three spaces, a digit, a period (.), at least one space, and the main paragraph text.

• Bulleted list items (such as this) are done using three spaces, an asterisk (*), at least one space, and the main paragraph text.

Tagged list items (like this)

These are done using three spaces, some tag string (which may include single spaces), a colon (:), three spaces, and the main paragraph text.

Inline Formatting

Inside a normal paragraph, the following formatting is supported:

fixed-width text

Enclosed by `back-quote characters. Double the ` to get a literal `, which also works in fixed-width text ` itself.

italicized text

Enclosed by two apostrophe (', single quote) characters

emboldened text

Enclosed in three apostrophes (single quotes)

Internal links

Enclosed by the name of the page in square brackets ([Formatting Rules])

External links

Automatically recognized, no special formatting required: https://wiki.tcl-lang.org/ . An external link is formatted as [L1 ] when written as [https://wiki.tcl-lang.org/] .

Other

A line whose sole content is four or more hyphens (----) is rendered as a horizontal rule.

New markup:

Beginning in 2007, there was a major change to the software running this wiki. As a part of that move, new formatting became available. Here are some of the changes made:

Lists

Unnumbered lists

Nested unnumbered lists can be done like this:

   * a
   ** a.a
   ** a.b
   *** a.b.a
   *** a.b.b
   *** a.b.c
   **** a.b.c.a
   **** a.b.c.b
   **** a.b.c.c
   *** a.b.d
   ** a.c
   * b
   * c

which will look like:

• a
  • a.a
  • a.b
    • a.b.a
    • a.b.b
    • a.b.c
      • a.b.c.a
      • a.b.c.b
      • a.b.c.c
    • a.b.d
  • a.c
• b
• c

Numbered lists

Nested Numbered lists can be done like this:

   1. a
   11. a.a
   11. a.b
   111. a.b.a
   111. a.b.b
   111. a.b.c
   1111. a.b.c.a
   1111. a.b.c.b
   1111. a.b.c.c
   111. a.b.d
   11. a.c
   1. b
   1. c

which will look like:

1. a
   1. a.a
   2. a.b
      1. a.b.a
      2. a.b.b
      3. a.b.c
         1. a.b.c.a
         2. a.b.c.b
         3. a.b.c.c
      4. a.b.d
   3. a.c
2. b
3. c

Mixed lists

Numbered and unnumbered lists can be mixed:

   * a
   11. a.a
   11. a.b
   111. a.b.a
   111. a.b.b
   111. a.b.c
   **** a.b.c.a
   **** a.b.c.b
   **** a.b.c.c
   111. a.b.d
   *** a.b.e
   11. a.c
   * b
   * c

which will look like:

• a
  1. a.a
  2. a.b
     1. a.b.a
     2. a.b.b
     3. a.b.c
        • a.b.c.a
        • a.b.c.b
        • a.b.c.c
     4. a.b.d
     • a.b.e
  3. a.c
• b
• c

Code block

A code block starts and ends with a line containing ======. Line markup is not processed.

A '''code'''
       ''block''
             [Tcl]
set a [expr {$b+12}]
lappend result $a $b $c

Notice the syntax highlighting and keyword links to corresponding wiki page. Code blocks are by default colored as Tcl code, which is equivalent to starting it with ======tcl. If you want c or c++ coloring, start the code block with ======c or ======cpp. If you don't want a code block to be colored, start it with ======none.

Fixed width font block

A fixed width font block starts and ends with a line containing ===. Line markup is processed:

A fixed width
             font block
                        Tcl

Option-value block

An option-value block start and ends with a line containing +++. Each line in an option-value block starts with an option, 2 or more spaces and the value. The option is shown in a fixed width font. Markup like this:

+++
a_command ''arg1'' ''arg2''   a command and arguments
b_command ''arg1'' ''arg2''   b command and arguments
+++

gets rendered as:

Fixed width font

When putting one or more words in a line between back-quotes, those words will be printed in a fixed width font.

Headers

A line starting and ending with **, *** or **** is displayed as a level 2, 3 or 4 html-header.

Table

Tabular data

A table can be made out of rows. A row is a line starting and ending with a | sign. This | sign is also used to separate row elements. An example:

|a|b|c|d|
|eeeee|[Tcl]|g|h|
|i|j|''italic''|l|
|m|n|'''bold'''|`fixed width`|

This is rendered as:

Column headers

A header row can be added to a table by beginning and ending a row with % signs like this:

%|a|b|c|d|%
|eeeee|[Tcl]|g|h|
|i|j|''italic''|l|
|m|n|'''bold'''|`fixed width`|

is rendered as:

Colored rows

When using | signs to delimit a table rows, the rows all get the same background color. When starting table rows with &| and ending them with |&, odd and even rows get different background colors. The following example:

%|a|b|c|d|%
&|eeeee|[Tcl]|g|h|&
&|i|j|''italic''|l|&
&|m|n|'''bold'''|`fixed width`|&
&|a|b|c|d|&
&|a|b|c|d|&
&|a|b|c|d|&

is rendered as:

| sign in table cells

When a | character is needed in a table cell, replace it with:

<<pipe>>

This example:

%|a|b|c|d|%
|eeeee|[Tcl]|g|h|
|i|j|''italic''|l|
|m|n|'''bold'''|`fixed <<pipe>> width`|

This is rendered as:

To insert a newline in a cell, use

<<br>>

This notation must also be used when starting and ending a non table line with a | sign.

Centered block

To center a block of text horizontally, put a line containing only !!!!!! (six exclamation marks) before and after the block like this:

 !!!!!!
 This text will be centered!
 !!!!!!

This is rendered as:

New line

The following will be translated to an html <br> statement:

<<br>>

An example:

Always wanted a line break between this<<br>>and this word!

Will be rendered as:

Always wanted a line break between this
and this word!

This can also be used inside table cells.

Description/Definition

Items needing a description/definition can be specified as 3 spaces, some text, a colon, 3 or more spaces, and the description:

   item ''needing'' '''description''':   the '''description''' the item ''needed''

Will be rendered as:

item needing description

the description the item needed

Links

By adding %|%<string>%|% to the end of a link you can set the string displayed for the link. This example:

Click [Formatting Rules%|%here%|%] for more info on formatting rules or https://wiki.tcl-lang.org%|%here%|% to go to the home page.

will be rendered as:

Click here for more info on formatting rules or here to go to the home page.

Redirecting

A page can be redirected to another by specifying the name of the page to redirect to with the following markup:

<<redirect>>Name of page to redirect to

When you got redirected, you'll find the name of the page you got redirected from in the header. Clicking on the name of the redirecting page in the header will bring you to the redirecting page itself.

Images

Images can be added to a page by creating a brand new (thus another) page that exclusively holds this image and that is named somehow in relationship to the image. After including an image, that page cannot be edited nor can text be added. To include an image see "Upload from file:" at the bottom of the edit page.

The image can be made visible within a text page by linking to it the same way as linking to another text page (hence remind the name of the page where you included the image). Width and height of the inlined images can be specified following %|%. Using this markup:

[WOMM Certification%|% width=200 height=200]

will inline the referenced image:

Back-references

Back-references to a page can be included by adding:

 <<backrefs>>

For this page it looks like:

By adding a page name at the end of the back-reference line, you can include back-references to other pages. The following line will include all back-references to the LLVM page:

<<backrefs>> LLVM

Which looks like this:

<<backrefs>> LLVM

Categories

Specify the categories a page belongs to with the following markup at the end of the page:

<<categories>> Wikit | Example

which will be rendered as:

See Category Category page and How do Wiki Categories work for more information about categories.

The "Category" prefix in the category name is optional. The above could equivalently have been written: <<categories>> Category Wikit | Category Example.

Discussions

Some pages include a lot of discussion. Using the <<discussion>> markup it is possible to hide these and show a button to make them visible. A discussion starts with a line containing <<discussion>>, optionally followed by a discussion header text (also in wiki markup). A discussion ends with:

• a line containing <<discussion>> after which the rest of the page is displayed normally
• a line containing <<discussion>> followed by a discussion header which will start a new discussion
• a <<categories>> statement

The following markup will create discussions:

 <<discussion>>
 This is a discussion without header
 <<discussion>>
 <<discussion>>
 This is another discussion without header but ended by a discussion with a header
 <<discussion>>Discussion `with` a header
 This is a discussion with a header, ended by another discussion with a header
 <<discussion>>Another discussion with a ''header''
 This is a discussion with a header, end by a `<<discussion>>` line
 <<discussion>>
 <<discussion>>
 And a final discussion ended by a `<<categories>>` line
 <<categories>> Wikit | Example

which is rendered as:

Table Of Contents

A table of contents for a page can be inserted using the following markup:

<<TOC>>

See also Embedding Images in the Wiki (outdated) and Wikit user names.

Questions relating to this wikit's page formatting rules

Larry Virden - There's a problem in the "Editing quick-reference" text - it says "Highlights are indicated by single quotes" - this implied - at least to this reader - that a single pair of single quotes did some kind of highlighting. Obviously, that's not correct. Perhaps the text should say "... by groups of single quotes".

Andy Tanenbaum 8-Oct-2002 - Some folks don't type exactly three spaces after the colon when trying to include tagged list items. If four or more spaces are typed instead, the list items come out as non-wrapped monospaced text, which is not convenient. Could the parser be changed to allow three-or-more spaces in these cases instead? It seems that three-or-more are ok before the tag, but not after the colon, is this an oversight? (Did this work at one time and then get changed? I just fixed about half a dozen tagged list entries on the glossary page that were getting mis-rendered.)

AK: The Wiki got a new renderer, faster than the old one, yet retaining compatibility with regard to input format. I tested this with 47 pages taken from this wiki itself, but not with all. In other words, it is possible that some difference slipped through. Members of the 'TclersWiki' mailinglist at yahoo can see the code of this renderer at http://groups.yahoo.com/group/TclersWiki/files/ .

In earlier versions of the wikit software, there were some characters which, when found in a page title, caused unexpected formatting problems. Some punctuation marks - such as + or ? - which also function as regular expression metacharacters, caused problems, while others, such as comma, did not.

Anyone know whether this is still a problem? PLEASE DON'T CREATE RANDOM PAGES HERE TO TEST! Either point us to existing pages with problems, or set up a wikit at home and see what you can find.

Editing the Wiki pages is no rocket science, but if I want to add a link to a Wiki page that does not exist yet, how am I supposed to create it?

LV All you do is write a single left square bracket followed by the name of the page you are wanting to create, followed by a single right square bracket. Save the page. The name of the page will show up with only the brackets showing as links. Click on the left or right bracket (which point to the same page). This will take you to the new blank page. Fill it out, save it, and off you go!

Someone recently asked about the undocumented formatting that appears to occur when typing 4 spaces by a colon and a space:

 one space formatting is displayed in this manner
    : the four space and colon type of formatting.

LV That format is documented - on https://wiki.tcl-lang.org/6 . The reason you may not recognize that you are tagging the line is because the tag code is described as 3 spaces, an identifier, a colon, and three spaces - so, this is a tagged line

tag

a way of marking a word and definition.

2 feb 2008 - when can the above formatting be available to users, as well as for download? michaely

LV the above formatting has been available for the past 2-6 months, I believe. As for download, are you asking where one can download the code for the wiki?

9 feb 2008 - oops! while editing this entry, i notice that the formatting above works just like it says, how embarrassing. the 'download' means the wikit.kit file. i tried some of the formattings (on my computer) but it did not works as stated... so i guess it must be for this website only. i will give it another try. michaely

jdc to get the above formatting, you will need Wub and wikitcl. A the bottom of the Wub page, apw describes how to get a local install.

11 Feb 2008- After editing and saving, remember to use "Reload Current Page". I had a bit of head scratching & wondering 'what the heck....' with having edits not showing after a save, it seems edits don't work, until you think about cache. All right, at least I put the two sentences I would look for in here if it happens to me again (it will :-) ) Jaf

LV Gentle readers, don't forget that http://code.google.com/p/wikitcl/issues/list is the place to report bugs, unexpected behavior, and requests for enhancements to this wiki software.

Jaf I didn't classify what happened as a Wikit problem. That was just me forgetting to hit the 'Reload'-Button. If there was a way the Wiki could tell the browser to automatically update that would be great. But, code just for my 'Alzheimer', nah, not worth it. A postit on the monitor and the phrase 'edits don't work' to search for are more than enough, 'low tech' but it should work. Cheers.

Question: I can use only classic markup, why? I downloaded wikit from http://www.equi4.com/pub/sk/wikit.kit where to find the wikit.kit for this site: https://wiki.tcl-lang.org/

LV this web site - wiki.tcl.tk - has been upgraded from the starkit you downloaded to totally original version which provides all the new functionality. See wub for details.

LV Is anyone aware of any other wub wikit formatting notation that takes place that is not currently mentioned on this page?

The wiki page rendering code has a set of characters that, if found as the last character of a URL, will be ignored. This list includes

[I believe this applies even to URLs within square brackets...]

If you enter a URL that ends in one of the above characters in column 1, the hyperlink that is created will not include the character in the URL to be followed. This will, in general, make the URL appear to be broken. Replace the literal character with the escape sequence and save the page. The resulting URL should be correct.

LV What is the trigger to get the page headers to show up in the wiki's sidebar column?

AMG Use ** header 1 **, *** header 2 ***, etc. It's automatic.

LV That's what I thought, but on menu, I tried to set up the headers and I don't see them showing up in the sidebar...

AMG: Here's what I see on menu's sidebar, right beneath the search boxes:

Page contents
 Tk menus
 Popup Menus
 How to add to the System menu in windows
 How to add console control to the System menu on Windows
 Questions
 See Also

Good - it is there now. When I first made the change, these didn't show up. Of course, I'm using IE 7 - might be some strange interaction. [eventually, make my way back here and replace this interchange with just a summary...]

dbohdan 2014-07-21: Is there a way to make text strikethrough?

AMG: Use http://s̶t̶r̶i̶k̶e̶.ws/ to suffix each character with \u0336 Unicode strikethrough combining characters. Or if you want to get really, really extravagant, use Tcl. :^)

proc strike {text} {regsub -all . $text &\u336}