Editing Wikitext/Preformatted Text

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Pre-formatted text is text that has been wrapped and additionally spaced by the user. It has spacing in it that is contrary to the preferred web-page layout, usually because its format has been determined in the culture from which it was obtained. It is seen mainly in writing for poetry, prose, lyrics, and most of all, in the listing of programming code.

It is distinguished from the more usual un-formatted text, where the software takes care of wrapping text while the user just keeps typing. Un-formatted text also depends on the software to handle line spacing, and to remove any extra spaces between words. As the reader will be aware, the Wiki software permits only one space after punctuation or between words, and will ignore a single line space, needing two of these to make a new paragraph.

True pre-formatted text is said to preserve white-space, because it must display text exactly as it is typed. However, a number of HTML-like tags have been made for other kinds of pre-formatted text; these preserve white-space to varying extents and each has characteristics of its own.

Pre-formatting Tags[edit | edit source]

The pre tags provide the most general method for displaying pre-formatted text. The text to display is simply enclosed in these tags and the text appears in a gray background with a dashed blue border. For example, when this code is typed in the editing window;

The time has come
the walrus said to
speak of many things...

it displays like this:

The time has come
the walrus said to
speak of many things...

A short experiment will confirm that without the tags, the lines would all display as one single line of text.

'Pre' Tag Summary:
  • They are simple to use; as such, their shortcomings are easily dismissed.
  • The format looks contrived; in that it does not entirely match any page format.
  • It uses the whole width of the page; even for a word or two, unless the tags are in-line styled.
  • Nesting pairs of pre tags will corrupt a layout; the inner pair need to be literals. See below.
  • Long lines do not wrap; though this has been corrected for recent browser versions.
  • The tags can be styled with CSS properties.
  • Pre-formatted text tags cannot be used within Wiki or other lists.

Nested Tag Problem[edit | edit source]

When the block of text that is to be displayed within the pre tags has itself pre tags in it, then the display will be corrupted. This results since the first closing tag is taken instead of the last. To get around the problem, and other problems of this type, all of the text block's pre symbols must be written in their literal form instead of their usual HTML tag format. This method can be applied elsewhere, such as for the <nowiki></nowiki> tags when similar problems arise.

The literal form is treated as text as opposed to being interpreted as having a function. To make a literal form, the wording within a tag need not be changed; it is only the less than symbol and the greater than symbol that need be substituted. Notice that literals start with an ampersand symbol then add other characters to it; finally a semi-colon is added. The entire tag is reconstructed by running all of the parts together into one word. The literals are shown for two sets of tags in the table below. See also meta:Help:Special characters.

It may be of interest for some to note that, since a literal typed into an editor window displays on the page as if a conventional tag notation were entered, it follows that in order to display a literal itself on the page, such as in the table below, a still different format is needed. To avoid a struggle in finding codes to explain the matter, interested parties can find the solution, should they ever need it, by accessing the markup for this page.

Literals for Selected Tags
HTML Tag Format Literal Tag Format
<pre> &lt;pre&gt;
</pre> &lt;/pre&gt;
<nowiki> &lt;nowiki&gt;
</nowiki> &lt;/nowiki&gt;

Styling Tags[edit | edit source]

The tags can be styled to change the formats. As is the case with all tag styling, a CSS style expression is placed in the leading tag. The example below shows the styles to change the basic pre layout to the format of the small box with the colored text.

<pre style="white-space:pre-wrap; width:25%; border:1px solid lightgrey; background:ivory; color:blue;">
The time has come
the walrus said,
to speak of many things...

It displays like this:

The time has come
the walrus said,
to speak of many things...

To center the box in the page, place all of the above, dropping the whitespace property, within a single table cell, and shift the outer containing table to center. When this method is used, the width setting should belong to the outer table. The revised code for a box that can be centered, (aligned on the page), is shown below, with the result.

{| width=25% align=center
|<pre style="border:1px solid lightgrey; background:ivory; color:blue;">
The time has come
the walrus said,
to speak of many things...

It displays like this:

The time has come
the walrus said,
to speak of many things...

Browser Pre-wrap Test[edit | edit source]

When code lines are to be listed, it often happens that some lines are longer than the page width. Because the text must be displayed just as it was typed, such lines will cause the text to spill out of the box and extent far to the right. The solution to this problem is to employ a conditional form of pre-formatting. By adding the style property white-space:pre-wrap; to the pre style expressions above, the long lines will be wrapped automatically while other white space is preserved.

At present, the Opera browser can function well with the white-space: pre-wrap;property, and it is included in Firefox, starting with version 3. Internet Explorer 6 does not support this value though Internet Explorer 8 does; the status of IE7 is still unclear. Many other browsers are not yet upgraded for its use, so users of Wiki pages that depend on it might not see the intended display.

To test whether or not your browser can handle pre-wrap, consider the box below. The first sentence consists of one long line of text and should be wrapped within a 400 pixel-wide box for a browser that can correctly handle the white-space:pre-wrap; property.

                 BROWSER PRE-WRAP TEST
If your browser can handle the pre-wrap feature, then this first sentence of un-formatted text will be wrapped in this 400 pixel-wide box, while the spacing of the remainder will be preserved.

a                b                c                d 
e                f                g                h 
i                j                k                l 
m                n                o                p
q                r                s                t
u                v                w                x 
y                z

If your browser is not compatible, the long line of text
in the first sentence above will spill over and extend
far beyond the margins of the box, or the box will be
extended to the right margin. 

The Poem Tags[edit | edit source]

The poem tags are designed for poetry and prose, though they can be adapted for code listings. They allow the use of a single line break to start a new line. In addition, a new line can start with a space.

The spacing rules for punctuation remain the same as for un-formatted text, and the wikitext apostrophe codes are still honored; three sets for bold, two sets for italics etc. Headings are possible provided that HTML heading codes are used. The tags do not invalidate code in the way of nowiki tags, and tables will remain active when their code is placed between poem tags.

'Poem' Tag Summary:
  • Space is generally not preserved; it is parsed like un-formatted text.
  • Single hard returns make a new line; this is needed for prose.
  • Leading spaces for lines are permitted; not like un-formatted text.
  • Wikitext apostrophe codes still work within the tags; italics, bold, etc.
  • HTML tags generally work within poem tags; though wiki headings do not.
  • Templates and tables are not deactivated; without nowiki tags they will run normally.
  • Long lines will be automatically wrapped; useful for code listings.
  • The tags can be styled with CSS properties; Default formats resemble the page.
  • Poem tags cannot be used within lists.

To display prose or poetry, or indeed any text that benefits from these formats, simply write the code as in the example below:

One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

The result is just as expected:

One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

Notice that the formats resemble those used for the main page, and that single line breaks have been used.

Styling the Poem Tags

To style the poem tags, a CSS style expression can be placed in in the leading tag. Some code can also be placed in a containing table cell to shift the block on the page. The following code listing can color the contents and shift the poem to the center of the page. The width of this block adjusts to the contents so some work may look inconsistent in width ; for a version with an independent width setting, place a width attribute in the table line and adjust the padding; see the CSS code summary in the last section for a list of these properties and others.

{| cellspacing=0 align=center
|<poem style="padding:15px 15px 15px 15px; background:lightyellow;color:maroon;border:1px solid gray;">
One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

The result is;

One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

Poem Tags for Code[edit | edit source]

A more complex example, this time to illustrate the automatic wrapping of long code lines is provided below. This time, the code block must be enclosed in nowiki tags to prevent the code from making a table on the page. As in the above section, a table container was added to permit alignment on the page, and details of the styles are shown. This time the code is all arranged in the table line as follows:

{| style="background:rgb(230,230,230);color:black; border:1px solid gray; font-family: fixedsys;" cellpadding=20px cellspacing=0 align=center width=80%
The code block goes here...

An example of such a display is just:

Wikitext Table Code Module

{| style="background:lightyellow; color:black; border:1px solid gray; font-size:inherit; font-weight:normal; font-family:inherit;" cellspacing=0 cellpadding=5px align=left width=70%
  |+ Top Caption Goes Here
  ! style="background:brown;color:white;border-bottom:1.5px solid black"|Heading 1
  ! style="background:brown;color:white;border-bottom:1.5px solid black"|Heading 2
  ! style="background:brown;color:white;border-bottom:1.5px solid black"|Heading 3
  | width=33% style="border-bottom:1px solid gray"|A
  | width=33% style="border-bottom:1px solid gray"|B
  | width=33% style="border-bottom:1px solid gray"|C
  | style="border-bottom:1px solid gray"|D
  | style="border-bottom:1px solid gray"|E
  | style="border-bottom:1px solid gray"|F
  | style="border-bottom:1.5px solid black"|G
  | style="border-bottom:1.5px solid black"|H
  | style="border-bottom:1.5px solid black"|I

Notice that the long code lines, notably the table's top line and the heading lines, have been automatically wrapped, (without any need for a pre-wrap property value).

The 'code' and 'syntaxhighlight' Tags[edit | edit source]

The <code> tags are useful when discussing small chunks of source code within a line of normal text. For example, "the infamous <code>gets()</code> function" is rendered as "the infamous gets() function".

The <syntaxhighlight> tags allow the display of pre-formatted code modules, but in addition they add coloring to the various elements of the code. Like the pre tags, they preserve white space, that is, they depict the code module exactly as it was typed.

When line numbering is in use, (the default state), long code lines will be wrapped and the code will be not extend beyond the boundaries of its container. To see code wrapping with these tags, refer to the examples below.

There are color plans for most programming languages, and a line is added to the leading tag to indicate what it is. See Code Coloring and Numbering for the full list. Wikitext is not listed as a language for these tags though text is. Although there is no coloring for the text selection, the numbering of lines is still possible, and with line numbering comes the wrapping of any long lines. As such. this text mode can be used for poetry, prose, and script listings.

Numbering is added by writing the word line within the leading tag. The numbering is applied to every line, but the starting number need not be one; it can be preset by adding the further entry, e.g. start=10, to start as line 10. If the line number is not given then the default applies and lines are numbered from one. When lines are copied for pasting elsewhere, the numbers are not copied; only the lines of text.

Programming code that was written in the syntaxhighlight tags, and then copied from a Wikibooks page, can be pasted directly into MS Word without any loss of quality. This is useful for those who want to write documentation.

'syntaxhighlight' Tag Summary:
  • The tags add color to enclosed code blocks; many language color plans exist.
  • Consecutive numbers can be added to lines automatically; the first number can be preset.
  • Highlighting of blocks of consecutive lines is possible.
  • When line-numbering is used, any long lines of text will wrap; there is no wrapping unless line-numbering is set.
  • Plain text exists as an option; so that Wiki or other text can be numbered too.
  • The tags cannot be styled; place everything in a table cell and style that.
  • Line numbers are not copied; only the text line is copied during copy/paste.
  • syntaxhighlight tags cannot be used within lists.

HTML Code Colors[edit | edit source]

The following example shows how to color an HTML code listing and to arbitrarily start numbering from 10. Additionally, the lines could be highlighted with an entry like highlight="2-3", though until more user-control over the highlight coloring is given, the effect must be said to be confusing; The term enclose="none" serves to remove the otherwise obtrusive dashed blue border which would result.

<syntaxhighlight lang="html4strict" enclose="none" line start=10 >
HTML module goes here...

A typical result for a short HTML table coding is:

<table align=center style="background: ivory;color:maroon;font-style:italic;font-family:arial;font-weight:bold;font-size:10pt;"> 
<caption>This is the top caption</caption>
<tr><th> Heading 1 </th><th> Heading 2 </th></tr>
<td style="padding:10px;"> This is cell 1 text </td>
<td style="padding:10px;"> This is cell 2 text </td>

Numbered Prose[edit | edit source]

The following example shows how to add numbers to poetry, prose or text, and start numbering lines from, for example, 1000. Note that another method for this exists in Other Ordered Lists.

<syntaxhighlight lang="text" enclose="none" line start=1000 >
Poem goes here... (let the software format any long lines).

A typical result is just:

One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

The syntaxhighlight tags do not permit any easy styling, but like the examples in the sections above, a table can be used as a container for the entire listing and that can be styled. An example of such a layout for numbered text is as follows:

{| style="background:ivory;color:black; border:1px solid gray; font-family: Inherit;" cellpadding=20px cellspacing=0 align=center width=40%
| <source lang="text" enclose="none" line start=1 >
One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

The result of running this code in the Wiki editor is:

One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...

Thus, a styled layout for numbered prose is possible, and formats are easily changed. Another method for numbered lists, e.g. prose, can be found by following the link Other Ordered Lists.

Older versions of Extension:SyntaxHighlight used the tag <syntaxhighlight>. This is still supported, but <syntaxhighlight> may help avoid conflicts if your source code itself contains <syntaxhighlight> tags (for example XML).

For those who need additional information on the syntaxhighlight tags and its language codes, go to Code Coloring and Numbering for the full set.

For a full text on CSS styles, refer to CSS Properties Reference

CSS Table Properties Summary[edit | edit source]

For those who intend to make use of tables in their work, the main CSS properties and HTML attributes have been summarized.

CSS Properties Summary
Commonly used style rules for Wiki markup tables :


There are two different sets of style rules in use; a set of HTML attributes that is associated with the specific elements in tables, and a Cascading Style Sheet set, CSS properties, that is of more general use.

Each of table, caption, row, and cell can be considered as separate elements in the more general building of tables. In each case where an attribute refers to the same format as a CSS property at the same level of the same element, the CSS property takes priority.

A short list of each style-set is given for quick reference though these listings are by no means complete. A link has been provided at the bottom of this drop-list for a full CSS properties reference.

HTML Attributes for Tables; use the format;

attribute1=value1 attribute2=value2 attributeN=valueN

Example               Values                     Element*   Purpose 

align=left**          left,right,center,         T, R, C    positions table or text**            
                      (plus justify for text)               in immediate container 

valign=top****        top, middle, bottom        R, C       vertical alignment of TEXT

border=1*****         0 for none, 1-7            T          all borders at once

cellpadding=5px       0 for none, px, pt, em     T          padding for all cell text
                                                            with one entry      

cellspacing=5px****** 0 for none, px, pt, em     T          between all table cells 
                                                            with one entry 

height=100px***       px, pt, cm, em, %          C          cell height, though likely
                                                            to increase with contents     

width=200px***        px, pt, cm, em, %          T, C       table or cell width

colspan="2"           number of columns.         C          joins cells rightward 

rowspan="2"           number of rows.            C          joins cells downward

*      T=Table, R=Rows, C=Cells of any kind
**     Align in cells applies horizontal text-alignment.
***    If not specified, the dimensions will adjust to the text.
****   If not specified, the default is middle
*****  Do not use border spacing styles with this attribute; only ''cellspacing''.
****** Do not use border styles with this attribute; only the ''border'' attribute.

CSS Style Rules; use the format;

style="property1:value1; property2:value2; propertyN:valueN;"

Example                   Values                     Elements**    Purpose 

caption-side:top          top,right,bottom,          T           only some browsers
                          and left

text-align:right          left,right,center,         T, R, C     horizontal alignment of text
                          and justify 

vertical-align:top        top, middle, bottom        C           Vertical-align text or image

background:yellow         name, rgb, hex,            T, R, C     background color
                          and transparent

color:blue                name, rgb, hex             T, R, C     text color


font-family:arial         font or family name        T, R, C     font or font-list      

font-size:20pt            px, pt, cm, em, %          T, R, C     text size

font-style:italic         italic, normal             T, R, C     text style

font-weight:bold          bold, normal               T, R, C     text weight


padding:5px 0 0 0         px, pt, cm, em             T, C        sequence top,right,bottom,left

margin:0 0 5px 0          px, pt, cm, em, %          T           sequence top,right,bottom,left

border:2px solid red*     width, type, color         T, C        border on all four sides

border-collapse:          separate or collapse       T           cell spacing or not

border-spacing:10px       px, pt, cm, em             T           cell spacing all-round

border-spacing:7px 5px    px, pt, cm, em             T           in form horizontal vertical 

table-layout:fixed        auto or fixed              T           expands with text or not  

width:400px               px, pt, cm, em  %          T, C        sets table or cell width 

height:200px              px, pt, cm, em  %          T, C        sets table or cell height 


line-height:2em***        px, pt, cm, em             T, R, C     height between text lines

letter-spacing:5px        px, pt, cm, em             T, R, C     space between text characters

word-spacing:10px         px, pt, cm, em             T, R, C     space between words of text

white-space:pre-wrap      browser issues             T           long line text wrapping,(soon)


* Separate border properties also exist; border-top,border-right,border-bottom, and border-left.
**   T=Table, R=Rows, C=Cells of any kind
***    Line-height applies only to Block Level Elements; e.g. <blockquote>, <center>,<div>,
      <h1-h6>, <hr>, <ol>, <p>, <pre>, <table>, and <ul>.  Line-height fails within a <span>.

Style Expression Spacing Rules for WIKITEXT

Main Points to Avoid

  • Line breaks are not permitted within style expressions. Let the software do the wrapping.
  • Spaces are not permitted immediately before colons or semi-colons.

These have Latitude

  • Space between the various table symbols and the word style is OK.
  • Space around any equals symbol is OK.
  • Space between the style rules and their outside parentheses is OK.
  • Spaces after colons and semi-colons are OK.
  • A semi-colon can be placed immediately after the last style rule.

In addition

  • Compound values like '2px solid black' must be space-separated.
  • HTML attributes must be separated from CSS style expressions with space.
  • HTML element line-spacing is permitted but not for Wikitext elements.
  • Wikitext and HTML table elements can be indented for clarity.
  • Long lines in code LISTINGS can wrap only if there are some spaces added.

Combining the two style rule methods:

It is possible to mix the attributes with CSS styles provided that they keep to their own local formats. That is to say; nothing with an equals sign between the quotes, and no CSS rules outside of them. Note that the Wiki apostrophe codes and various HTML tags can still be used directly on text. An example of mixed styles is shown below.

{| border=1 width=300px style="background:lightyellow;color:maroon;"
| height=100px| <u>''First''</u> cell
| style="background:black;color:white;" width=200px align=center|''Second'' cell

Priorities for Inline Styles.

When there is a contest at the same level between an attribute and a style, the style will have priority.

When two similar properties exist in a style expression, each having a different value, the second value will be taken.

When there are two entire style expressions in the same table line, the second is ignored. The same situation applies for two similar attributes in a line; the second is ignored.

Refer to CSS Reference List for more detailed descriptions of properties and values.