<piece variant="VARIANT" add-to="ADDTO">
Items define the documentation, and pieces define the code output. Each piece must be embedded in an item or it gets roundly
ignored. (Yes, yes, a DTD would simply make that illegal but remember that the alpha version doesn't really
understand XML.)
If a piece has a variant attribute, then it will only be included in objects for which it matches the variant spec. It will
be filtered out of others. This will allow a single presentation to produce specific code for, say, Unix and Win32 variants
of a single codebase. For finer control over variants, you can also embed a <variant>
tag into a piece.
The other application for the variant system is documentation of porting projects. Both variants (even in widely different
languages) can thus be tangled from the same presentation, while patterns shared by both may be shared explicitly. Again,
once the feature is complete and I've tried it on a certain project I have in mind (involving Common LISP and Java, so we're
at least talking about widely different languages) then we'll see how effective the whole idea is.
The add-to attribute is optional; if present, it causes the piece to be added, not to the
currently active item, but to the item named. This makes it convenient for presenting
cleanup code adjacent to allocation code, for instance. I'm still not entirely convinced
it's a good idea, but I'm reserving judgment until I've tried it out in a couple of
presentations.
<variant name="VARIANT">
When used within a <piece>
, makes a part of the piece subject to suppression. So if the object I'm
currently tangling is variant "unix" and I encounter a variant "win32" in the current piece, the contents of that tag will
not appear in the object.
<insert name="NAME"/>
Used to do literate programming in the traditional sense, of course. The occurrence of the tag is replaced with the contents
of the named item. This operation is recursive and is called tangling if you're not familiar with literate programming.
Come to think of it, if you are familiar with literate programming, it's still called tangling.