From 11da09105d02f41a89ce82f757dbcf58971581cc Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Wed, 16 Dec 2015 01:01:01 -0600 Subject: [PATCH] Add note on caveats [ci skip] --- README.rst | 18 ++++++++++++++++++ docs/caveats.rst | 17 +++++++++++++++++ docs/index.rst | 1 + 3 files changed, 36 insertions(+) create mode 100644 docs/caveats.rst diff --git a/README.rst b/README.rst index c361a56..20e665d 100644 --- a/README.rst +++ b/README.rst @@ -114,6 +114,24 @@ saving the page!) by calling ``str()`` on it:: Likewise, use ``unicode(code)`` in Python 2. +Caveats +------- + +An inherent limitation in wikicode prevents us from generating complete parse +trees in certain cases. For example, the string ``{{echo|''Hello}}, world!''`` +produces the valid output ``Hello, world!`` in MediaWiki, assuming +``{{echo}}`` is a template that returns its first parameter. But since +representing this in mwparserfromhell's node tree would be impossible, we +compromise by treating the first node (i.e., the template) as plain text, +parsing only the italics. + +The current workaround for cases where you are not interested in text +formatting is to pass ``skip_style_tags=True`` to ``mwparserfromhell.parse()``. +This treats ``''`` and ``'''`` like plain text. + +A future version of mwparserfromhell will include multiple parsing modes to get +around this restriction. + Integration ----------- diff --git a/docs/caveats.rst b/docs/caveats.rst new file mode 100644 index 0000000..927aa54 --- /dev/null +++ b/docs/caveats.rst @@ -0,0 +1,17 @@ +Caveats +======= + +An inherent limitation in wikicode prevents us from generating complete parse +trees in certain cases. For example, the string ``{{echo|''Hello}}, world!''`` +produces the valid output ``Hello, world!`` in MediaWiki, assuming +``{{echo}}`` is a template that returns its first parameter. But since +representing this in mwparserfromhell's node tree would be impossible, we +compromise by treating the first node (i.e., the template) as plain text, +parsing only the italics. + +The current workaround for cases where you are not interested in text +formatting is to pass *skip_style_tags=True* to :func:`mwparserfromhell.parse`. +This treats ``''`` and ``'''`` like plain text. + +A future version of mwparserfromhell will include multiple parsing modes to get +around this restriction. diff --git a/docs/index.rst b/docs/index.rst index 9a6c8ab..bb00bf6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,6 +41,7 @@ Contents :maxdepth: 2 usage + caveats integration changelog API Reference