Edgewall Software

Changes between Version 19 and Version 20 of GenshiFaq


Ignore:
Timestamp:
Sep 11, 2006, 2:15:18 PM (18 years ago)
Author:
cmlenz
Comment:

s/Markup/Genshi

Legend:

Unmodified
Added
Removed
Modified

  • GenshiFaq

    v19 v20  
    11= Frequently Asked Questions =
    22
    3 Here you can find answers to frequently asked questions about Markup.
     3Here you can find answers to frequently asked questions about Genshi.
    44
    55[[PageOutline(2-3, Overview, inline)]]
    … …  
    77== General ==
    88
    9 === What is Markup? ===
     9=== What is Genshi? ===
    1010
    11 We like to call it a ''“toolkit for stream-based generation of markup for the web”''. The largest feature provided by Markup is an XML-based template engine that is heavily inspired by [http://kid-templating.org/ Kid].
     11We like to call it a ''“toolkit for stream-based generation of output for the web”''. The largest feature provided by Genshi is an XML-based template engine that is heavily inspired by [http://kid-templating.org/ Kid]. But it also provides a text-based template engine, as well as a collection of tools for working with markup.
    1212
    1313=== Why yet another template engine? ===
    … …  
    3838We felt these problems would best be addressed by developing a new engine form scratch, as opposed to trying to “fix” Kid.
    3939
    40 === What are the main differences between Kid and Markup? ===
     40=== What are the main differences between Kid and Genshi? ===
    4141
    42 Markup executes templates directly, there's no code generation phase. Expressions are evaluated in a more forgiving way using AST transformation. Template variables are stored on a stack, which means that some variable set in a loop deep in the template won't leak into the rest of the template. And even though Markup doesn't generate Python code for templates, it generally [wiki:MarkupPerformance performs] slightly better than Kid (even up to 2x in [source:/trunk/examples/basic/ some of our tests], but the exact differences depend on a lot of factors).
     42Genshi executes templates directly, there's no code generation phase. Expressions are evaluated in a more forgiving way using AST transformation. Template variables are stored on a stack, which means that some variable set in a loop deep in the template won't leak into the rest of the template. And even though Genshi doesn't generate Python code for templates, it generally [wiki:GenshiPerformance performs] slightly better than Kid (even up to 2x in [source:/trunk/examples/basic/ some of our tests], but the exact differences depend on a lot of factors).
    4343
    44 Markup does not depend on !ElementTree. It uses Expat for parsing XML, and is based on streaming slightly abstracted parse events through the processing pipeline. It uses [http://www.w3.org/TR/xinclude/ XInclude] – instead of Kids' `py:extends` – to allow template authors to factor out common bits. For match templates, it uses [http://www.w3.org/TR/xpath XPath] expressions instead of the !ElementTree API.
     44Genshi does not depend on !ElementTree. It uses Expat for parsing XML, and is based on streaming slightly abstracted parse events through the processing pipeline. It uses [http://www.w3.org/TR/xinclude/ XInclude] – instead of Kids' `py:extends` – to allow template authors to factor out common bits. For match templates, it uses [http://www.w3.org/TR/xpath XPath] expressions instead of the !ElementTree API.
    4545
    46 For more details about what's different see MarkupVsKid.
     46For more details about what's different see GenshiVsKid.
    4747
    4848=== What other features does the toolkit provide? ===
    4949
    50 Beyond the template engine, Markup provides:
     50Beyond the XML-based template engine, Genshi provides:
    5151 * a [MarkupStream unified stream-based processing model] for markup, where
    5252 * streams can come from XML or HTML text, or be [MarkupBuilder generated programmatically] using a very simple syntax.
    5353 * [MarkupPath XPath] can be used to query any stream, not just in templates.
    54  * Different serialization methods (XML and HTML) for streams.
     54 * Different serialization methods (XML, HTML, and plain text) for streams.
    5555 * An HTML “sanitizing” filter to strip potentially dangerous elements or attributes from user-submitted HTML markup.
     56 * A simple text-based template engine that can be used for generating plain text output.
    5657
    5758=== Why use includes instead of inheritance? ===
    … …  
    5960We think that includes are both simpler and more natural for templating.
    6061
    61 Template inheritance is a concept that fits well with template languages where a master template provide “slots” that are “filled” by the inheriting templates. However, Markup has no such feature, and instead uses the more powerful and flexible concept of [wiki:MarkupTemplates#py:match match templates].
     62Template inheritance is a concept that fits well with template languages where a master template provide “slots” that are “filled” by the inheriting templates. However, Genshi has no such feature, and instead uses the more powerful and flexible concept of [wiki:GenshiTemplates#py:match match templates].
    6263
    6364Furthermore, [http://www.w3.org/TR/xinclude/ XInclude] is a [http://www.w3.org/ W3C] standard, which means that it is more likely to be supported in authoring tools than some esoteric custom notation for including external resources.
    6465
    65 ''See also MarkupRecipes/PyExtendsEquivalent and MarkupRecipes/PyLayoutEquivalent to find out how the Kid directives `py:extends` and `py:layout` map to includes in Markup.''
     66''See also GenshiRecipes/PyExtendsEquivalent and GenshiRecipes/PyLayoutEquivalent to find out how the Kid directives `py:extends` and `py:layout` map to includes in Genshi.''
    6667
    6768[[Image(http://static.edgewall.org/gfx/opensource-75x65.png, width=75, height=65, align=right)]]
    68 === What license governs the use of Markup? ===
     69=== What license governs the use of Genshi? ===
    6970
    70 Markup is released under the [wiki:License revised BSD license], which is a liberal open source license that has been [http://opensource.org/licenses/bsd-license.php approved] by the [http://opensource.org/ Open Source Initiative (OSI)].
     71Genshi is released under the [wiki:License revised BSD license], which is a liberal open source license that has been [http://opensource.org/licenses/bsd-license.php approved] by the [http://opensource.org/ Open Source Initiative (OSI)].
    7172
    72 === What do I need to use Markup? ===
     73=== What do I need to use Genshi? ===
    7374
    7475Python 2.3 or later. Python 2.4 is recommended for better performance, plus error messages will include template line numbers and column offsets. [http://peak.telecommunity.com/DevCenter/setuptools Setuptools] is optional and only used for installation if it's available.
    7576
    76 The template engine plugin (for http://www.turbogears.org/docs/plugins/template.html), which enables usage of Markup in frameworks such as [http://www.turbogears.com/ TurboGears], depends on Setuptools at runtime and installation time. Use of the plugin implementation is optional, though: Setuptools is ''not'' required for using Markup directly.
     77The template engine plugin (for http://www.turbogears.org/docs/plugins/template.html), which enables usage of Genshi in frameworks such as [http://www.turbogears.com/ TurboGears], depends on Setuptools at runtime and installation time. Use of the plugin implementation is optional, though: Setuptools is ''not'' required for using Genshi directly.
    7778
    78 === What's up with the name? It's not possible to google for it! ===
     79=== Why is it called “Genshi”? ===
    7980
    80 We're aware of the problem. Frankly, finding a good name that is sufficiently unique but doesn't sound cheesy is really hard.
     81“Genshi” (原糸) is japanese and roughly translates to “thread for weaving”. Basically, Genshi is a ''thread for weaving web output''. The thread meaning also fits nicely
     82with how markup is presented as streams of events in Genshi.
    8183
    82 We're really open for suggestions though! If you have a good idea for a name, please bring it up on the [MailingList mailing list], [IrcChannel IRC channel], or the NameSuggestions wiki page. This project is still young, so changing the name at this point is certainly doable.
    83 
     84Prior to release 0.3, the project was called “Markup”. The name was changed because:
     85 * there was [http://markup.sourceforge.net/ another Python project] using the name,
     86 * it made communication somewhat awkward, because it was sometimes unclear whether someone is talking about the project “Markup”, or just plain markup, and
     87 * it was not easy to find the project via search engines.
    8488
    8589== Usage ==
    … …  
    8791=== How can I include literal XML in template output? ===
    8892
    89 Unless explicitly told otherwise, Markup escapes any data you substitute into template output so that it is safe for being parsed and displayed by web browsers and other tools. This saves you from the work of having to tediously escape every variable by hand, and greatly reduces the risk of introducing vectors for [http://ha.ckers.org/xss.html cross-site scripting (XSS)] attacks.
     93Unless explicitly told otherwise, Genshi escapes any data you substitute into template output so that it is safe for being parsed and displayed by web browsers and other tools. This saves you from the work of having to tediously escape every variable by hand, and greatly reduces the risk of introducing vectors for [http://ha.ckers.org/xss.html cross-site scripting (XSS)] attacks.
    9094
    9195However, sometimes what you want is to include text in the template output that should ''not'' get escaped. For example, if you allow users to enter HTML verbatim (or provide a rich-text editor of sorts), you want that HTML to appear as actual markup in the output, not as escaped text.
    9296
    93 Markup provides a number of ways to do that:
    94  * The `Markup` class in the [ApiDocs/MarkupCore markup.core] module can be used to flag strings that should not be escaped. Strings wrapped in a `Markup` instance get copied to the output unchanged.
    95  * The `XML` and `HTML` functions in the [ApiDocs/MarkupInput markup.input] module parse XML and HTML strings, respectively, and produce a [MarkupStream markup stream]. Note that this option can be rather expensive, as the text needs to be parsed just to be serialized again. Also, this method fails on bad markup that cannot be parsed by either [http://docs.python.org/lib/module-HTMLParser.html HTMLParser] or [http://docs.python.org/lib/module-xml.parsers.expat.html Expat].
    96  * If you are generating the snippets in question yourself, you may want to use the [ApiDocs/MarkupBuilder markup.builder] to [MarkupBuilder generate markup streams programmatically]. Just as the results of the `XML` and `HTML` functions discussed above, the stream produced using `markup.builder` will not be escaped in the template output.
     97Genshi provides a number of ways to do that:
     98 * The `Markup` class in the [ApiDocs/GenshiCore genshi.core] module can be used to flag strings that should not be escaped. Strings wrapped in a `Markup` instance get copied to the output unchanged.
     99 * The `XML` and `HTML` functions in the [ApiDocs/GenshiInput genshi.input] module parse XML and HTML strings, respectively, and produce a [GenshiStream markup stream]. Note that this option can be rather expensive, as the text needs to be parsed just to be serialized again. Also, this method fails on bad markup that cannot be parsed by either [http://docs.python.org/lib/module-HTMLParser.html HTMLParser] or [http://docs.python.org/lib/module-xml.parsers.expat.html Expat].
     100 * If you are generating the snippets in question yourself, you may want to use the [ApiDocs/GenshiBuilder genshi.builder] to [GenshiBuilder generate markup streams programmatically]. Just as the results of the `XML` and `HTML` functions discussed above, the stream produced using `genshi.builder` will not be escaped in the template output.
    97101
    98102----
    99 See also: MarkupGuide, MarkupRecipes
     103See also: GenshiGuide, GenshiRecipes