# stx_to_html - render StructuredText to HTML, including images
# =============================================================
# Aug 23, 2001 - Danny W. Adair
#
#
# Usage:
#
# Put this file in your "Extensions" folder, and create an "External method"
# stx_to_html in your management interface, using "stx_to_html" both as module
# and function name.
#
# To render StructuredText including images, change your current way of
# rendering StructuredText to HTML
#
# -------------------------------------------
#
# -------------------------------------------
#
# to using the external method:
#
# -------------------------------------------
#
# -------------------------------------------
#
#
# There are two ways of inserting images in your stx input,
# very similar to the ones you would use to insert a hyperlink:
#
# 1. Text enclosed by double quotes followed by ":img" (without the
# quotes), followed by another colon and a URL, and concluded by
# punctuation plus white space, or just white space, will show
# the image residing in the specified URL, using the double quoted
# text as the "alt" text.
#
# For example,
# ----------------------------------------------
# "My Zope Logo":img:/p_/zopelogo_jpg
# ----------------------------------------------
# will insert the Zope logo from your Zope server, and provide
# "My Zope Logo " as the alt text.
#
# 2. Text enclosed by double quotes followed by ":img" (without the
# quotes), follwed by a comma, one or more spaces, an absolute URL
# and concluded by punctuation plus white space, or just white space,
# will show the image residing in the specified absolute URL, using
# the double quoted text as the "alt" text.
#
# For example,
# ----------------------------------------------
# "The Zope Logo":img, http://www.zope.org/p_/zopelogo_jpg
# ----------------------------------------------
# will insert the Zope logo from zope.org, and provide "The Zope
# Logo" as the alt text.
#
#
# ( Sorry if you have never seen a "p_" folder... ;-) )
#
#
# So actually the only difference to creating a hyperlink is that you append
# a ":img" to your doublequoted text...
#
#
# Technical Note:
# This function uses two helper classes to override the standard behavior
# of the preinstalled ...WithImages classes of the StructuredText package.
#
# - The current Zope 2.4 (and 2.4.1b1) implementation has a little bug in
# StructuredText.DocumentWithImages.doc_img() that prevents it from accepting
# images with underscores in their URL. This has been fixed.
#
# - The current Zope 2.4 (and 2.4.1b1) implementation of
# StructuredText.HTMLWithImages.document() will add and tags
# to your input. I expect this to be unwanted by most users, since
# StructuredText.HTMLClass.document() - the standard rendering without images -
# doesn't do that. stx_to_html will only render "the inner part", nothing
# that you didn't have in your stx input will be added.
#
import StructuredText, re
from StructuredText.HTMLWithImages import HTMLWithImages
_STXDWI = StructuredText.DocumentWithImages.__class__
class DWIClass( StructuredText.DocumentWithImages.__class__ ):
## Some constants to make the doc_img() regex easier to read.
from StructuredText.STletters import letters, dbl_quoted_punc
_DQUOTEDTEXT = r'("[ %s0-9\n\r%s]+")' % (letters,dbl_quoted_punc) ## double quoted text
_ABSOLUTE_URL=r'((http|https|ftp|mailto|file|about)[:/]+?[%s0-9_\@\.\,\?\!\/\:\;\-\#\~\=\&\%%]+)' % letters
_ABS_AND_RELATIVE_URL=r'([%s0-9_\@\.\,\?\!\/\:\;\-\#\~\=\&\%%]+)' % letters
_SPACES = r'(\s*)'
def doc_img(self, s,
expr1 = re.compile( _DQUOTEDTEXT + ":img:" + _ABS_AND_RELATIVE_URL + _SPACES ).search,
expr2 = re.compile( _DQUOTEDTEXT + ":img" + r'(\,\s+)' + _ABSOLUTE_URL + _SPACES ).search):
# overrides DocumentWithImages.doc_img (Zope 2.4.1b1) to fix the missing underscore in the regex
return _STXDWI.doc_img( self, s, expr1, expr2 )
DWIClass = DWIClass()
class HWIClass( HTMLWithImages ):
def document(self, doc, level, output):
# overrides HTMLWithImages.document (Zope 2.4.1b1) to leave out and tag when rendering
for c in doc.getChildNodes():
getattr(self, self.element_types[c.getNodeName()])(c, level, output)
HWIClass = HWIClass()
def stx_to_html( text, level=1 ):
st = StructuredText.Basic( text )
if not st:
return ""
doc = DWIClass( st )
html = HWIClass( doc, level )
return html