Introduction
- Usage in Ruby
- Pros and Cons
  - Why you should use it
  - Why you shouldn't use it
Base elements
Placeholder
Inclusions
- Images
Plugins
- Footnotes and Footnote groups
  - Your own labels
  - Multiple footnote groups
- Inline Ruby

Introduction

Creole is a common wiki markup language to be used across different wikis. More about Creole can be found at http://www.wikicreole.org/

I decided to implement a creole-interface creole2doc for my docgenerator.

This is a short description, on how to use this creole2doc-implementation.

There is always the code and the result:

Sourcecode and result

Sourcecode and result

One remark: creole2doc is no Wiki! It is a document generator, based on docgenerator.rb, using the creole wiki syntax. So there are some differences in linking. There are no Inter-wiki-links (there is no wiki). But there are links to other files on your file system.

Usage in Ruby

You can create ruby scripts to generate documents. One big advantage: You have one source and you can build HTML or LaTeX-files.

Example:

require 'creole/creole2doc'
doc = Creole_document.new(
  :title => 'A not so short introduction to Creole',
  :shorttitle => 'Creole',
  :with_toc => true
)
#Add the content
doc << DATA
#File.open('wiki.txt'){|file| doc << file } 
doc.save('creole.html')
doc.save('creole.tex') #build the LaTeX-code

__END__
=Document start
Here is your wiki text.

Remarks:

The content after __END__ is not part of the script. (Just think in matter of a here-document) You could also read the content from a file as in the comemnted part of the script.
There is a runtex-script which allows an automatic translation to pdf (if LaTeX is installed)

Pros and Cons

Why you should use it

You can create HTML and/or LaTeX (and plain text, wikimedia wiki and perahps later creole).
You can extend it as you need it.
You can ask for new features if you need it.

Why you shouldn't use it

Well, you can use it. There are some restrictions:

This tool supports the features I need and how I expect it. There is no guarantee that is supports the features you need and how you expect how it should work.
Up to now, it's only tested on windows. I expect some problems with encodings.
The HTML is not really proper. Some Problems:
- Encoding - there is no special handling. It works for my tests ;-)
- HTML-version. It's not strickly handled. you can get <br>}}} oder {{{<br/>

Base elements

Sections

Sections are defined by = at the start of a line.

Differences to creole-standard:

There is an optional label for the sections.

The level for the section are following the rule:

0 ⇒ nil
1 ⇒ :h1
2 ⇒ :h2
3 ⇒ :h3
4 ⇒ :h4
5 ⇒ :h5
6 ⇒ :h6

This rule can by modified by the option :title_levels

You can build a table of contents from your wiki-text. The table of contents will be a nested list with all heading entries. Details see ruby docuemntation.

Generell Markup

Paragraphs and Linebreaks

With an empty line you get different paragraphs.

This is the second paragraph

With an empty line you get different paragraphs.

This is the second paragraph

Manual Line breaks

Two backslashes create a newline\
TeX-useres are welcome ;-)

Two backslashes create a newline
TeX-useres are welcome ;-)

(Here's a little problem with the two backslashs and the display in the source. There are really two \ in the source)

Text

You can make things **bold** or //italic// 
or **//both//** or //**both**//.

You can make things bold or italic or both or both.

Separator line

----

Lists

*one
*two
*three

one
two
three

#one
#two
#three

one
two
three

Mixages are possible:

*one
*#one-one
*#one-two
*two
*#two-one

one
1. one-one
2. one-two
two
1. two-one

Links

http://ruby.lickert.net

[[http://ruby.lickert.net|My Ruby page]]

[[#links|Page internal link]]

http://ruby.lickert.net

My Ruby page

Page internal link

Verbatim/no Wiki

{{{
Use three curly brackets for original code
}}}

Use three curly brackets for original code

Easy Tables

Creole allows to build some easy tables.

|=header col1|=header col2| 
|col1|col2| 
|you         |can         | 
|also        |align\ it. |

header col1	header col2
col1	col2
you	can
also	align it.

I don't recommend this tables. I prefer a solution with placeholders

Placeholder

When there is something advanced, a placeholder will show up, so users will not be confused seeing more than one syntax. (optional for wiki developers)

⇒ http://www.wikicreole.org/wiki/Creole1.0#section-Creole1.0-Placeholder

Special rule: After the >>> you have to add which placeholder you work with.

Placeholder or often used in creole2doc.

html: Output only for HTML.
latex: Output only for LaTeX.
tables/tabulars

under development:

Rail-diagramms
Structogramms
...

Restricted Wiki text

Wiki text only for LaTeX

Example:

  <<<latex
  \textbf{This}  is only for LaTeX.
  >>>

Wiki text only for HTML

  <<<html
  <em>This</em>  is only for HTML.
  >>>

This is only for HTML.

Your own placeholders

With a bit of Ruby-Knowlwdge you can define your own placeholders.

For this document I created a 'testcase'-placeholder to compare the code and the result.

class Creole_testcase < Creole_placeholder
  #Return content only for html
  def to_doc( target, options = {})
    [
      element(:div,{ :class => 'source'}, element(:verbatim,{},@source.join)),
      element(:div,{ :class => 'result'}, Creole.new( :content => @source.map{|x|x.sub(/^\s*(\S)/,'')}.join )),
      element(:br, :clear => 'all'),
    ].to_doc( target, options)
    
  end  
end #Creole_html 
wiki = Creole.new()
wiki.placeholders['testcase'] = Creole_testcase

Tables similar to Wikimedia

Creole allows also to build easy tables

I prefer the Wikimedia syntax for tables. To provide LaTeX-tables some additional informations are available.

  before **a**
  <<<tabular
  |!columns=3
  |!columndescription=ccc
  |=1
  |=2
  |=3
  |-
  |eins
  |zwei
  |drei
  |-
  |one
  |two
  |three
  >>>
  after

before a

1	2	3
eins	zwei	drei
one	two	three

after

CSV-tables

Not realized up to now.

Inclusions

Inclusions are things that are included in your resulting document.

According the creole-standard 1.0 this are mainly pictures. I extended it by more features for my personal use. Other extensions are built in as Plugin

All extensions are build in the same way:

  {{key}}
  {{key|description}}
  {{key|description|opt1=xxx|opt2=yyyy}}

You have a key for the inclusion, then a description and afterwords a list of options. Description and options are optional.

Images

Images are added quite simply:

{{Red_Flower.jpg}}

{{Red_Flower.jpg|red flower}}

red flower

The description is used as "alt"-text.

In addition to the creole 1.0 standard you can use additional options.

Add CSS-information

You can add some css-information for the image:

{{Red_Flower.jpg|red flower|css=width:50px}}
{{Red_Flower.jpg|red flower|imgcss=width:100px}}

red flower

There is no difference between the option css and imgcss.

Add CSS-classes

Instead of direct css you can define a class:

{{Red_Flower.jpg||class=img100}}

{{Red_Flower.jpg||imgclass=img100}}

This makes sense if you add something like

<style>
img.img100 { width: 100; border: double; border-color: green; }
</style>

Aligment, width, link

You can define aligment and width via the css-command:

{{Red_Flower.jpg|red flower|css=width:50px;float:left}}

Links can be added also:

[[<<yourlink>>|{{Red_Flower.jpg|red flower}}]]

Plugins

Plugins are parts of the wiki, where the usage is no Creole-standard, but the definition corresponds to the standard.

All plugins are build in the same way:

  <<key>>
  <<key|description>>
  <<key|description|opt1=xxx|opt2=yyyy>>

You have a key for the plugin, then a description and afterwords a list of options. Description and options are optional.

http://www.wikicreole.org/wiki/Plugin

Footnotes and Footnote groups

You can add footnotes to your text. With footnotes you get the footnotes.

Hi<<footnote|Remark one>>

Hi again!<<footnote|Remark two>>
----
<<footnotes>>

Hi¹

Hi again!²

¹Remark one
²Remark two

The output of the footnotes makes no sense with LaTeX. ¹

Your own labels

If you want, you can define your own label:

<<footnote|This is a footnote|label=mylabel>>

^mylabel

This works only for HTML, not LaTeX

Multiple footnote groups

If you need it, you can build different groups of footnotes.

One usage could be footnotes inside tables. You could build a group for this footnotes and print it after the table. In LaTeX you don't need this groups, with minipages you get this feature automatic.

Hi<<footnote|This is a footnote>>

Hi again!<<footnote|This is another footnote|groupid=other>>

----
<<footnotes>>
----
<<footnotes|other>>

Hi¹

Hi again!¹

¹This is a footnote

¹This is another footnote

¹LaTeX is already putting the footnotes to the text.
²Don't forget: eval is evil

Inline Ruby

You can add Inline-Ruby in your creole Code. There are two different variants.

Raw data

The rubycode is added unchanged to the wiki.

1 + 1 = <<ruby_raw|1+1>>

1 + 1 = 2

Parsed data

The ruby code is parsed by the wiki before it is added:

1 + 1 = <<ruby|1+1>>

Countdown: 
<<ruby|(1..10).to_a.reverse.join("-")>>

1 + 1 =

Countdown:

10-9-8-7-6-5-4-3-2-1

Just to explain the output: The command part of the plugin is executed (with eval²) . The result is used as input to the wiki and is parsed by the wiki. And so you get new paragraphs for the result.

An example for the usage

Just one example for the usage:

<<ruby_raw|File.readlines('mydata.txt')>>

This wiki-code will load and display the content of the file mydata.txt.

A not so short introduction to Creole and Creole2doc