Conventional Plaintext Language

Home Download Documentation plain2html


How to use COPL?

COPL can be used either as webserver-plugin or as standalone interpreter.
When you set it up as plugin for your webserver, COPL is to interpret all requested COPL-source-files just-in-time, generate HTML-code and send this code to the visitor.
However, you also can use the COPL-interpreter to create static HTML-files out of COPL-source-files manually. You simply execute a command like "./copl --nohttp test.copl >test.html".

Probably the webserver-plugin is more interesting than the standalone-usage of COPL. However, setting up COPL as webserver-plugin also means more work, especially since I haven't written an Apache module yet.


How does COPL work?

First of all, I want to describe what the COPL-interpreter does when interpreting a COPL-source-file.
The COPL-source-file must be very normal plain text file. Unfortunately, other character encodings than ISO-Latin (such as UTF-8) might produce problems.

The COPL-interpreter recognizes a number of different basic document-elements:

Paragraphs and lists are recognized by common conventions: A paragraph usually is surrounded by empty lines. Lists usually start with a tab followed by a list-item (such as '*', 'o' or '-'), followed by a space and then a line.
Headings and horizontal rows must be compliant with very simple COPL-specific text-formatting-rules. As in wikipedia, a line just containing four hyphens ("----") creates a horizontal row (in HTML "<hr />"). In HTML there are six types of different headings, ranging from "<h1>" to "<h6>". To create a "<h1>"-heading in COPL, your line must begin and end with a single equal sign ('='). To create a "<h6>"-heading, your line must begin and end with six equal signs. For example, the line "===The third-largest heading===" creates a "<h3>"-heading.

You probably have recognized that HTML gives you much more possibilities than these four basic document-elements recognized by COPL, for example tables. For this reason, it is easy to implement real HTML-code within a COPL-document. A line just containing "<!HTML>" marks the beginning of such an HTML-block; a line just containing "<!/HTML>" marks the ending of the HTML-block.

After having divided the document into these different elements, the COPL-interpreter has a look at each line independently to do these things:

Including links and images is quite similar to normal HTML. A link is written "< !url http://bla.de/bla.html Description>" (without the space between '<' and '!'). The description is optional; if you leave it out the URL itself will be used as description. An image can be included with "< !img bla.jpg Description>" (without the space between '<' and '!'). The description is optional; no description will be set if you leave it blank.
The COPL-interpreter also replaces a large number of special characters with their respective HTML-entities (e.g. 'ä', 'ö', 'ß', '&' and so on). It also replaces '<' and '>' with their respective HTML-entities which means that you cannot simply implement HTML-tags. You have to escape them with the usual escape character, the backslash ('\'). This means that the code "\<code\>" results in the HTML-tag "<code>". If you want to write a backslash itself, you again have to escape it. This means that the code "\\" results in a single backslash "\".
The classic different types of text-formatting are bold, italic and underlined text. To mark one or more words as bold, the phrase must be surrounded by two pairs of asterisks (e.g.: "a bold word"). Analogical an italic word or sentence is created by surrounding it by two pairs of slashes (e.g.: "an italic word") and an underlined word or sentence is created by surrounding it by two pairs of underscores (e.g.: "an underlined word"). If you want a pair of asterisks, slashes or underscores not to be interpreted as beginning/ending of a bold, italic oder underlined phrase, you must escape them. Again, this is done with the backslash.


How to set up COPL as webserver-plugin?

Apache 2: a CGI-program and some configuration
This is one way to install COPL as webserver-plugin. With the Apache-configuration-commands "AddHandler" and "Action" all requests to ".copl"-files are forwarded to a CGI. This CGI calls the COPL-interpreter on the given file.

Webserver-independent: a workaround in PHP
This method does not require access to the webserver-configuration, but it requires PHP. I'm using this method at this homepage.
Check the code of the index.php. The index.php simply invokes the COPL-interpreter on the given filename which is located in the directory content/.
Since I prefered requests like "index.php/home.copl" to requests like "index.php?home.copl", I'm using $_SERVER["PATH_INFO"] in the index.php. Additionally, I had to add a .htaccess-file.


Is this homepage written in COPL?

Yes, of course. I've used the webserver-independent workaround with an index.php and an .htaccess-file, since I don't have any access to the Apache configuration at the SourceForge-servers.
The COPL-source-files are located here and this is the stylesheet.



Christoph Schwering · schwering@gmail.com