<div dir="ltr">What applications does this HTML5 validation enable?  I've tried to skim this thread to find the big picture, but I can't find it.<div><br></div><div>Why does Clang need to validate the HTML, rather than simply associating comments with Decls and handing them over to a client who knows the details of Doxygen and HTML?</div>
</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Apr 28, 2014 at 2:14 AM, Dmitri Gribenko <span dir="ltr"><<a href="mailto:gribozavr@gmail.com" target="_blank">gribozavr@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hello,<br>
<br>
In one of the threads on cfe-commits I was asked by Tobias to provide<br>
a rationale for adding more HTML-related validation facilities in<br>
Clang's comment parsing.<br>
<br>
HTML is an indivisible part of Doxygen syntax.  It is impossible to<br>
parse Doxygen without not only merely parsing, but doing semantic<br>
analysis on HTML tags.<br>
<br>
For example, paragraph splitting is more complex than just finding an<br>
empty line.<br>
<br>
/// <b>Aaa<br>
///<br>
/// Bbb<br>
void f();<br>
<br>
/// <table><br>
/// <tr><td>Aaa</tr></td><br>
///<br>
/// </table><br>
void g();<br>
<br>
Somehow (I am not saying that the rules make sense, it is just what it<br>
is), Doxygen interprets this like this:<br>
<br>
1. for f():<br>
<br>
<p><b>Aaa</b></p><br>
<p><b>Bbb </b></p><br>
<br>
An unterminated <b> tag started to span multiple paragraphs.<br>
<br>
2. for g():<br>
<br>
<table class="doxtable"><br>
<tr><br>
<td><p class="starttd">Aaa</p><br>
<p class="endtd"></p><br>
</td></tr><br>
</table><br>
<br>
An empty line between table tags made Doxygen add a second paragraph<br>
to a table cell that had its content clearly specified.<br>
<br>
Judging just from these two simple examples, it is clear that in order<br>
to parse embedded HTML in Doxygen so that the output actually takes<br>
the HTML markup into account, requires *semantic* analysis of HTML<br>
tags, and transformation of the HTML AST.<br>
<br>
It is a non-trivial amount of work to implement this, and I did look<br>
for HTML libraries that could help us in doing so.  libtidy [1] is a<br>
nice one, except that I got the impression that it is "stabilized to<br>
the point of becoming unmaintained" -- there are no releases, code is<br>
available through cvs only, and it was not updated for HTML5.  There<br>
is an experimental HTML5 fork of it [2], which was not updated for<br>
more than 2 years, and probably does not correspond to the current<br>
HTML5 draft.<br>
<br>
But even if libtidy did completely support HTML5, its interface is not<br>
suitable for fine-grained parsing and AST manipulation that we need.<br>
The interface accepts only complete HTML docs for parsing, while Clang<br>
deals with fragments.  Constructing the HTML AST though libtidy just<br>
to figure out what the tag name is is not going to deliver good<br>
performance either.<br>
<br>
Apart from libtidy, I did not find other *lightweight* libraries (not<br>
HTML rendering engines) that provide low-level manipulation that we<br>
need.<br>
<br>
But parsing and doing semantic analysis correctly is only half of the<br>
story.  Sanitizing the output is important, otherwise Clang clients<br>
can not use the HTML parts of comments, and have to re-do the parsing<br>
work, now with the intent of sanitizing the output.  I think it is<br>
reasonable to state that almost all clients want the output as<br>
well-formed HTML and sanitized of javascript.  It rarely (if ever)<br>
makes sense to put executable javascript into comments anyway.<br>
<br>
I hope this addresses everyone's concerns.<br>
<br>
Dmitri<br>
<br>
[1] <a href="http://tidy.sourceforge.net/" target="_blank">http://tidy.sourceforge.net/</a><br>
[2] <a href="https://github.com/w3c/tidy-html5" target="_blank">https://github.com/w3c/tidy-html5</a><br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if<br>
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com">gribozavr@gmail.com</a>>*/<br>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
</font></span></blockquote></div><br></div>