This module implements a base class for text formatting and manages extensions providing specific markup formats.
Multiple formats are supported and identified by content types. Extensions should use the same content type names as in MIME.
Why not choose the simple solution of supporting only one markup format? Markdown is the obvious choice for it, while the author uses reStructuredText for this manual and some other works. Complex works need HTML or LaTeX. Each wiki has its own incompatible markup. Other users have documents with different markup languages, while they could use Lethe to handle drafts for their works and copy them to other systems. For these reasons, we need support for multiple formats and a general infrastructure handling them.
implement and mention linking: its design is another reason for format complexity
Base class for text formatters.
To format a text, get a subclass constructor from get_format (or FormatRegistry.get_format). Construct an instance with the text containing markup in the text argument and use methods like to_html to format the text.
Subclasses should implement the to_html and verify methods. If the format has direct support for plain text output (e.g. with different text than via HTML), to_text should be implemented too. The default implementations should be ok for plain text represented as preformatted text in HTML.
Content type that this instance handles. Must be replaced in subclasses.
Return the input with replaced links. Implementations of to_html should use this method.
|Parameters:||html – a string with HTML text.|
|Returns:||a markupsafe.Markup instance with the input text with link targets replaced by the link processor|
Run process_uri on each link target in the text as returned by to_html.
Use this function to make site-internal links point to URLs used by your frontend for Lethe.
|Parameters:||process_uri – a function that accepts a single string argument and returns a URI to use instead of the argument, or None to not change the URIs|
Template name for HTML fragment documenting the format. None for undocumented formats.
The unformatted text. Don’t change it. (This is an instance attribute, not a class attribute.)
Return a markupsafe.Markup instance containing the text in HTML markup.
Return a plain text approximation of the text as a Unicode string.
The base implementation extracts text from the HTML representation of the document.
Verify markup syntax.
|Returns:||a list of syntax errors found (as human-readable strings) or an empty list if the markup is correct|
Keep content type to Format implementation mapping.
Register all formats declared in modules of the lethe.ext.format package.
Register the specified Format subclass.
|if format_class doesn’t have a string in the Format.content_type attribute|
Return a sequence of pairs of content type and human-readable name.
FormatRegistry.get_format for the default registry providing all lethe.ext.format extensions.