Proposed Language Extension for coWiki

Paul Hanchett, March 29 2005

Rather than try to extend wiki-text to include sophisticated formatting, we will make wiki-text an easy to use (default) subset of a more powerful set of language.

In this way, a user will be able to select the easiest to use formatting language that accomplishes their purpose. As they desire more sophisticated formatting, they will be naturally drawn to use the more powerful language constructs. Availability of those constructs will be controlled by the site administrator.

Editing Text

coWiki presently attempts to save and redisplay text which the parser does not understand. This behavior should be changed so that if text cannot be parsed, it will be immediately redisplayed for correction by the user. If corrected text is not saved, the original text of the page will be retained because the modified text was never stored.

CoWiki's implementation of wiki-text

The current implementation of wiki-text as exemplified in the Boron release does not have to change, beyond extensions mentioned later in this document. However, two suggestions do seem to be in order:

1.      Currently, matched pairs of single characters indicate formatting commands. For example, /italic/ becomes italic. This should be changed so that repeated characters indicate formatting, to reduce the liklihood of a clash with desired text. In this case then, **bold** becomes bold.

2.      These special formatting sequences should be escaped by repetition without intervening space. For example, to write *bold* enter ****bold****. To enter *bold* enter ** *bold* **.

Here is the resulting coWiki markup language:

Style

Command

Effect

Headings 1..6

+ H1

++ H2

+++ H3

++++ H4

<h1>H1</h1>

<h2>H2</h2>

<h3>H3</h3>

<h4>H4</h4>

Lists 1..4 levels

* Item 1

** Item 1a

** Item 1b

* Item 2

·         Item 1

o       Item 1a

o       Item 1b

·         Item 2

Numbered lists

# Item 1

## Item 1a

## Item 1b

# Item 2

1.      Item 1

a.       Item 1a

b.      Item 1b

2.      Item 2

Horizontal Rule

---

--------------------------

Emphasis

**bold**

__underline__

//italics//

==fixed==

--strikeout--

Bold

Underline

Italics

Fixed

strikeout

Links

http: //www.cowiki.org

((www.cowiki.org))

((www.cowiki.org)(coWiki))

…and so on…

http://www.cowiki.org

www.cowiki.org

coWiki

Variable substitution

%MODIFIED%

29 Mar 2005 14:20

The following current commands are based on html syntax

Line break

<br>, <br/>

Line break, <br>

Subscript

CH<sub>3</sub>COOH

CH3COOH

Superscript

e = mc<super>2</super>

e = mc2

Preformatted text

<pre>
pre
formatted 
text
</pre>

pre
formatted 
text

Code Boxes

<code>
for i = 1 to 5
  print i
next i
print
</code>

for i = 1 to 5
  print i
next i
print

 

Posting

<posting>
Somebody wrote:
 
> Quoting level 1
>> Quoting level 2
| >>  Quoting level 3
</posting>
Somebody wrote:
 
> Quoting level 1
>> Quoting level 2
| >>  Quoting level 3 

 

Quote

<q>
Quoted text appears indented and cannot be nested.
</q>

Quoted text appears indented and cannot be nested.

Table of Contents

<toc>

Generates and inserts a TOC for the document.

The following new tags are proposed to be introduced

Justification

<left>This text is left justified</left>

<right>This text is right justified</right>

<center>This text is center justified</ center >

<fill> This text is fill justified even though it’s not clear to me how to do it on the web </fill>

This text is left justified

This text is right justified

This text is center justified

This text is fill justified even though it’s not clear to me how to do it on the web.

 

Emphasis

<b>bold</b>

<u>underline</u>

<i>italics</i>

<fixed>fixed</fixed>

< strikeout>strikeout
</ strikeout>

Bold

Underline

Italics

Fixed

Strikeout

Include images

<image url=… align=… />

Image appears in text

Include a web page

<URL >

Text of referenced page is merged with coWiki page.

 

Changes to table format

Currently coWiki introduces tables with <table> and </table> tags, rows are delimited by EOLN, and fields are separated by pipe.  This format works well for simple tables with limited content, but would be completely unmanageable to represent the preceeding table.  We propose here two minor extensions that will make table more serviceable, but recommend that difficult table formatting be done in html with an editor.

 

Table headings are indicated on lines beginning with “^”, no previous <table> tag is required to introduce a table.  The fields of the heading are separated by “^” and the heading list ends with the EOLN character.  Table headings may be specially formatted and default to center justification.

 

Similarly, row data is introduced by lines beginning with “|” and is separated by “|”.  Data for each row ends with the EOLN.  If a row does not contain enough data for the width of the table, the remainder of the row is assumed to be blank.  If a row contains too much data, it (probably) spills over the edge of the table.  Potentially the parser can detect data underflow and overflow…  In a data row, character data should left justify and numeric should right justify by default.

 

Justification of headings and data can be adjusted by using the left/right/center/fill tags introduced above.

 

Security

Security will be maintained by allowing the site adminstrator to determine whether or not particular language features are allowed. Initially, it will be possible to enable or disable a language feature for all users of the site.

Eventually, the ability to save text with a particular language construct can be associated with membership in a security group. A user not assigned to the language's security group will not be able to modify a page containing that language, nor will they be able to save a page that invokes the language.

For languages like HTML it may be possible to provide lists of tags to be allowed (or disallowed).

Language Processing Instructions:

At the core of this extension is creating language processing instructions that can be included in the text of the wiki page to change the interpretation of the following text. These instructions begin with <? followed by a tag that identifies a processing language. The scope of a language selection is concluded by a matching >?.

Processing instructions may be nested, and at the conclusion of the scope of one instruction, the previous enclosing instruction will become effective.

1.      The default processing language is wiki-text

2.      Alternate languages are introduced and concluded with a <?language ... ?> processing instruction. The content of each language section is represented internally as an XML node. Language sections are allowed to nest.

Language

Instruction

XML representation

Wiki-text

Default; also <?cowiki ... ?>

<language-cowiki> ... </ language-cowiki>

HTML

<?html ... ?>

<language-html> ... </language-html>

PHP

<?php ... ?>

<language-php> ... </language-php>

 

In the future, all coWiki pages should be stored with a root tag that indicates the starting language type.  If the root tag does not indicate a language, it will be assumed to be wiki-text.

Processing Assumptions