https://issues.apache.org/bugzilla/show_bug.cgi?id=55383
--- Comment #3 from Konstantin Preißer <prei...@web.de> --- Hi Mark, (In reply to Mark Thomas from comment #2) > An overhaul of the docs and site is long overdue as you can tell from the > age of the duplicate. > > Please, go ahead. If you attach proposed patches, I'm happy to review and > apply them as I am sure other committers will be as well. > > One piece of advice I would give is to make small, incremental changes > rather than a "big-bang" approach. It is hard to provide guidance to what > the 'right' size is but the committers will let you know if you are wide of > the mark. > > As you go, please keep in mind the concerns raised in bug 16579. > > One comment on the new default homepage, it is (in my view) too cluttered. > It is a million miles better than what we had before but I think there is > still scope for improvement. Ok, thank you. After reviewing bug 16579, I would like to add to my previous point 3) reg. <table>: You can create a table-like layout purely with CSS (that is, using tags like <div> in markup and then use style "display: table;", "display: table-row" etc). This has the advantages over using <table> that - the HTML markup doesn't misuse a <table> for layout, which means a user-agent like a Search Engine can correctly regognize the structure of the document, and - the CSS "table" will not exceed the given width if it has elements that are wider (e.g. a <pre> with long lines of unwrappable text) than the "table" (this should consider the concerns in bug 16579). There are some other things that came to my attention while I was browsing through Tomcat's doc: 1) Sometimes there is following markup in HTML (a <ul> in a <p> tag): <p> Text... <ul>...</ul> More Text... </p> For example, r1511000 intruduced such a structure. Note that this is invalid HTML, as a <p> element cannot have nested <ul> and <ol> elements. A HTML parser therefore closes the <p> element as soon as it sees a <ul>, and therefore the following </p> is incorrect (I think this has been mentioned already by Konstantin Kolinko). In XHTML, it is possible to have a DOM like <p><ul>...</ul></p>, but it is still not valid XHTML. The currect markup in this case would be: <p>Test...</p> <ul>...</ul> <p>More Text...</p> Please see the HTML5 spec [1] reg. "The p element" for more info at this issue. 2) The Tomcat Docs use the Comments system (https://comments.apache.org/) by appeding a JavaScript that will place a comments section there (e.g. at the bottom at http://tomcat.apache.org/tomcat-8.0-doc/index.html). Note that while the script seems to be intended to be usable in XHTML as it contains a CDATA-declaration in the <script> tag, it actually isn't, as it uses document.write(). The use of "document.write()" in JavaScript is strongly discouraged and actually does not work in XHTML, because it can affect the HTML parser state while the parser is running [2] which is not possible with XML. One can use DOM methods like document.createElement(...) to insert elements when the DOM is ready, in preference to document.write(). That said, I think I can post an idea of a improved markup and tweaked style for the Tomcat Website and Docs shortly. [1] http://www.w3.org/TR/html51/grouping-content.html#the-p-element [2] http://www.w3.org/TR/html51/dom.html#document.write%28%29 -- You are receiving this mail because: You are the assignee for the bug. --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
