[boost] Documentation skinning

From: Emil Dotchevski (emil_at_[hidden])
Date: 2008-08-14 22:25:12

Perhaps I did something wrong, or failed to follow documentation
rules, but the fact that the HTML files that I generated for Boost
Exception were processed and wrapped in additional HTML caught me by
surprise. Obviously I'm not against using uniform skin throughout
Boost, but in general we can't just get HTML+CSS and wrap it with more
HTML+CSS, there might be class name collisions, and whatnot.

Besides the fact that now the Boost Exception documentation doesn't
validate as XHTML 1.0, another problem is that some headings are
simply function and class names, which the Boost CSS converts to
allcaps, making them look like macros.

It seems like other libraries have similar problems, I saw an instance
of library documentation having its own tags indicating that it's HTML
compliant, to which Boost is adding an additional XHTML 1.0 compliance
tag, the end result being that the file is neither HTML or XHTML
compliant.

This is unfortunate and unprofessional. Is there a standardized XML
format that can be used as documentation source?

Emil Dotchevski
Reverge Studios, Inc.
http://www.revergestudios.com/reblog/index.php?n=ReCode