When working with collections of topics, two types of file formats are somehow required:
- A file format for the collection (the map)
- A file format for the topics
After considering other options for about a few seconds, XML was selected as the preferred file format. But what dialect of XML to use?
Master collection (map) file
Although typical users will probably never edit the collection's master file directly, the file used by Tópico is a simple XML file that should easily be understood by any power user. It's basically a big document header hosting the different collection options with a root topic at the bottom. This root topic is the parent of all other topics in the collection.
The base packages include some sample XSL transformation templates for the master file:
- Nested unordered lists (for CSS/JS menus)
- HTML Help content file (hhc)
- ASP.NET site map
- Sitemap.org (1)
- DITA Map
- Other Custom Menu Scripts
(1) File format for submiting to search engines
XHTML topic source files
Tópico individual topic files are saved as valid XHTML file, with a few meta elements containing the different topic properties. This approach that provides Tópico users with a standard file format that is highly effective for simple publishing scenarios, where you can ecreate your own microformat.
Actually, the source files aren't exactly valid if you use XInclude elements but that's not really a problem because you can define namespaces to be left out of the validation process in the topico.ini.xml file. By default, the XInclude (xi prefix) namespace and the embed element that's found in the xhtml namespace are excluded.
- <!-- exclude from xhtml validation -->
- <section id="exclude">
- <set key="ex" xpath="//xi:*" />
- <set key="ex" xpath="//xhtml:embed" />
Individual topics are not (by default) validated againts the XHTML DTD. The XStandard editor produces very clean XHTML markup and in the case a topic would proved to be problematic (read invalid), many specialized tools are available (for free or commercially) to troubleshoot and fix the problem.
A very simple Shematron (subset) implementation allows for validating topics in a more user friendly way.
THIS TOPIC IS A WORK IN PROGRESS