From Beamer I've realized the best solution for writing presentations in this kind of tools is in my opinion to have by default the slides in a single file, and to provide an include facility to structure large presentations. This way short presentations are easy to write, and includes let authors organize their presentations as they wish.
Granted, that's an old idea, but in the prototype there was a directory structure. Its purpose was to have the slide and its related files in a single directory. Since in the presentations the prototype was written for almost every slide has a program and its corresponding HTML listing that sort of made sense. But for Halk that would be clearly a wrong choice.
Now, after seeing YAML wouldn't be a good choice for the config file, I pondered XML. If presentations are going to be writable in a single file I won't choose XML for two reasons:
- There's no clean including mechanism in XML that I know. The canonical options seem to be to create an entity like this
<!DOCTYPE spec SYSTEM "spec.dtd" [ <!ENTITY section1 SYSTEM "section1.xml"> ]>which I don't like for a friendly config file, or to use XInclude, whose corresponding Perl module I couldn't even install. I could try to add some custom solution for it but the second reason has more weight:
- Since presentations are written in HTML the config file would need to be full of CDATA markers. I don't like that idea.
Next step is to try to come with a neat solution for the requeriments I've got using some templating system. The candidates are Text::Template for its simplicity and, and the Template Toolkit for its power and clear syntax. In any case, authors wouldn't be required to know Perl or to study any of the choosen solutions unless they want to. The documentation should ideally explain how to write slides in a self-contained way.