Home

derdon edited this page Dec 24, 2010 · 14 revisions
Clone this wiki locally

Roundy — the first round markup language!

A simple example

Create a file called test.rd with the following content:

(html
    (head
        (title))
    (body
        (h1)))

Use roundy.py to convert this file's content into XHTML:

roundy.py --filename test.rd
<html><head><title></title></head><body><h1></h1></body></html>

This doesn't look very pretty, let's activate the pretty-printing mode:

roundy.py --filename test.rd --pretty
<html>
  <head>
    <title>
    </title>
  </head>
  <body>
    <h1>
    </h1>
  </body>
</html>

Note: the option -p is an alias for the option --pretty. In the following examples, I will always use this option to make the output more readable.

You should see that there are two things missing in the output: a doctype and some text (a title and the headline). The following section shows how to add a doctype and after that, I'll show you how to insert text (or more general, the content between a start tag and an end tag) in your roundy documents.

Adding a doctype

Adding a doctype to your roundy documents is very easy, here is an example to demonstrate it:

(html
    (doctype "html5")
    (head
        (title))
    (body
        (h1)))

This will be rendered to the following output:

<!DOCTYPE HTML>
<html>
  <head>
    <title>
    </title>
  </head>
  <body>
    <h1>
    </h1>
  </body>
</html>

As you can see, a doctype is added by assigning the attribute doctype a specific value. The following table shows the allowed values for doctype and its resulting strings.

value doctype string
html or html-strict
<!DOCTYPE HTML "-//W3C//DTD HTML 4.01//EN"
html-transitional
<!DOCTYPE HTML "-//W3C//DTD HTML 4.01 Transitional//EN"
html-frameset
<!DOCTYPE HTML "-//W3C//DTD HTML 4.01 Frameset//EN"
html5 <!DOCTYPE HTML>
xhtml or xhtml-strict
<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN"
xhtml-transitional
<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Transitional//EN"
xhtml-frameset
<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Frameset//EN"
xhtml11
<!DOCTYPE html "-//W3C//DTD XHTML 1.1//EN"

Adding text

To add content between a specific start tag and its corresponding end tag, you have to assign it a special attribute. Per default, this attribute is called text. After having added some text to our example file, it will look like this:

(html
    (doctype "html5")
    (head
        (title
            (text "a first attempt")))
    (body
        (h1
            (text "boom, a headline!"))))

Output:

<!DOCTYPE HTML>
<html>
  <head>
    <title>
      a first attempt
    </title>
  </head>
  <body>
    <h1>
      boom, a headline!
    </h1>
  </body>
</html>

CLI reference

-f FILENAME, --filename FILENAME
  path to the file which has to be parsed. (default: STDIN)
-t TEXT_ATTRIBUTE, --text-attribute TEXT_ATTRIBUTE
  the name of the attribute to use for marking text (default: "text")
-p, --pretty Enable pretty printing of the HTML output (disabled per default)
-i INDENT, --indent INDENT
  The number of spaces to use for indenting the output (only used in combination with the option -p --pretty). Only values which are greater than or equal to 0 will take effect (because negative indentations do not make any sense). The default value is 2.
-o OUTPUTFILE, --outputfile OUTPUTFILE
  write the output to the file OUTPUTFILE instead of STDOUT