I've been reading How to Make a Complete Map of Every Thought You Think, a not-so-well-written, edge-of-your-seat homebrew guide on how to organize everything that goes through your head. I finished "chapter" five while waiting for the bus, and I've learned how the author organizes his notebooks, what kinds of pens he keeps around, and how to organize topics into "maps" and entire pages.
I'll chirp about the content later, as it's the style of the "book" that's hooked my attention. The author explains that he wrote the entire document in one fell sloop with nearly no use of the backspace key. The result is a firehose of information, which is organized into "chapters" that are really markers of how many pages to print at a time.
The book screams for an editor. My designer and editorial instincts are simply dying to take over. With every other paragraph I imagine dumping the document with
w3m, starting to mark it up with POD or KWID, converting it to LaTeX sections, refactoring the content, and playing with the style. The author describes techniques for marking notebook pages, and my reading is constantly interrupted with ideas of how to autogenerate figures to exemplify his techniques. If only I had time!
A little yak-shaving is needed, however, because I'd much rather use KWID and WAFL markup than POD. (KWID is kind of the name for Kwiki markup, which may also become an alternative to POD for Perl6 documentation.). What I really, really want is an extensible KWID parser, but there doesn't seem to be anything like it!
Parsing wiki text is different from parsing, say, the output of
diff. When you parse wiki text, if there is incorrect syntax, nothing happens. There don't seem to be any events, only things to replace other things with, so a stream interface wouldn't apply.
The original CGI::Kwiki::Formatter (the Olde Kwiki Era) seemed to have the right idea by specifying a list of things to to format and in what order. Kwiki::Formatter (the New Kwiki Era) specifies a class heirarchy, and each class specfies what other classes it contains, and supports the new extensible WAFL syntax. Kwiki::Formatter, however, doesn't seem to be able to stand alone easily.
Basically, a formatter of this type turns markup into a data structure, and the data structure is turned into output markup, whether it be XHTML, XML, LaTeX, POD, plain text, etc. The question is, how do I go about doing it, and how do I do it well?