Editing Wikitext/Preformatted Text
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;
<pre> The time has come the walrus said to speak of many things... </pre>
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.
- 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.
| HTML Tag Format | Literal Tag Format |
|---|---|
| <pre> | <pre> |
| </pre> | </pre> |
| <nowiki> | <nowiki> |
| </nowiki> | </nowiki> |
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... </pre>
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...
</pre>
|}
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.
- 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:
<poem>
One, two, three, four, five,
Once I caught a fish alive.
Six, seven, eight, nine, ten,
Then I put it back again...
</poem>
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...
</poem>
|}
The result is;
One, two, three, four, five, |
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%
|
<poem>
<nowiki>
The code block goes here...
</nowiki>
</poem>
|}
An example of such a display is just:
|
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.
- 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...
</syntaxhighlight>
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>
<tr>
<td style="padding:10px;"> This is cell 1 text </td>
<td style="padding:10px;"> This is cell 2 text </td>
</tr>
</table>
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).
</syntaxhighlight>
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...
</source>
|}
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 <source>. This is still supported, but <syntaxhighlight> may help avoid conflicts if your source code itself contains <source> 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.
|
