path: root/README.creole

= about

python-creole is a OpenSource (GPL) Python lib for converting markups.
python-creole is pure python. No external libs needed.

Existing converters:

* creole -> html
* html -> creole markup
* reSt -> html (for clean html code)
* html -> reStructuredText markup (only a subset of reSt supported)
* html -> textile markup (not completed yet)

The creole2html part based on the creole markup parser and emitter from the MoinMoin project by Radomir Dopieralski and Thomas Waldmann.


= install

Python packages available on: [[http://pypi.python.org/pypi/python-creole/]]

{{{
~$ pip install python-creole
}}}


= example

== creole2html
Convert creole markup to html code:
{{{
>>> from creole import creole2html
>>> creole2html("This is **creole //markup//**")
u'<p>This is <strong>creole <i>markup</i></strong></p>\n'
}}}


== html2creole
Convert html code back into creole markup:
{{{
>>> from creole import html2creole
>>> html2creole(u'<p>This is <strong>creole <i>markup</i></strong></p>\n')
u'This is **creole //markup//**'
}}}


== rest2html
Convert ReStructuredText into clean html code (needs [[http://pypi.python.org/pypi/docutils|docutils]]):
{{{
>>> from creole.rest2html.clean_writer import rest2html
>>> rest2html(u"A ReSt link to `PyLucid CMS <http://www.pylucid.org>`_ :)")
u'<p>A ReSt link to <a href="http://www.pylucid.org">PyLucid CMS</a> :)</p>\\n'
}}}
(more information: [[https://code.google.com/p/python-creole/wiki/rest2html|rest2html wiki page]])


== html2rest
Convert html code into ReStructuredText markup:
{{{
>>> from creole import html2rest
>>> html2rest(u'<p>This is <strong>ReStructuredText</strong> <em>markup</em>!</p>')
u'This is **ReStructuredText** *markup*!'
}}}


== html2textile
Convert html code into textile markup
{{{
>>> from creole import html2textile
>>> html2textile(u'<p>This is <strong>textile <i>markup</i></strong>!</p>')
u'This is *textile __markup__*!'
}}}

See also: [[http://github.com/jedie/python-creole/blob/master/demo.py]]


= documentation

We store documentation/exmplate into the project wiki:

* [[http://code.google.com/p/python-creole/w/list]]

How to handle unknown html tags in html2creole:

* [[http://code.google.com/p/python-creole/wiki/UnknownHtmlTags]]

Contributers should take a look at this page:

* [[http://code.google.com/p/python-creole/wiki/DeveloperInfo]]


== Use creole in README ==

With python-creole you can convert a README on-the-fly from creole into ReStructuredText in setup.py
How to do this, read: https://code.google.com/p/python-creole/wiki/UseInSetup


= history

* v0.8.1
** Bugfix for installation under python 2.5
** Note: [[https://code.google.com/p/python-creole/wiki/UseInSetup|setup helper]] changed: rename {{{GetLongDescription(...)}}} to {{{get_long_description(...)}}}
* v0.8
** New GetLongDescription() helper for setup.py, see: https://code.google.com/p/python-creole/wiki/UseInSetup
* v0.7.3
** Bugfix in html2rest:
*** table without {{{<th>}}} header
*** new line after table
*** create reference hyperlinks in table cells intead of embedded urls.
*** Don't always use raise_unknown_node()
** Add child content to raise_unknown_node()
* v0.7.2
** Activate {{{----}}} to {{{<hr>}}} in html2rest
** Update demo.py
* v0.7.1
** Bugfix if docutils are not installed
** API change: rest2html is now here: {{{ from creole.rest2html.clean_writer import rest2html }}}
* v0.7.0
** **NEW**: Add a html2reStructuredText converter (only a subset of reSt supported)
* v0.6.1
** Bugfix: separate lines with one space in "wiki style line breaks" mode
* v0.6
** **NEW**: html2textile converter
** some **API changed**!
* v0.5
** **API changed**:
*** Html2CreoleEmitter optional argument 'unknown_emit' takes now a callable for handle unknown html tags.
*** No macros used as default in creole2html converting.
*** We remove the support for callable macros. Only dict and modules are allowed.
** remove unknown html tags is default behaviour in html2creole converting.
** restructure and cleanup sourcecode files.
* v0.4
** only emit children of empty tags like div and span (contributed by Eric O'Connell)
** remove inter wiki links and doesn't check the protocol
* v0.3.3
** Use <tt> when ~{~{~{ ... ~}~}~} is inline and not <pre>, see: [[http://forum.pylucid.org/viewtopic.php?f=3&t=320|PyLucid Forum Thread]]
** Bugfix in html2creole: insert newline before new list. TODO: apply to all block tags: [[http://code.google.com/p/python-creole/issues/detail?id=16#c5|issues 16]]
* v0.3.2
** Bugfix for spaces after Headline: [[https://code.google.com/p/python-creole/issues/detail?id=15|issues 15]]
* v0.3.1
** Make argument 'block_rules' in Parser() optional
* v0.3.0
** creole2html() has the optional parameter 'blog_line_breaks' to switch from default blog to wiki line breaks
* v0.2.8
** bugfix in setup.py
* v0.2.7
** handle obsolete non-closed <br> tag
* v0.2.6
** bugfix in setup.py
** Cleanup DocStrings
** add unittests
* v0.2.5
** creole2html: Bugfix if "--", "~/~/" etc. stands alone, see also: [[http://code.google.com/p/python-creole/issues/detail?id=12|issues 12]]
** Note: bold, italic etc. can't cross line any more.
* v0.2.4
** creole2html: ignore file extensions in image tag
*** see also: [[http://code.google.com/p/python-creole/issues/detail?id=7|issues 7]]
* v0.2.3
** html2creole bugfix/enhanced: convert image tag without alt attribute:
*** see also: [[http://code.google.com/p/python-creole/issues/detail?id=6|issues 6]]
*** Thanks Betz Stefan alias 'encbladexp'
* v0.2.2
** html2creole bugfix: convert {{{<a href="/url/">Search & Destroy</a>}}}
* v0.2.1
** html2creole bugfixes in:
*** converting tables: ignore tbody tag and better handling p and a tags in td
*** converting named entity
* v0.2
** remove all django template tag stuff: [[http://code.google.com/p/python-creole/issues/detail?id=3|issues 3]]
** html code always escaped
* v0.1.1
** improve macros stuff, patch by Vitja Makarov: [[http://code.google.com/p/python-creole/issues/detail?id=2|issues 2]]
* v0.1.0
** first version cut out from [[http://www.pylucid.org|PyLucid CMS]]


= donation

* [[http://flattr.com/thing/181554/python-creole|Flattr this!]]
* Send [[http://www.bitcoin.org/|Bitcoins]] to [[https://blockexplorer.com/address/12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9|12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9]]


= links

| Google code | [[http://code.google.com/p/python-creole/]]
| GitHub      | [[http://github.com/jedie/python-creole]]
| PyPi        | [[http://pypi.python.org/pypi/python-creole/]]
| IRC         | [[http://www.pylucid.org/permalink/304/irc-channel|#pylucid on freenode.net]]