tools/doc/html.js produces invalid html

[jelmd]

tools/doc/html.js produces invalid html (v5.1.0) produces invalid html wrt. doc/api/*.html - use https://validator.w3.org/ to check. Suggested fix:

--- ./tools/doc/html.js.orig    Tue Nov 17 21:55:34 2015
+++ ./tools/doc/html.js Fri Nov 20 01:46:19 2015
@@ -135,11 +135,11 @@
       }
       if (tok.type === 'list_end') {
         depth--;
+        output.push(tok);
         if (depth === 0) {
           state = null;
           output.push({ type:'html', text: '</div>' });
         }
-        output.push(tok);
         return;
       }
       if (tok.text) {

[thefourtheye]

Can you please give a sample HTML which it produces right now?

[jelmd]

http://iws.cs.uni-magdeburg.de/~elkner/tmp/x/all.html

[thefourtheye]

@jelmd Thanks for the sample. How did you generate that?

[jelmd]

Found a shorter one:

./node tools/doc/generate.js --format=html --template=doc/template.html doc/api/buffer.markdown > /tmp/x/buffer.html

[thefourtheye]

@jelmd Do you have the doc/api_assets directory copied to the target location as assets?

[jelmd]

I made 'gmake doc && rm -rf /tmp/x && cp -pr out/doc/api /tmp/x' and playing around with it right now.

[thefourtheye]

@jelmd Weird. When I try that locally it seems work fine. BTW, why don't you submit the patch you have seen in this issue as a PR? So that people can review and give suggestions/feedback.

[jelmd]

https://validator.w3.org/nu/?doc=https%3A%2F%2Fnodejs.org%2Fapi%2Fbuffer.html

[jelmd]

FWIW: http://iws.cs.uni-magdeburg.de/~elkner/tmp/x/ contains now the fixed version (which also uses a "honor user prefs", optimized stylesheet).

[Fishrock123]

(Note: the doc tool hasn't been touched in years and about no-one actually remembers / knows how it works.)

[tflanagan]

@Fishrock123 I've recently submitted a PR updating it to include "since version" (#3867). It's a little obtuse, but not that bad. If there are questions, I'm happy to answer.

[Trott]

https://validator.w3.org/nu/?doc=https%3A%2F%2Fnodejs.org%2Fapi%2Fbuffer.html

That link now produces a single warning but no errors. That's true of a few other URLs on the site I checked. This suggests that the bug is no longer an issue, but if I'm wrong about that, please re-open or comment.

[jelmd]

At least 6.3.1 still seems to have a problem:
https://validator.w3.org/nu/?doc=http%3A%2F%2Fiws.cs.uni-magdeburg.de%2F~elkner%2Ftmp%2Fx%2Fall.html

Furthermore the doc/template.html is confusing wrt. id="toc" and name="toc" (actually name attr is deprecated in favor of the id attr). So in principal the generated docs have two blocks with the same id ...