#!/usr/bin/env python
# -*- coding: utf-8 -*-
# created by Massimo Di Pierro
# recreated by Vladyslav Kozlovskyy
# license MIT/BSD/GPL
import re
import urllib
from cgi import escape
from string import maketrans
try:
from ast import parse as ast_parse
import ast
except ImportError: # python 2.5
from compiler import parse
import compiler.ast as ast
"""
TODO: next version should use MathJax
"""
__all__ = ['render', 'markmin2html', 'markmin_escape']
__doc__ = """
# Markmin markup language
## About
This is a new markup language that we call markmin designed to produce high quality scientific papers and books and also put them online. We provide serializers for html, latex and pdf. It is implemented in the ``markmin2html`` function in the ``markmin2html.py``.
Example of usage:
``
m = "Hello **world** [[link http://web2py.com]]"
from markmin2html import markmin2html
print markmin2html(m)
from markmin2latex import markmin2latex
print markmin2latex(m)
from markmin2pdf import markmin2pdf # requires pdflatex
print markmin2pdf(m)
``
====================
# This is a test block
with new features:
This is a blockquote with
a list with tables in it:
-----------
This is a paragraph before list.
You can continue paragraph on the
next lines.
This is an ordered list with tables:
+ Item 1
+ Item 2
+ --------
aa|bb|cc
11|22|33
--------:tableclass1[tableid1]
+ Item 4
-----------
T1| T2| t3
===========
aaa|bbb|ccc
ddd|fff|ggg
123|0 |5.0
-----------:tableclass1
-----------:blockquoteclass[blockquoteid]
This this a new paragraph
with a followed table.
Table has header, footer, sections,
odd and even rows:
-------------------------------
**Title 1**|**Title 2**|**Title 3**
==============================
data 1 | data 2 | 2.00
data 3 |data4(long)| 23.00
|data 5 | 33.50
==============================
New section|New data | 5.00
data 1 |data2(long)|100.45
|data 3 | 12.50
data 4 | data 5 | .33
data 6 |data7(long)| 8.01
|data 8 | 514
==============================
Total: | 9 items |698,79
------------------------------:tableclass1[tableid2]
## Multilevel
lists
Now lists can be multilevel:
+ Ordered item 1 on level 1.
You can continue item text on
next strings
. paragraph in an item
++. Ordered item 1 of sublevel 2 with
a paragraph (paragraph can start
with point after plus or minus
characters, e.g. **++.** or **--.**)
++. This is another item. But with 3 paragraphs,
blockquote and sublists:
.. This is the second paragraph in the item. You
can add paragraphs to an item, using point
notation, where first characters in the string
are sequence of points with space between
them and another string. For example, this
paragraph (in sublevel 2) starts with two points:
``.. This is the second paragraph...``
.. ----------
### this is a blockquote in a list
You can use blockquote with headers, paragraphs,
tables and lists in it:
Tables can have or have not header and footer.
This table is defined without any header
and footer in it:
---------------------
red |fox | 0
blue |dolphin | 1000
green|leaf | 10000
---------------------
----------
.. This is yet another paragraph in the item.
--- This is an item of unordered list **(sublevel 3)**
--- This is the second item of the unordered list ''(sublevel 3)''
++++++ This is a single item of ordered list in sublevel 6
.... and this is a paragraph in sublevel 4
---. This is a new item with paragraph in sublevel 3.
++++ Start ordered list in sublevel 4 with code block: ``
line 1
line 2
line 3
``
++++. Yet another item with code block (we need to indent \`\` to add code block as part of item):
``
line 1
line 2
line 3
``
This item finishes with this paragraph.
... Item in sublevel 3 can be continued with paragraphs.
... ``
this is another
code block
in the
sublevel 3 item
``
+++ The last item in sublevel 3
.. This is a continuous paragraph for item 2 in sublevel 2.
You can use such structure to create difficult structured
documents.
++ item 3 in sublevel 2
-- item 1 in sublevel 2 (new unordered list)
-- item 2 in sublevel 2
-- item 3 in sublevel 2
++ item 1 in sublevel 2 (new ordered list)
++ item 2 in sublevel 2
++ item 3 in sublevle 2
+ item 2 in level 1
+ item 3 in level 1
- new unordered list (item 1 in level 1)
- level 2 in level 1
- level 3 in level 1
- level 4 in level 1
## This is the last section of the test
Single paragraph with '----' in it will be turned into separator:
-----------
And this is the last paragraph in
the test. Be happy!
====================
## Why?
We wanted a markup language with the following requirements:
- less than 300 lines of functional code
- easy to read
- secure
- support table, ul, ol, code
- support html5 video and audio elements (html serialization only)
- can align images and resize them
- can specify class for tables, blockquotes and code elements
- can add anchors
- does not use _ for markup (since it creates odd behavior)
- automatically links urls
- fast
- easy to extend
- supports latex and pdf including references
- allows to describe the markup in the markup (this document is generated from markmin syntax)
(results depend on text but in average for text ~100K markmin is 30% faster than markdown, for text ~10K it is 10x faster)
The [[web2py book http://www.lulu.com/product/paperback/web2py-%283rd-edition%29/12822827]] published by lulu, for example, was entirely generated with markmin2pdf from the online [[web2py wiki http://www.web2py.com/book]]
## Download
- http://web2py.googlecode.com/hg/gluon/contrib/markmin/markmin2html.py
- http://web2py.googlecode.com/hg/gluon/contrib/markmin/markmin2latex.py
- http://web2py.googlecode.com/hg/gluon/contrib/markmin/markmin2pdf.py
markmin2html.py and markmin2latex.py are single files and have no web2py dependence. Their license is BSD.
## Examples
### Bold, italic, code and links
------------------------------------------------------------------------------
**SOURCE** | **OUTPUT**
==============================================================================
``# title`` | **title**
``## section`` | **section**
``### subsection`` | **subsection**
``**bold**`` | **bold**
``''italic''`` | ''italic''
``~~strikeout~~`` | ~~strikeout~~
``!`!`verbatim`!`!`` | ``verbatim``
``\`\`color with **bold**\`\`:red`` | ``color with **bold**``:red
``\`\`many colors\`\`:color[blue:#ffff00]`` | ``many colors``:color[blue:#ffff00]
``http://google.com`` | http://google.com
``[[**click** me #myanchor]]`` | [[**click** me #myanchor]]
``[[click me [extra info] #myanchor popup]]`` | [[click me [extra info] #myanchor popup]]
-------------------------------------------------------------------------------
### More on links
The format is always ``[[title link]]`` or ``[[title [extra] link]]``. Notice you can nest bold, italic, strikeout and code inside the link ``title``.
### Anchors [[myanchor]]
You can place an anchor anywhere in the text using the syntax ``[[name]]`` where ''name'' is the name of the anchor.
You can then link the anchor with [[link #myanchor]], i.e. ``[[link #myanchor]]`` or [[link with an extra info [extra info] #myanchor]], i.e.
``[[link with an extra info [extra info] #myanchor]]``.
### Images
[[alt-string for the image [the image title] http://www.web2py.com/examples/static/web2py_logo.png right 200px]]
This paragraph has an image aligned to the right with a width of 200px. Its is placed using the code
``[[alt-string for the image [the image title] http://www.web2py.com/examples/static/web2py_logo.png right 200px]]``.
### Unordered Lists
``
- Dog
- Cat
- Mouse
``
is rendered as
- Dog
- Cat
- Mouse
Two new lines between items break the list in two lists.
### Ordered Lists
``
+ Dog
+ Cat
+ Mouse
``
is rendered as
+ Dog
+ Cat
+ Mouse
### Multilevel Lists
``
+ Dogs
-- red
-- brown
-- black
+ Cats
-- fluffy
-- smooth
-- bald
+ Mice
-- small
-- big
-- huge
``
is rendered as
+ Dogs
-- red
-- brown
-- black
+ Cats
-- fluffy
-- smooth
-- bald
+ Mice
-- small
-- big
-- huge
### Tables (with optional header and/or footer)
Something like this
``
-----------------
**A**|**B**|**C**
=================
0 | 0 | X
0 | X | 0
X | 0 | 0
=================
**D**|**F**|**G**
-----------------:abc[id]
``
is a table and is rendered as
-----------------
**A**|**B**|**C**
=================
0 | 0 | X
0 | X | 0
X | 0 | 0
=================
**D**|**F**|**G**
-----------------:abc[id]
Four or more dashes delimit the table and | separates the columns.
The ``:abc``, ``:id[abc_1]`` or ``:abc[abc_1]`` at the end sets the class and/or id for the table and it is optional.
### Blockquote
A table with a single cell is rendered as a blockquote:
-----
Hello world
-----
Blockquote can contain headers, paragraphs, lists and tables:
``
-----
This is a paragraph in a blockquote
+ item 1
+ item 2
-- item 2.1
-- item 2.2
+ item 3
---------
0 | 0 | X
0 | X | 0
X | 0 | 0
---------:tableclass1
-----
``
is rendered as:
-----
This is a paragraph in a blockquote
+ item 1
+ item 2
-- item 2.1
-- item 2.2
+ item 3
---------
0 | 0 | X
0 | X | 0
X | 0 | 0
---------:tableclass1
-----
### Code, ````, escaping and extra stuff
``
def test():
return "this is Python code"
``:python
Optionally a ` inside a ``!`!`...`!`!`` block can be inserted escaped with !`!.
**NOTE:** You can escape markmin constructions (\\'\\',\`\`,\*\*,\~\~,\[,\{,\]\},\$,\@) with '\\\\' character:
so \\\\`\\\\` can replace !`!`! escape string
The ``:python`` after the markup is also optional. If present, by default, it is used to set the class of the block.
The behavior can be overridden by passing an argument ``extra`` to the ``render`` function. For example:
``
markmin2html("!`!!`!aaa!`!!`!:custom",
extra=dict(custom=lambda text: 'x'+text+'x'))
``:python
generates
``'xaaax'``:python
(the ``!`!`...`!`!:custom`` block is rendered by the ``custom=lambda`` function passed to ``render``).
### Line breaks
``[[NEWLINE]]`` tag is used to break lines:
``
#### Multiline [[NEWLINE]]
title
paragraph [[NEWLINE]]
with breaks[[NEWLINE]]in it
``
generates:
#### Multiline [[NEWLINE]]
title
paragraph [[NEWLINE]]
with breaks[[NEWLINE]]in it
### Html5 support
Markmin also supports the %s' % (cls, id, escape(code[1:-1]), pp)
return '%s' % (cls, id, escape(code[beg:end]))
text = regex_expand_meta.sub(expand_meta, text)
if environment:
text = replace_components(text,environment)
return text.translate(ttab_out)
def markmin2html(text, extra={}, allowed={}, sep='p',
autolinks='default', protolinks='default',
class_prefix='', id_prefix='markmin_', pretty_print=False):
return render(text, extra, allowed, sep,
autolinks=autolinks, protolinks=protolinks,
class_prefix=class_prefix, id_prefix=id_prefix,
pretty_print=pretty_print)
def run_doctests():
import doctest
doctest.testmod()
if __name__ == '__main__':
import sys
import doctest
from textwrap import dedent
html=dedent("""
%(style)s
%(title)s
%(body)s
""")[1:]
if sys.argv[1:2] == ['-h']:
style=dedent("""
""")[1:]
print html % dict(title="Markmin markup language",
style=style,
body=markmin2html(__doc__, pretty_print=True))
elif sys.argv[1:2] == ['-t']:
from timeit import Timer
loops=1000
ts = Timer("markmin2html(__doc__)","from markmin2html import markmin2html")
print 'timeit "markmin2html(__doc__)":'
t = min([ts.timeit(loops) for i in range(3)])
print "%s loops, best of 3: %.3f ms per loop" % (loops, t/1000*loops)
elif len(sys.argv) > 1:
fargv = open(sys.argv[1],'r')
try:
markmin_text=fargv.read()
# embed css file from second parameter into html file
if len(sys.argv) > 2:
if sys.argv[2].startswith('@'):
markmin_style = ''
else:
fargv2 = open(sys.argv[2],'r')
try:
markmin_style = ""
finally:
fargv2.close()
else:
markmin_style = ""
print html % dict(title=sys.argv[1], style=markmin_style,
body=markmin2html(markmin_text, pretty_print=True))
finally:
fargv.close()
else:
print "Usage: "+sys.argv[0]+" -h | -t | file.markmin [file.css|@path_to/css]"
print "where: -h - print __doc__"
print " -t - timeit __doc__ (for testing purpuse only)"
print " file.markmin [file.css] - process file.markmin + built in file.css (optional)"
print " file.markmin [@path_to/css] - process file.markmin + link path_to/css (optional)"
run_doctests()