You may have incomplete documents (e.g. documents with conditional sections, very much like XSLT): <code:if test="..."> <!-- whatever --> <code:e

You may have incomplete documents (e.g. documents with conditional sections, very much like XSLT): <code:if test="..."> <!-- whatever --> <code:else> <!-- whatever --> </code:if> Here you'll first process your code part an copy the contents as they are and then process the contents; but in the source document the two languages are interspersed. Or you may want to extend your text format with, say, literate programming and add code fragments and files. In my homegrown system it's like that: <literate:fragment id="..." language="..."> <text:caption>...</text:caption> <literate:code>...</literate:code> </literate:fragment> My text system already has a notion of captions so there's no need to add my own "literate:caption" here. Yet the other two "literate" elements are new an unique. Also, using a namespace here ensures that I'm sure not to have a clash if the base system adds their own "fragment" or "code" blocks.