Pwikip

Overview

Creole 1.0 Markup

Bold and Italics

Headings

Level 2 Whitespace Free

Level 3 Whitespace Everywhere

Links - Internal and External

Paragraphs

Line Breaks

Lists

Horizontal Rule

Image (Inline)

Tables

Nowiki (Preformatted)

Escape Character

Placeholder

Bold and/or Italic Links

Bold, Italics, Links, Inline Nowiki in Lists

Creole Additions

Monospace

Superscript

Subscript

Underline

Indented Paragraphs

HTML Entities

Extensions

Table of Contents

File Listing

HTML

Pragmas

#ftpput

#html and #htmlend

#head and #headend

#charset

#title

#favicon

#description

#keywords

#stylesheet

#javascript

#body and #bodyend

#include

#execute

#comment

Command-Line Arguments

~/.pwikiprc

Downloads

Licence

Source Tarballs

Pwikip is a Creole 1.0 Compliant** plus Creole Additions wikitext parser including a productive selection of pragmas and extensions to facilitate the efficient development, deployment and maintenance of a wikitext based HTML project.

The project is written in Linux shell script and requires GNU Bash as it contains a few bashisms: if [[ regex ]] where a case statement won't do and ${shellvar/substring/replacement} where inserting shellvars with sed and having to escape sed's special characters is cumbersome. A more portable grep could replace the former but it's not a built-in and it would unnacceptably impact performance so there's no reason not to use the latter.

I have not and am not intending to implement free-standing URLs being turned into links because the increased processing and resultant decrease in performance is not justified by isolating and effectively fixing URLs with missing enveloping brackets.

The latest version 0.2.9 manages to fully construct this entire page in 0m12.254s.

The wikitext source code of this page and of all the pages that constitute this website are listed here if you are interested to see how a pwikip project is constructed (you may have to set the page's character encoding to Unicode UTF-8 in your browser).

Creole 1.0 Markup

This is the Creole 1.0 markup:

Bold and Italics

Bold

Creole Compliant .

Sample input:

**Bold text.**

**Bold to end-of-line.

Bold should **be\\able** to cross broken lines.

Bold should **be
able** to cross multiple lines.

Sample output:

Bold text.

Bold to end-of-line.

Bold should be
able
to cross broken lines.

Bold should be able to cross multiple lines.

Italics

Creole Compliant .

Sample input:

//Italic text.//

//Italics to end-of-line.

Italics should //be\\able// to cross broken lines.

Italics should //be
able// to cross multiple lines.

Sample output:

Italic text.

Italics to end-of-line.

Italics should be
able
to cross broken lines.

Italics should be able to cross multiple lines.

Bold Italics

Creole Compliant .

Sample input:

**//Bold italic text.//**

**//Bold italics to end-of-line.

Bold italics should **//be\\able//** to cross broken lines.

Bold italics should **//be
able//** to cross multiple lines.

**//Unacceptable but automatically corrected.**//

Sample output:

Bold italic text.

Bold italics to end-of-line.

Bold italics should be
able
to cross broken lines.

Bold italics should be able to cross multiple lines.

Unacceptable but automatically corrected.

Italic Bold

Sample input:

//**Italic bold text.**//

//**Italic bold to end-of-line.

Italic bold should //**be\\able**// to cross broken lines.

Italic bold should //**be
able**// to cross multiple lines.

//**Unacceptable but automatically corrected.//**

Sample output:

Italic bold text.

Italic bold to end-of-line.

Italic bold should be
able
to cross broken lines.

Italic bold should be able to cross multiple lines.

Unacceptable but automatically corrected.

Headings

Creole Compliant : the rules state that parsing within headings is optional but phrasing content is permitted within a heading so I support it.

The specification doesn't mention anything about the format of links created from the heading text so I've implemented the same format that the http://wikicreole.org/ website is using: invalid characters are removed, then the lowercase characters to the right of any whitespace are converted to uppercase before finally all whitespace is stripped.

Sample input:

=Level 1 Biggest=
==Level 2 Whitespace Free==
 === Level 3 Whitespace Everywhere === 
==== Level 4 Unterminated
 =====Level 5 {{../images/tip.gif}} [[Parsing]] __is__ //supported// =====
======Level 6 Smallest======

Sample output:

Level 1 Biggest

Level 2 Whitespace Free

Level 3 Whitespace Everywhere

Level 4 Unterminated

Level 5 Parsing is supported
Level 6 Smallest

Creole Compliant** : I'm not currently implementing free-standing URLs being automatically turned into links.

Internal

Sample input:

[[../angliasoft]]

[[../angliasoft|Angliasoft]]

[[../mmcoyzx81|{{../mmcoyzx81/images/logo.gif|Mastering Machine Code on Your ZX81 or ZX80}}]]

Sample output:

../angliasoft

Angliasoft

Mastering Machine Code on Your ZX81 or ZX80

External

Sample input:

[[http://www.angliasoft.org.uk/]]

[[http://www.angliasoft.org.uk/|Angliasoft]]

[[http://code.google.com/p/gtkdialog/|{{http://code.google.com/p/gtkdialog/logo?cct=1345562730|Gtkdialog}}]]

Sample output:

http://www.angliasoft.org.uk/

Angliasoft

Gtkdialog

Paragraphs

Creole Compliant .

Sample input:

This is a line of text which will be accompanied by the following line.
This is another line of text which will join the previous line in a paragraph.

This is yet another line of text which will become a paragraph on its own.

Sample output:

This is a line of text which will be accompanied by the following line. This is another line of text which will join the previous line in a paragraph.

This is yet another line of text which will become a paragraph on its own.

Line Breaks

Creole Compliant .

Sample input:

This is the first line,\\and this is the second.

This is the first line,\\
and this is the second.

Sample output:

This is the first line,
and this is the second.

This is the first line,
and this is the second.

Lists

Creole Compliant .

Unordered Lists

Sample input:

* Level 1 item 1 with a URL: [[http://www.woden.org.uk|Woden]]
 * Level 1 item 2
with two additional lines of text underneath
which remain part of the same list item.
  ** **Level 2** item 1 with bold
	*** Level 3 item 1
	 *** Level 3 //item 2// with italics
		  **** Level 4 item 1
 ***** Level 5 item 1 with\\multiple\\line\\\\breaks
  ***** Level 5 item 2 with code: {{{for f in `ls`; do echo $f; done}}}
	**** Level 4 item 2
	 ** Level 2 item 2
		  **** Level 4 item 3 - an unacceptable two level increase parsed as a line of bold text.

Sample output:

  • Level 1 item 1 with a URL: Woden
  • Level 1 item 2 with two additional lines of text underneath which remain part of the same list item.
    • Level 2 item 1 with bold
      • Level 3 item 1
      • Level 3 item 2 with italics
        • Level 4 item 1
          • Level 5 item 1 with
            multiple
            line

            breaks
          • Level 5 item 2 with code: for f in `ls`; do echo $f; done
        • Level 4 item 2
    • Level 2 item 2 ** Level 4 item 3 - an unacceptable two level increase parsed as a line of bold text.

Ordered Lists

Sample input:

# Level 1 item 1 with a URL: [[http://www.woden.org.uk|Woden]]
 # Level 1 item 2
with two additional lines of text underneath
which remain part of the same list item.
  ## **Level 2** item 1 with bold
	### Level 3 item 1
	 ### Level 3 //item 2// with italics
		  #### Level 4 item 1
 ##### Level 5 item 1 with\\multiple\\line\\\\breaks
  ##### Level 5 item 2 with code: {{{for f in `ls`; do echo $f; done}}}
	#### Level 4 item 2
	 ## Level 2 item 2
		  #### Level 4 item 3 - an unacceptable two level increase parsed as a line of monospaced text.

Sample output:

  1. Level 1 item 1 with a URL: Woden
  2. Level 1 item 2 with two additional lines of text underneath which remain part of the same list item.
    1. Level 2 item 1 with bold
      1. Level 3 item 1
      2. Level 3 item 2 with italics
        1. Level 4 item 1
          1. Level 5 item 1 with
            multiple
            line

            breaks
          2. Level 5 item 2 with code: for f in `ls`; do echo $f; done
        2. Level 4 item 2
    2. Level 2 item 2 ## Level 4 item 3 - an unacceptable two level increase parsed as a line of monospaced text.

Horizontal Rule

Creole Compliant .

Sample input:

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

Sample output:




Image (Inline)

Creole Compliant .

Sample input:

{{../images/capsule.gif}}
{{../images/teleport.gif|Teleport!}}

Sample output:

Teleport!

Tables

Creole Compliant .

Sample input:

|={{../images/home.gif|Image}}|=Heading01|=Heading02|=Heading03|=Heading04|=Heading05|
|=Heading10|**Bold**|Row1 Col2|Row1 Col3|Row1 Col4|__Underlined__|
|=Heading20|Row2 Col1|//Italics//|Row2 Col3|,,Sub,,scripted|Row2 Col5|
|=Heading30|Row3 Col1|Row3 Col2|{{{Inline nowiki}}}|Row3 Col4|Row3 Col5|
|=Heading40|Row4 Col1|^^Super^^scripted|Row4 Col3|[[A_URL]]|Row4 Col5|
|=Heading50|##Monospaced##|Row5 Col2|Row5 Col3|Row5 Col4|A line\\break|

|Inline HTML:|»»»<input type="button" value="A Button">«««|
	| Whitespace...	 | ...everywhere	|	 
 | Closing markup... | ...is optional

|1 cell

Sample output:

ImageHeading01Heading02Heading03Heading04Heading05
Heading10BoldRow1 Col2Row1 Col3Row1 Col4Underlined
Heading20Row2 Col1ItalicsRow2 Col3SubscriptedRow2 Col5
Heading30Row3 Col1Row3 Col2Inline nowikiRow3 Col4Row3 Col5
Heading40Row4 Col1SuperscriptedRow4 Col3A_URLRow4 Col5
Heading50MonospacedRow5 Col2Row5 Col3Row5 Col4A line
break
Inline HTML:
Whitespace... ...everywhere
Closing markup... ...is optional
1 cell

Nowiki (Preformatted)

Creole Compliant .

Sample input:

{{{
//This// nowiki block does **not** get [[formatted]].
}}}

This {{{//inline// nowiki **doesn't** get [[formatted]]}}} either.

Sample output:

//This// nowiki block does **not** get [[formatted]].

This //inline// nowiki **doesn't** get [[formatted]] either.

Closing braces in nowiki

Creole Compliant .

Sample input:

{{{
if (x != NULL) {
  for (i = 0; i < size; i++) {
    if (x[i] > 0) {
      x[i]--;
  }}}
}}}

{{{if (a>b) { b = a; }}}}

Sample output:

if (x != NULL) {
  for (i = 0; i < size; i++) {
    if (x[i] > 0) {
      x[i]--;
  }}}

if (a>b) { b = a; }

Escape Character

Creole Compliant** : I'm not currently implementing the escaping of HTML entities.

Sample input:

~# Not an unordered list item, ~__not underlined~__, ~## not monospaced ~##.

{{{~^^Ignored {inside~^^}}}} {{{~,,inline nowiki~,,}}} and »»»~##HTML~##«««.

~**Not bold~**, http://www.users.waitrose.com/~thunor/, ~// not italic ~//.

~[[Not an internal URL]], ~[[http://wikicreole.org/|not an external URL]].

This is a tilde escaping itself ~~__which then doesn't escape underlined.

This is a tilde alone ~ and ~these aren't~ ~escaping~ anything ~

{{{
~**Ignored inside a ~##nowiki block.
}}}

»»»
~//Ignored inside an ~~^^HTML block.
«««

~| Not | a | table |

~----

Sample output:

# Not an unordered list item, __not underlined__, ## not monospaced ##.

~^^Ignored {inside~^^} ~,,inline nowiki~,, and ~##HTML~##.

**Not bold**, http://www.users.waitrose.com/~thunor/, // not italic //.

[[Not an internal URL]], [[http://wikicreole.org/|not an external URL]].

This is a tilde escaping itself ~which then doesn't escape underlined.

This is a tilde alone ~ and these aren't~ escaping~ anything ~

~**Ignored inside a ~##nowiki block.
~//Ignored inside an ~~^^HTML block.

| Not | a | table |

----

Placeholder

N/A

Creole Compliant .

Sample input:

**[[http://www.murga-linux.com/puppy]]**

//[[http://www.murga-linux.com/puppy|Puppy Linux Discussion Forum]]//

**//[[http://www.wikicreole.org/]]//**

//**[[http://www.wikicreole.org/|WikiCreole: Home]]**//

Sample output:

http://www.murga-linux.com/puppy

Puppy Linux Discussion Forum

http://www.wikicreole.org/

WikiCreole: Home

Bold, Italics, Links, Inline Nowiki in Lists

Creole Compliant .

Sample input:

* **Bold text**
## //Italic text//
*** **//Bold italic text//**
#### //**Italic bold text.**//
#### **[[../angliasoft]]**
*** //[[../angliasoft|Angliasoft]]//
## **//[[http://www.angliasoft.org.uk/]]//**
* [[http://www.angliasoft.org.uk/|**Anglia**//soft//]]

Sample output:

Creole Additions

This is the Creole Additions markup:

Monospace

Creole Compliant .

Sample input:

##Monospaced text.##

##Monospaced to end-of-line.

Monospace should ##be\\able## to cross broken lines.

Monospace should ##be
able## to cross multiple lines.

Sample output:

Monospaced text.

Monospaced to end-of-line.

Monospace should be
able
to cross broken lines.

Monospace should be able to cross multiple lines.

Superscript

Creole Compliant .

Sample input:

^^Superscripted text.^^

^^Superscripted to end-of-line.

Superscript should ^^be\\able^^ to cross broken lines.

Superscript should ^^be
able^^ to cross multiple lines.

Sample output:

Superscripted text.

Superscripted to end-of-line.

Superscript should be
able
to cross broken lines.

Superscript should be able to cross multiple lines.

Subscript

Creole Compliant .

Sample input:

,,Subscripted text.,,

,,Subscripted to end-of-line.

Subscript should ,,be\\able,, to cross broken lines.

Subscript should ,,be
able,, to cross multiple lines.

Sample output:

Subscripted text.

Subscripted to end-of-line.

Subscript should be
able
to cross broken lines.

Subscript should be able to cross multiple lines.

Underline

Creole Compliant .

Sample input:

__Underlined text.__

__Underlined to end-of-line.

Underline should __be\\able__ to cross broken lines.

Underline should __be
able__ to cross multiple lines.

Sample output:

Underlined text.

Underlined to end-of-line.

Underline should be
able
to cross broken lines.

Underline should be able to cross multiple lines.

Indented Paragraphs

Creole Compliant .

The specification doesn't mention anything about indented nowiki blocks but I've implemented them.

Sample input:

:This **paragraph** is indented to level 1.
::This paragraph is //indented// to level 2.
:::This {{{paragraph}}} is indented to level 3.
::::This paragraph is [[indented]] to level 4.
:::::This __paragraph__ is indented to level 5.

Sample output:

This paragraph is indented to level 1.

This paragraph is indented to level 2.

This paragraph is indented to level 3.

This paragraph is indented to level 4.

This paragraph is indented to level 5.

Sample input:

:{{{
This **nowiki** block is indented to level 1.
}}}
::{{{
This nowiki block is //indented// to level 2.
}}}
:::{{{
This {{{nowiki}}} block is indented to level 3.
}}}
::::{{{
This nowiki block is [[indented]] to level 4.
}}}
:::::{{{
This __nowiki__ block is indented to level 5.
}}}

Sample output:

This **nowiki** block is indented to level 1.
This nowiki block is //indented// to level 2.
This {{{nowiki}}} block is indented to level 3.
This nowiki block is [[indented]] to level 4.
This __nowiki__ block is indented to level 5.

HTML Entities

HTML entities can be inserted into a page by simply entering them as is.

Sample input:

&thorn; &hearts; &euro; &copy; &equiv; &#254; &#9829; &#8364; &#169; &#8801;

{{{&thorn; &hearts; &euro; &copy; &equiv; &#254; &#9829; &#8364; &#169; &#8801;}}}

Sample output:

þ ♥ € © ≡ þ ♥ € © ≡

&thorn; &hearts; &euro; &copy; &equiv; &#254; &#9829; &#8364; &#169; &#8801;

Extensions

The plugin/extension markup is Creole Compliant .

Table of Contents

Sample input:

<<TableOfContents>>
<<TableOfContents title="Contents">>
<<TableOfContents float='left'>>
<<TableOfContents limit="4">>
<<TableOfContents width='100%'>>
<<TableOfContents title='Overview' float="right" limit='3' width="200px">>

Sample output:

The bottom example shown above represents the Table of Contents at the top of this page.

File Listing

<<FileListing>>
<<FileListing title="Packages">>
<<FileListing columns='2'>>
<<FileListing indent="5">>
<<FileListing command='ls *.gz'>>
<<FileListing width="75%">>
<<FileListing image="compressed.png">>
<<FileListing alternate="yes">>
<<FileListing links="yes">>
<<FileListing title="Project Wiki Files" command='find ../ -maxdepth 2 -name "*.wiki" | sort'
	image="../images/file.gif" alternate="true" links="true">>

Sample output demonstrating the bottom example shown above:

Project Wiki Files
../code/index.wiki ../code/namedpipesfifoipc.wiki ../extinct/index.wiki
../fltetravex/index.wiki ../friq/index.wiki ../gnurobbo/index.wiki
../i2008.wiki ../i2009.wiki ../i2010.wiki
../index.wiki ../jsataxx/index.wiki ../jscb/index.wiki
../jspp/index.wiki ../pipepanic/index.wiki ../pwikip/index.wiki
../rbvba/index.wiki ../tmp/index.wiki ../vintagemags/index.wiki

HTML

How could you not want this feature! Useful for inserting JavaScript amongst many other things.

The characters I've chosen are guillemets which can be reached on a UK keyboard [with Linux] using AltGr+z and AltGr+x or AltGr+[ and AltGr+] on a US keyboard.

Sample input:

»»»
<p><strong>This</strong> <em>is</em> <code>a</code> <a href="block">block</a><br>
<u>of</u> <sup>raw</sup> <sub>HTML</sub> <tt>code</tt>.<p>
«««

Inline HTML: »»»<input type="button" value="A Button">«««

»»»
<script language="JavaScript" type="text/javascript">
	var d=new Date();
	document.write("<p>" + d + "<\/p>");
</script>
<noscript><p>JavaScript is disabled in your browser.</p></noscript>
«««

Sample output:

This is a block
of raw HTML code.

Inline HTML:

Pragmas

Some of these are [unintentionally] similar to MoinMoin's which means I'm on the right wavelength, but mostly they are custom.

#ftpput

This will by default ftp-put the target HTML file on completion although you can specify any number of files. The ftp account information is read from either the ~/.pwikiprc file or from the command-line at start-up.

Examples:

#ftpput
#ftpput index.html
#ftpput index.html index.wiki
#ftpput index.* css/stylesheet.css

#html and #htmlend

Inserts the HTML tags <html> or </html> into the page. An open html tag will be closed automatically if the page ends therefore the closing tag is optional.

Examples:

#html
#htmlend

#head and #headend

Inserts the HTML tags <head> or </head> into the page. An open head tag will be closed automatically if a body tag is opened in which case the closing tag is optional.

Examples:

#head
#headend

#charset

Specifies the page's character encoding . If required, this must go inside the head section.

Examples:

#charset UTF-8
#charset ISO-8859-1

#title

Specifies the page's title . This is mandatory inside a head section but it can be blank.

Example:

#title Pwikip Creole 1.0 Compliant** Wikitext Parser

#favicon

Specifies the page's icon . If required, this must go inside the head section.

Examples:

#favicon favicon.ico
#favicon images/favicon.ico
#favicon ../images/favicon.ico

#description

Specifies the page's description . If required, this must go inside the head section.

Example:

#description Pwikip Creole 1.0 Compliant** wikitext parser written in Linux shell script

#keywords

Specifies the page's keywords . If required, this must go inside the head section.

Example:

#keywords Pwikip, Creole 1.0, Creole Additions, wikitext parser, shell script

#stylesheet

Specifies the stylesheet(s) to import. If required, this must go inside the head section.

Examples:

#stylesheet stylesheet.css
#stylesheet css/stylesheet1.css css/stylesheet2.css
#stylesheet ../css/*.css

#javascript

Specifies the JavaScript(s) to import. If required, this would normally go inside the head section.

Examples:

#javascript javascript.js
#javascript js/javascript1.js js/javascript2.js
#javascript ../js/*.js

#body and #bodyend

Inserts the HTML tags <body> or </body> into the page. An open body tag will be closed automatically if the page ends therefore the closing tag is optional.

Examples:

#body
#bodyend

#include

Specifies one or more files to include. The file(s) must contain HTML, not wikitext markup.

Examples:

#include file.html
#include includes/file1.html includes/file2.html
#include ../includes/*.html

#execute

Specifies a command to execute. The output must contain HTML, not wikitext markup.

Sample input:

#execute echo "<p>Last updated:"; date; echo "</p>"

Sample output:

Last updated: Fri Jun 7 16:37:27 BST 2013

#comment

This is a wikitext comment which won't be written to the target file.

Example:

#comment This is a wikitext comment which won't be written to the target file.

Command-Line Arguments

Most of these have rcfile equivalents (see ~/.pwikiprc below).

Pwikip Creole 1.0 Compliant** Wikitext Parser version 0.2.9
Usage: build [OPTION] [file or folder]

  -b, --beep                 beep when finished
  -c, --comment              comment the output
      --enable-ftp=state     enable/disable ftp
      --ftp-host=address     set ftp host address
      --ftp-port=number      set ftp port number
      --ftp-root=folder      set ftp base folder
      --ftp-username=user    supply ftp username
      --ftp-password=pass    supply ftp password
  -r, --recursive            recurse subfolders

Pass [./]path/to/folder to process all files within a folder
Pass [./]path/to/file to process one file only

~/.pwikiprc

This is Pwikip's rcfile -- created on first run -- which contains options comparable to the command-line options above. If you wish to store your ftppassword within the rcfile then do so and Pwikip will obfuscate it the next time it's run.

## Simply uncomment and set the options you want.
#optionbeep=1
#optioncomment=1
#optionenableftp=1
#ftphost=
#ftpport=
#ftproot=
#ftpusername=
#ftppassword=

Downloads

Licence

GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007

Source Tarballs