https://issues.apache.org/bugzilla/show_bug.cgi?id=55383
Bug ID: 55383
Summary: Improve markup and design of Tomcat's HTML pages
Product: Tomcat 8
Version: trunk
Hardware: All
OS: All
Status: NEW
Severity: enhancement
Priority: P2
Component: Documentation
Assignee: dev@tomcat.apache.org
Reporter: prei...@web.de
Hi,
I think there is room for improvements in markup and style of Tomcat's HTML
pages (e.g. to meet current HTML5 [1] standards and not using obsolete
features) in Tomcat 8.
The ROOT index.jsp has alredy greatly been improved by pidster.
There are some other occurences of HTML in Tomcat's source that I think can be
improved:
• Tomcat's error pages
• Examples webapp
• Probably also the Tomcat website (http://tomcat.apache.org/)
Some things that I think of being improvable are:
1) Use always "Full Standards Mode" instead of "Quirks Mode" or "Almost
Standards Mode", as the Quirks mode is kind of a relict that browsers implement
to be able to display Websites that were written for IE <= 5, which had serious
layout errors. However, current Websites should always use Standards Mode as
described in the HTML5 spec [1].
This means that for HTML documents ("text/html"), always use the recommended
doctype <!DOCTYPE html>. For XHTML documents ("application/xhtml+xml"), a
doctype is not needed (as there is only Full Standards Mode), but should be
used if making polyglot documents [2].
Note: Placing a DOCTYPE after a HTML comment (like it is done at pidster's
proposal here: http://people.apache.org/~pidster/tomcat/site/) will force IE 9
and older to use Quirks Mode; however, IE 10 and newer will use Full Standards
Mode in such case. This can be tested by using IE's F12 developer tools.
2) Don't use obsolete HTML elements or attributes, like the ones which are
replaced by CSS as they were purely used for styling and not markup (e.g.
"bgcolor" or "align" attributes, <font> element etc.)
3) A <table> element should only be used for showing real tables, not for
layouting purposes [3], like currently done at the Tomcat Website.
4) Use new HTML5 elements for structuring HTML content, like <nav> (marking a
navigation section), <header>, <footer>; <time datetime="..."> for marking a
date with a machine-readable format and so on.
HTML5 also allows to declare microdata in HTML markup using some new
attributes like "itemscope", "itemtype" etc [9]. E.g. one can use microdata
format provided by http://schema.org/ which should be recognized by Search
Engines like Google, Bing, Yahoo and Yandex (but I don't know if this will be
useful to the Tomcat website).
However, if we still want to support IE versions older than IE9, then care
must be taken when using new HTML elements, because IE <= 8 have a special
parsing method of unknown elements compared to IE9 and other browsers. E.g., if
you have
<myElement class="myHeader">Hi!</myElement>
then the DOM in IE 9/10/11 and other browsers like Firefox represents exactly
that piece of HTML, so if they don't know what a <myElement> element is, they
will still use the CSS defined for class "myHeader" to format it. However in IE
8 and older, the DOM will look like
<myElement></myElement>Hi!</myElement><//myElement>
(this is not valid HTML, but the DOM actually has a element with the name
"myElement" and one with the name "/myElement"), so it will not make use of the
CSS defined for that element.
5) Maybe also historical practices like putting CSS or Javascript into comments
("<style type=...><!-- .myClass {...} --></style>") can be abandoned, as that
was only required for very old browsers that did not know <style> or <script>
elements, to prevent the content of such elements from appearing in a document
as text. However, I cannot think of a still supported browser that would not
recognize such elements.
Note: For XHTML, this approach is actually wrong, because a XML parser will
treat a comment inside of a style element like a comment, which means that the
browser only sees a empty style element. There are ways to make things work if
the document should be both a HTML and a XHTML document [4], but I don't think
it makes sense (see 7) ).
6) Encodings can be set on HTML pages using <meta charset="UTF-8">,
alternatively to <meta http-equiv="Content-Type" value="text/html;
encoding="UTF-8">. I think the shorter form makes more sense because the
Content-Type can only be set externally (by a Header or using a file extension)
before a browser begins with parsing the document. It seems that even IE7
supports the short variant.
Notice that this is for HTML only; for XHTML, the encoding can specified in
the XML header declaration (<?xml version="1.0" encoding="UTF-8"?>).
Note: For the sake of polyglot documents (see 7) ), it is allowed that a
XHTML document also includes a <meta charset="UTF-8" /> - but "UTF-8" is the
only permitted value in this case [8]. Then, also a XML declaration may not be
used as it is forbidden in HTML - this means a XML parser will determine the
encoding from BOM bytes, if present - if not, UTF-8 will be used [7].
Note: Even if the encoding is already set by a Content-Type header, I think
it is a good practice to also include the encoding declaration in the document
itself (of course, matching the one set in the Content-Type header).
7) Some HTML pages contain elements in a XHTML-compatible syntax, e.g.
self-closing elements like "<br />", whereas others contain "<br>". Actually,
when using "<br />" in a document that is sent using "text/html" (or a ".html"
file extension), this was wrong syntax according to previous HTML
specifications, as only "<br>" syntax was allowed (even if a DOCTYPE states
"XHTML 1.0", the browser actually uses a HTML parser instead of a XML parser
when the page is sent with "text/html" instead of "application/xhtml+xml").
However, the new HTML5 specification allows this syntax (<br />) in HTML
documents.
However, when a document is intended to be a polyglot document (i.e. a
document that is compatible with both HTML and XML parsing modes), then there
are a lot of other concerns that one needs to take care of, e.g. not to use
entity references like " " as XML parsers are not guaranteed to process a
external DTD (which would declare such entities), and also the HTML5 spec does
not define any such DTD [5]. Furthermore, always write <input type="checkbox"
checked="checked" itemscope="itemscope" /> instead of <input type=checkbox
checked itemscope> and so on.
However, I think it is easier to write documents that are either HTML only,
or XHTML (XML) only. IE 9 is the first IE that supports XHTML, so I think,
currently, a XHTML-only document is not an option here (whereas I do XHTML-only
documents for my own websites, as I use a XML tool to generate the output and I
don't care about IE <= 8). In this case, I think it is easier to use HTML-only
syntax instead of creating a polyglot document.
Actually, for a person that writes HTML by hand, I think it is easier to
write HTML-only syntax; whereas for documents generated programatically by an
XML writer, the XHTML-only syntax would fit better.
Please add, if I forgot something.
Now, if one is going to improve the markup of a document, I think it is a good
idea to also improve the design/layout.
When I have time (and if you agree) I can start working on the things mentioned
above, unless it is already done by another person ;-)
I see in the archives that Pidster already proposed a new layout for the Tomcat
website [6] (which was the same layout as the ROOT index.jsp), which has not
been accepted yet. I don't have another proposal for a new design of the Tomcat
website atm, but I think the HTML markup can be improved (the points mentioned
above) and the style can be tweaked a bit so that the site doesn't look dated.
What do you think?
[1] http://www.w3.org/TR/html5/
[2] http://wiki.whatwg.org/wiki/HTML_vs._XHTML
[3] http://www.w3.org/TR/html5/tabular-data.html#the-table-element
[4] http://hixie.ch/advocacy/xhtml
[5] http://www.w3.org/TR/html5/the-xhtml-syntax.html#writing-xhtml-documents
[6] http://markmail.org/message/og235cbvrdluiejg
[7] http://www.w3.org/TR/xml/#sec-guessing
[8] http://www.w3.org/TR/html5/document-metadata.html#attr-meta-charset
[9] http://en.wikipedia.org/wiki/Microdata_%28HTML%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
