Bug 55383 - Improve markup and design of Tomcat's HTML pages
Summary: Improve markup and design of Tomcat's HTML pages
Status: NEW
Alias: None
Product: Tomcat 8
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 8.0.x-trunk
Hardware: All All
: P2 enhancement (vote)
Target Milestone: ----
Assignee: Tomcat Developers Mailing List
URL:
Keywords:
: 16579 (view as bug list)
Depends on:
Blocks:
 
Reported: 2013-08-07 20:54 UTC by Konstantin Preißer
Modified: 2016-10-14 18:27 UTC (History)
4 users (show)



Attachments
Example for new markup and style (20.96 KB, text/html)
2013-08-10 16:04 UTC, Konstantin Preißer
Details
Draft for improved HTML markup of Tomcat Docs (48.01 KB, patch)
2013-08-15 23:06 UTC, Konstantin Preißer
Details | Diff
Updated patch for improving HTML markup & style in Tomcat docs (52.47 KB, patch)
2013-08-18 01:15 UTC, Konstantin Preißer
Details | Diff
New Tomcat image to be placed in "trunk/webapps/docs/images/" folder (8.21 KB, image/png)
2013-08-18 01:16 UTC, Konstantin Preißer
Details
Updated patch for improving HTML markup & style in Tomcat docs (41.31 KB, patch)
2013-08-18 01:41 UTC, Konstantin Preißer
Details | Diff
Updated patch for improving HTML markup & style in Tomcat docs (41.33 KB, patch)
2013-08-25 00:11 UTC, Konstantin Preißer
Details | Diff
First part of updated documentation XMLs (175.01 KB, patch)
2013-08-28 00:42 UTC, Konstantin Preißer
Details | Diff
Misaligned display IE8 top (38.04 KB, image/gif)
2013-08-28 23:24 UTC, Sebb
Details
Misaligned display IE8 bottom (19.02 KB, image/gif)
2013-08-28 23:25 UTC, Sebb
Details
Part 2 of updated documentation XMLs (111.10 KB, patch)
2013-08-29 23:46 UTC, Konstantin Preißer
Details | Diff
Part 3 of updated documentation XMLs (113.70 KB, patch)
2013-09-02 15:59 UTC, Konstantin Preißer
Details | Diff
Part 4 of updated documentation XMLs (49.83 KB, patch)
2013-09-03 16:12 UTC, Konstantin Preißer
Details | Diff
Ppatch for improving HTML markup & style in the Tomcat Site (22.64 KB, patch)
2013-09-10 14:35 UTC, Konstantin Preißer
Details | Diff
Missing background color IE9 top (51.08 KB, image/png)
2013-09-11 06:32 UTC, Violeta Georgieva
Details
Broken layout in IE8 (94.51 KB, image/jpeg)
2013-09-11 09:03 UTC, Konstantin Kolinko
Details
Adds work-arounds for IE ≤ 9. (3.35 KB, patch)
2013-09-11 13:15 UTC, Konstantin Preißer
Details | Diff
Adds work-arounds to Tomcat 8 Docs for IE ≤ 9. (3.51 KB, patch)
2013-09-11 13:29 UTC, Konstantin Preißer
Details | Diff
Layout fixes for old browsers without conditional comments (5.64 KB, patch)
2013-09-11 17:37 UTC, Konstantin Preißer
Details | Diff
Doc layout fixes for old browsers without conditional comments (4.46 KB, patch)
2013-09-11 17:39 UTC, Konstantin Preißer
Details | Diff
Updated Tomcat Site XMLs (78.69 KB, patch)
2013-09-12 15:03 UTC, Konstantin Preißer
Details | Diff
Use local ASF image (2.50 KB, patch)
2013-09-19 15:15 UTC, Konstantin Preißer
Details | Diff
Improve markup for Welcome pages (5.78 KB, patch)
2013-09-19 16:09 UTC, Konstantin Preißer
Details | Diff
Improve markup for Tomcat Examples - Part 1 (84.42 KB, patch)
2013-09-19 17:14 UTC, Konstantin Preißer
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Konstantin Preißer 2013-08-07 20:54:30 UTC
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 "&nbsp;" 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
Comment 1 Mark Thomas 2013-08-07 21:21:52 UTC
*** Bug 16579 has been marked as a duplicate of this bug. ***
Comment 2 Mark Thomas 2013-08-07 21:25:38 UTC
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.
Comment 3 Konstantin Preißer 2013-08-10 14:42:06 UTC
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
Comment 4 Konstantin Preißer 2013-08-10 16:04:30 UTC
Created attachment 30719 [details]
Example for new markup and style

I attached an example HTML page with an idea of new HTML markup and tweaked style, that could be used as template for Tomcat Documentation and Tomcat Website.

The layout is very similar to the current one (navigation at left-hand-side), but it should refresh the look so the site doesn't look dated.

There is still room for a completely new layout in the future (like the proposal from pid), but I do not yet have an idea of how a new layout might look like (I'm more a programmer than designer), and my favor was to improve the HTML markup while kepping a similar layout.

The page is HTML but is also viewable as XHTML. It is best viewed at IE10+, Firefox, Chrome etc. (note that Chrome seems to behave differently than IE10 and Firefox with the font line height).
I'm developing mostly on Windows so I used a Windows font (Lucida Sans Unicode) as primary font for the site.

Note that older browsers like IE 9 do not show the layout correctly, but information is still viewable (if people need to view the site with old IE at  corporate PCs for example).

For the code box, overflow:auto is used, so in the XML example with the long unwrappable line, browsers should display a scrollbar below the box (but I needed to use markup like <div class="codeBox><pre><span>...</span></pre></div>" for the style).


What do you think?
Comment 5 Konstantin Preißer 2013-08-15 23:06:51 UTC
Created attachment 30735 [details]
Draft for improved HTML markup of Tomcat Docs

Hi,

as I did not receive negative comments, I tried to apply the new markup and style to the Tomcat Docs XSLT. :-)

Attached is a patch that uses improved HTML markup and a new CSS stylesheet.

Note that I did not work with XSL Transformation before, so I might have done strange things in the XSLT file - I would be glad if some XSLT expert could check that. ;-)


While working in the XSLT file, I found some points on which I'm not clear (maybe someone can comment on these):

1) The xsl:stylesheet element specifies version="1.0"; however, I found that there's already version 3.0 of the XSLT spec [1] (a working draft), so I modified the version attribute to "3.0". Is this OK?


2) Some issues regarding HTML output:

  a) HTML5 specifies for the HTML syntax a recommended doctype of
       <!DOCTYPE html>

     For HTML generators that cannot output such a short doctype, it provides a Doctype Legacy String [2] as follows:
       <!DOCTYPE html SYSTEM "about:legacy-compat">

     However, using the "doctype-system" attribute on the "xsl:output" element, I seem only be able to produce the longer (legacy-compat) doctype, but not the short one.

  In XHTML however, a doctype is not needed as there is no quirks mode.


  b) It seems that when using method="html", the generated .html files always contain the following meta element:
       <META http-equiv="Content-Type" content="text/html; charset=UTF-8">

     so I couldn't use the shorter form:
       <meta charset="UTF-8">

  c) It seems that the library that produces the HTML output does not have a current view of the HTML5 void elements (such as <br>, <img> etc). For example, if I specify <wbr /> in the XSLT, then the generated HTML output will be <wbr></wbr>, although it should be only <wbr>, since this is a void element (specifying html-version="5.0" on the xsl:output element did not change that).

     Note that for XHTML, the XSLT could simply generate <wbr /> for void elements, as well as <div /> for empty non-void elements, as the browser would use a XML parser. This would avoid the need for the XSLT processor to know which elements are void elements.


  I think it could be worth looking at switching to XHTML sometime. However, in this case IE users would have to use at least IE 9, as that is the first IE to support XHTML.



With the modified XSLT, the Doc index.html now validates when using the W3X Non-DTD based validator at http://validator.w3.org/nu/ as opposed to the previous markup which raised about 63 errors and 10 warnings.


What do you think about it?


[1] http://www.w3.org/TR/xslt-30/
[2] http://www.w3.org/TR/html51/syntax.html#the-doctype
Comment 6 Konstantin Preißer 2013-08-18 01:15:13 UTC
Created attachment 30739 [details]
Updated patch for improving HTML markup & style in Tomcat docs

I updated the patch with minor improvements (e.g. replace tabs with spaces, added AL2 to the new CSS file, further improvements of XSLT contents).

I also changed the JavaScript for the Comments section to annotate XSLT-generated strings to the <script> element using the new HTML5 data-* attributes [1] instead of inserting text directly in JavaScript string literals, as that would cause problems if the string data contains special characters.

Furthermore, I added the Tomcat image as normal <img> with a link, instead of using it as background-image.

Note that I had to create a new .png image from tomcat.svg as the previous image was .gif and therefore did not contain alpha transparency.
The patch doesn't contain the image "tomcat-new.png" as it is binary data - is it possible to include such files in a SVN patch?


(In reply to Konstantin Preißer from comment #5)
> 2) Some issues regarding HTML output:
> 
>   a) HTML5 specifies for the HTML syntax a recommended doctype of
>        <!DOCTYPE html>
> 
>      For HTML generators that cannot output such a short doctype, it
> provides a Doctype Legacy String [2] as follows:
>        <!DOCTYPE html SYSTEM "about:legacy-compat">
> 
>      However, using the "doctype-system" attribute on the "xsl:output"
> element, I seem only be able to produce the longer (legacy-compat) doctype,
> but not the short one.

The XSLT and XQuery Serialization 3.0 spec says at point 7.4.6 [2]:

> If the value of the requested HTML version is 5.0, the doctype-public and doctype-system serialization parameters are both absent, the first element node child of the document node that is to be serialized is to be serialized as an HTML element, the local part of the QName of which is equal to the string HTML, without regard to case, and any text node that precedes that element node in document contain only whitespace characters, then the HTML output method MUST output a document type declaration, with no public or system identifier.


That should account for the new HTML5 doctype. However, it seems that the XSLT serialization library used when building Tomcat with Ant does not yet implement this, as it doesn't output a Doctype when setting html-version="5.0".


>   c) It seems that the library that produces the HTML output does not have a
> current view of the HTML5 void elements (such as <br>, <img> etc). For
> example, if I specify <wbr /> in the XSLT, then the generated HTML output
> will be <wbr></wbr>, although it should be only <wbr>, since this is a void
> element (specifying html-version="5.0" on the xsl:output element did not
> change that).

At point 7.1 of the spec [3], it says:

> For HTML5, the void elements are area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track and wbr.

So just like the above point, the XSLT serializer probably doesn't yet implement this.


(In reply to Konstantin Preißer from comment #3)
> This has the advantages over using <table> that
> - 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).

To correct me: A table will not exceed the given width when using "table-layout: fixed" style. This is also true for <table> elements.


[1] http://www.w3.org/TR/html51/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes
[2] http://www.w3.org/TR/xslt-xquery-serialization-30/#HTML_DOCTYPE
[3] http://www.w3.org/TR/xslt-xquery-serialization-30/#HTML_MARKUP
Comment 7 Konstantin Preißer 2013-08-18 01:16:45 UTC
Created attachment 30740 [details]
New Tomcat image to be placed in "trunk/webapps/docs/images/" folder
Comment 8 Konstantin Preißer 2013-08-18 01:41:33 UTC
Created attachment 30741 [details]
Updated patch for improving HTML markup & style in Tomcat docs

Sorry - the previous patch contained the wrong CSS file.
Comment 9 Konstantin Preißer 2013-08-25 00:11:45 UTC
Created attachment 30760 [details]
Updated patch for improving HTML markup & style in Tomcat docs

Hi,

I updated the patch (again, sorry) to:

• use only 1 data-* attribute for the comments identifier to be retrieved in JS.
• replace instances of <h3><a id="...">...</a><h3> with <h3 id="...">...</h3>,
  as it is not needed to use a <a> element to be able to link to a part of a
  document with a fragment identifier (and <a name="..."> is obsolete).
• remove markup that was only needed for a separate printer-friendly version
  of the docs (which was removed with r601180).
• remove markup that was needed for a "status" page which was removed with
  r630006.
Comment 10 Mark Thomas 2013-08-27 09:51:10 UTC
I like it! It is a big improvement on what we have at the moment.

I have your latest patch applied locally after fixing a few minor niggles (trailing whitespace) with the patch.

The only issue I can see at the moment is that the Tomcat logo doesn't show up. I'm inclined to commit this patch just as soon as I have fixed the logo issue.

My current view is that once we are happy with this for 8.0.x (I'm pretty much there - I can't speak for the other committers) we apply similar changes to 7.0.x, 6.0.x and the main Tomcat site (all are built with essentially the same mechanism).
Comment 11 Mark Thomas 2013-08-27 09:55:53 UTC
Figured out the logo issue. I missed the new logo you attached.

I renamed it to tomcat.png - no need for the new bit.
Comment 12 Mark Thomas 2013-08-27 10:18:54 UTC
Patches applied to 8.0.x.

I'm leaving this open for further improvements to 8.0.x as well as possible back-port to 7.0.x, 6.0.x and the website.
Comment 13 Konstantin Preißer 2013-08-27 11:37:53 UTC
Hi Mark,
(In reply to Mark Thomas from comment #12)
> Patches applied to 8.0.x.
> 
> I'm leaving this open for further improvements to 8.0.x as well as possible
> back-port to 7.0.x, 6.0.x and the website.

Great!

Note, for the documentation there are still some things to do in the various XML files (like using "#One_Two_Three" fragment identifiers instead of wrong "#One Two Three" (another correct way would be "#One%20Two%20Three", but the XSLT replaces " " with "_" which also looks better), replacing hard-coded HTML presentational elements/attributes with CSS, and so on.

I will work on these things, (I just wanted to wait on someone reviewing the XSLT before I go on).
Comment 14 Konstantin Preißer 2013-08-27 19:39:16 UTC
Hi,

I noticed that when viewing the doc XML source files from SVN over HTTP, like changlog.xml:
  http://svn.apache.org/repos/asf/tomcat/trunk/webapps/docs/changelog.xml
then the CSS is not applied. Firefox logs an error about wrong MIME type (text/plain instead of text/css).

This is probably because I forgot to set the correct MIME type on the .css stylesheet. I think the following change should fix it:

Index: webapps/docs/images/docs-stylesheet.css
===================================================================
--- webapps/docs/images/docs-stylesheet.css	(revision 1517925)
+++ webapps/docs/images/docs-stylesheet.css	(working copy)

Property changes on: webapps/docs/images/docs-stylesheet.css
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+text/css
\ No newline at end of property



BTW, what do you think about switching from HTML to XHTML for the docs of Tomcat 8 (or next major release)?
I mean:
  - change method attribute on the XSLT from "html" to "xml"
  - change file extension of generated output from ".html" to ".xhtml"
  - change output MIME type from "text/html" to "application/xhtml+xml"

Comparing XHTML over HTML for XSLT-generated content, I currently see the following points:

Pro:
  - The XSLT processor does not need to know how specific HTML elements
    should be outout.
    For example, <wbr> is a void element in HTML5, but currently
    the XSLT processor used by Ant/Java outputs <wbr></wbr>, which is wrong,
    as the XSLT processor does not yet implement the current XSLT and XQuery
    Serialization 3.0 spec [1].
    However, when using XHTML, the browser also uses a XML parser and
    therefore XML Syntax can be used (both <wbr /> or <wbr></wbr> would be
    correct). This avoids the need for the XSLT processor to know how
    specific elements should be output (this also concerns elements like
    <style> and <script> which are output as CDATA in HTML).
  - One does not have to use the "about:legacy-compat" DOCTYPE (as
    work-around until the XSLT processor supports the XLST 3 spec), because
    in XHTML there is only "Full Standards Mode".
    Also, the old-style <meta> element which includes the encoding in a
    Content-Type declaration is not needed.

Contra:
  - IE 9 (released: March 2011; IE 11 will be released soon) is the first IE
    to support XHTML, while all other supported browsers like Firefox, Chrome,
    Opera etc. support XHTML. IE 8 users will get a download dialog instead
    of the page displayed.

Neutral:
  - Because the input (XML files and the XSLT file) is already XML and the
    output will be automatically generated, the output syntax
    (HTML or XHTML) is not of a concern when editing the source XML files.


However, because the file extension would change from .html to .xhtml, such a step can probably only be done at a new major release as otherwise existing links to the pages would stop working.

Using XHTML means that people which use IE 8 or older cannot view the pages. However, one could think that folks with old browsers stay with old Tomcat versions, and folks which use the newest Tomcat 8 also use a current IE.  :D


[1]  http://www.w3.org/TR/xslt-xquery-serialization-30/#HTML_DOCTYPE
Comment 15 Mark Thomas 2013-08-27 20:39:32 UTC
(In reply to Konstantin Preißer from comment #14)
> Hi,
> 
> I noticed that when viewing the doc XML source files from SVN over HTTP,
> like changlog.xml:
>   http://svn.apache.org/repos/asf/tomcat/trunk/webapps/docs/changelog.xml
> then the CSS is not applied. Firefox logs an error about wrong MIME type
> (text/plain instead of text/css).
> 
> This is probably because I forgot to set the correct MIME type on the .css
> stylesheet. I think the following change should fix it:
> 
> Index: webapps/docs/images/docs-stylesheet.css
> ===================================================================
> --- webapps/docs/images/docs-stylesheet.css	(revision 1517925)
> +++ webapps/docs/images/docs-stylesheet.css	(working copy)
> 
> Property changes on: webapps/docs/images/docs-stylesheet.css
> ___________________________________________________________________
> Added: svn:mime-type
> ## -0,0 +1 ##
> +text/css
> \ No newline at end of property

Fixed.

> BTW, what do you think about switching from HTML to XHTML for the docs of
> Tomcat 8 (or next major release)?

Not yet. Some surveys suggest as many as 30% of browsers are IE < 9. That is too big a chunk of the user base to exclude from the docs.

A better analysis would be to look at the access logs for the Tomcat docs. I'm unlikely to have the time to do that for a while.
Comment 16 Rainer Jung 2013-08-27 22:39:08 UTC
> > BTW, what do you think about switching from HTML to XHTML for the docs of
> > Tomcat 8 (or next major release)?
> 
> Not yet. Some surveys suggest as many as 30% of browsers are IE < 9. That is
> too big a chunk of the user base to exclude from the docs.
> 
> A better analysis would be to look at the access logs for the Tomcat docs.
> I'm unlikely to have the time to do that for a while.

After about 22 hours of todays logs: MSIE < 9 is about 12% of all requests to the TC vhost access logs and about 10% of the ones to doc content. "All requests" means all excluding obvious bots.

Of all MSIE requests, MSIE 5-8 are about 50-60%.

More detailed data:

tomcat.apache.org (US)	All			Docs		
UA	Count	Pct	Cum Pct	Count	Pct	Cum Pct
Chrome	63932	41,9%	41,9%	24891	45,3%	45,3%
Firefox	36730	24,1%	66,0%	15889	28,9%	74,3%
Safari	5518	3,6%	69,6%	1670	3,0%	77,3%
AppleWebKit other	165	0,1%	69,7%	71	0,1%	77,5%
Opera	1731	1,1%	70,9%	491	0,9%	78,4%
Varia	11256	7,4%	78,2%	2527	4,6%	83,0%
MSIE 5	414	0,3%	78,5%	8	0,0%	83,0%
MSIE 6	1973	1,3%	79,8%	465	0,8%	83,8%
MSIE 7	3760	2,5%	82,3%	968	1,8%	85,6%
MSIE 8	12530	8,2%	90,5%	3878	7,1%	92,6%
MSIE 9	7526	4,9%	95,4%	2346	4,3%	96,9%
MSIE 10	6981	4,6%	100,0%	1693	3,1%	100,0%
Sum	152516	100,0%		54897	100,0%	
						
MSIE 5-8	18677	12,2%		5319	9,7%	
						
tomcat.apache.org (EU)	All			Docs		
UA	Count	Pct	Cum Pct	Count	Pct	Cum Pct
Chrome	72372	43,7%	43,7%	26923	45,5%	45,5%
Firefox	40208	24,3%	68,0%	17361	29,3%	74,8%
Safari	5920	3,6%	71,5%	2036	3,4%	78,2%
AppleWebKit other	200	0,1%	71,7%	65	0,1%	78,3%
Opera	1745	1,1%	72,7%	620	1,0%	79,4%
Varia	10767	6,5%	79,2%	2538	4,3%	83,7%
MSIE 5	662	0,4%	79,6%	5	0,0%	83,7%
MSIE 6	2005	1,2%	80,8%	314	0,5%	84,2%
MSIE 7	4048	2,4%	83,3%	977	1,6%	85,9%
MSIE 8	12797	7,7%	91,0%	4146	7,0%	92,9%
MSIE 9	8078	4,9%	95,9%	2429	4,1%	97,0%
MSIE 10	6832	4,1%	100,0%	1803	3,0%	100,0%
Sum	165634	100,0%		59217	100,0%	
						
MSIE 5-8	19512	11,8%		5442	9,2%
Comment 17 Konstantin Preißer 2013-08-28 00:42:57 UTC
Created attachment 30772 [details]
First part of updated documentation XMLs

Hi,

I attached a patch with a first part of updated doc XML files to improve the HTML markup and follow up to the new XSLT. The changes include:
- Ensure that a <p> does not contain <pre>, <ul>, <ol> etc. tags.
- Use fragment identifiers that have a space replaced with "_".
- Replace presentational tags/attributes with CSS; only use
  <table> when it is really a table.
- Use CDATA section in <source> elements so that source code/XML examples
  in the doc XMLs is better readable (I hope this is OK).


Mark and Rainer,
(In reply to Mark Thomas from comment #15)
> Not yet. Some surveys suggest as many as 30% of browsers are IE < 9. That is
> too big a chunk of the user base to exclude from the docs.

(In reply to Rainer Jung from comment #16)
> After about 22 hours of todays logs: MSIE < 9 is about 12% of all requests
> to the TC vhost access logs and about 10% of the ones to doc content. "All
> requests" means all excluding obvious bots.

I agree that 30% IE < 9 users is still too many to switch to XHTML now (probably even the 12%).
(Argh - Old IEs keep being a nightmare for web designers :)
Comment 18 Christopher Schultz 2013-08-28 14:47:08 UTC
Re: XHTML (or application/xml), I think it's reasonable to clean-up our documentation such that the documents would pass an XHTML validator, so that when the day comes to make the switch, we just switch the content-type and associated <META> tags, etc.

My experience is that MSIE 8 and 9 don't completely choke on XML documents, but it does force the browser into compliance-mode which is definitely nice (e.g. sane box model, etc.).

Mark: is there anywhere online we can see a sample of the newly-formatted documentation, or do we have to build it from svn?
Comment 19 Mark Thomas 2013-08-28 14:59:51 UTC
The CI system makes the latest build of the docs available to view:

http://ci.apache.org/projects/tomcat/tomcat8/docs/
Comment 20 Sebb 2013-08-28 23:24:57 UTC
Created attachment 30778 [details]
Misaligned display IE8 top
Comment 21 Sebb 2013-08-28 23:25:31 UTC
Created attachment 30779 [details]
Misaligned display IE8 bottom
Comment 22 Sebb 2013-08-28 23:28:26 UTC
The display looks a bit odd in IE8 (WinXP).

The images in the top row don't display correctly.

The bottom row is missing the text "Comments are disabled for this page at the moment." and the horizontal line below it.

Also the Copyright line at the bottom is not centred.

See attached screen prints.
Comment 23 Mark Thomas 2013-08-29 09:11:55 UTC
(In reply to Konstantin Preißer from comment #17)
> Created attachment 30772 [details]
> First part of updated documentation XMLs

Patch applied with tabs -> 4 spaces and trailing whitespace removed.


> I agree that 30% IE < 9 users is still too many to switch to XHTML now
> (probably even the 12%).
> (Argh - Old IEs keep being a nightmare for web designers :)

I'm afraid so. Given we'd like to extend this work to docs for all current versions and the main Tomcat website, 12% is too high a percentage to exclude.
Comment 24 Konstantin Preißer 2013-08-29 09:46:14 UTC
Hi Sebb,

(In reply to Sebb from comment #22)
> The display looks a bit odd in IE8 (WinXP).
> 
> The images in the top row don't display correctly.
> 
> The bottom row is missing the text "Comments are disabled for this page at
> the moment." and the horizontal line below it.
> 
> Also the Copyright line at the bottom is not centred.
> 
> See attached screen prints.

thanks for your feedback about IE8.

When updating the markup and design, I tried to orientate on new Standards (HTML5 and CSS3) which current browsers support. Unfortunately, IE8 does not support much of these new standards. Therefore the design looks a bit odd in IE8.

My thoughts were, "If people use a current browser, they will get the correct layout. However if they use an old browser like IE8, they could get a odd layout, but the information they search for (documentation) is still available".

E.g. the JavaScript does not work in IE8 because of the "application/javascript" type that is first supported by IE9 (IE8 also lacks a lot of current JS functionality).

Do you think we should add work-arounds for old browsers like IE8 (e.g. creating a IE8-CSS that is included with conditional comments)?
Comment 25 Konstantin Preißer 2013-08-29 23:46:51 UTC
Created attachment 30786 [details]
Part 2 of updated documentation XMLs

Hi,

here is another part of updated Documentation XMLs.

Note: I also modified the CSS to make tables look a bit better (use different colors for odd and even rows).
Comment 26 Mark Thomas 2013-08-30 07:39:55 UTC
(In reply to Konstantin Preißer from comment #25)
> Created attachment 30786 [details]
> Part 2 of updated documentation XMLs

Applied. Many thanks.
Comment 27 Konstantin Preißer 2013-09-02 15:59:03 UTC
Created attachment 30793 [details]
Part 3 of updated documentation XMLs

Hi,

here is another part of updated Documentation XMLs.

I modified the CSS so that a table with class="detail-table" looks the same as class="defaultTable". If you don't like it, you (or I) can change it so that a detail-table has different colors.

When working through the documentation, I found the following page (and others in appdev):
http://tomcat.apache.org/tomcat-8.0-doc/appdev/installation.html

which seemed a bit outdated, as it mentioned Tomcat 7 and Java 6 (I updated it to Tomcat 8 and Java 7), but it also mentions CVS (I guess this was written before SVN existed).

Furthermore, this example web.xml:
http://tomcat.apache.org/tomcat-8.0-doc/appdev/web.xml.txt
declares itself as "Web Application 2.3" instead of 3.1.


Note, that I also modified the HTTP and AJP configuration pages so that the Connector Comparison Chart is now using a <table>, instead of plain text, as it is tabular data.
Comment 28 Mark Thomas 2013-09-03 12:41:58 UTC
(In reply to Konstantin Preißer from comment #27)
> Created attachment 30793 [details]
> Part 3 of updated documentation XMLs

Patch applied. Many thanks.
Comment 29 Konstantin Preißer 2013-09-03 16:12:38 UTC
Created attachment 30797 [details]
Part 4 of updated documentation XMLs

Hi,

here is the final part of the documentation update.
With this patch, the improvement of HTML markup in the Tomcat 8 docs should be complete.

Note: In the doc about the DefaultServlet [1], I also modified a dead link to Servlet 2.3 to point to http://jcp.org/en/jsr/detail?id=340 (Servlet 3.1).


(In reply to Mark Thomas from comment #10)
> My current view is that once we are happy with this for 8.0.x (I'm pretty
> much there - I can't speak for the other committers) we apply similar
> changes to 7.0.x, 6.0.x and the main Tomcat site (all are built with
> essentially the same mechanism).

I think I can look into applying the new markup/design for the main Tomcat Site now.


[1] http://tomcat.apache.org/tomcat-8.0-doc/funcspecs/fs-default.html
Comment 30 Mark Thomas 2013-09-05 14:17:59 UTC
(In reply to Konstantin Preißer from comment #29)
> With this patch, the improvement of HTML markup in the Tomcat 8 docs should
> be complete.

Applied. Many, many thanks.

> I think I can look into applying the new markup/design for the main Tomcat
> Site now.

Fantastic. Go for it.
Comment 31 Konstantin Preißer 2013-09-10 14:35:45 UTC
Created attachment 30809 [details]
Ppatch for improving HTML markup & style in the Tomcat Site

Hi,

here is a patch for the main Tomcat Site to improve the HTML markup and the layout, similar to the one for Tomcat 8 Doc.

The added image (xdocs/images/tomcat.png) is the same one as in attachment 30740 [details].
Comment 32 Mark Thomas 2013-09-10 19:23:46 UTC
(In reply to Konstantin Preißer from comment #31)
> Created attachment 30809 [details]
> Patch for improving HTML markup & style in the Tomcat Site

Patch applied. Waiting for the reaction on the users mailing list...

I haven't enjoyed committing a patch so much in ages. Thank you. It is a huge improvement. But don't let that stop you trying to make it even better ;)
Comment 33 Violeta Georgieva 2013-09-11 06:32:52 UTC
Created attachment 30812 [details]
Missing background color IE9 top

The background color on the top is missing when using IE9. See the attached screenshot.
Comment 34 Konstantin Kolinko 2013-09-11 09:03:11 UTC
Created attachment 30813 [details]
Broken layout in IE8

In IE8 (WinXP) the background color is missing as well.

Plus to that the top of the page is broken.
The Tomcat cat and Apache Feather images are located above the page title, instead of floating at the left/right sides of it.
Comment 35 Konstantin Preißer 2013-09-11 12:40:11 UTC
Hi,
(In reply to Violeta Georgieva from comment #33)
> The background color on the top is missing when using IE9. See the attached
> screenshot.

I think this is because "background: linear-gradient(...)" CSS is first supported by IE 10.

(In reply to Konstantin Kolinko from comment #34)
> Created attachment 30813 [details]
> Broken layout in IE8
> 
> In IE8 (WinXP) the background color is missing as well.
> 
> Plus to that the top of the page is broken.
> The Tomcat cat and Apache Feather images are located above the page title,
> instead of floating at the left/right sides of it.

I think this is because I used new HTML5 elements like <header id="header"> which have a DOM in IE8 as <header id="header"></header>...</header><//header>, so the CSS doesn't apply to them. One would have to use something like <header><div id="header">...</div></header> for it to work in IE8.

I hoped it wouldn't be necessary, but I will look into adding workarounds for old IEs. :)
Comment 36 Konstantin Preißer 2013-09-11 13:15:21 UTC
Created attachment 30814 [details]
Adds work-arounds for IE ≤ 9.

This patch adds work-arounds for IE ≤ 9 to fix the layout on these IE versions.

I used conditional comments to include a IE fix CSS file, and to use <div id="..."> for IE ≤ 9, while IE ≥ 10 and other browsers will use <header id="..."> as IE 10 dropped support for conditional comments in Full Standards Mode.
Comment 37 Konstantin Preißer 2013-09-11 13:29:53 UTC
Created attachment 30815 [details]
Adds work-arounds to Tomcat 8 Docs for IE ≤ 9.

This one adds the same work-arounds to the Tomcat 8 docs.
Comment 38 Mark Thomas 2013-09-11 13:50:25 UTC
Applied. Many thanks.
Comment 39 Konstantin Preißer 2013-09-11 17:37:29 UTC
Created attachment 30818 [details]
Layout fixes for old browsers without conditional comments

After Mark applied the patch, it turned out that the conditional comments for the IE fixes broke the CGI scripts on the download pages (see [1]). I'm sorry for that.

Therefore, this patch adds layout fixes for IE <= 8 and and old Firefoxes (3.x) without using conditional comments.


[1] http://markmail.org/message/rya7c6iu6vvbdkmw
Comment 40 Konstantin Preißer 2013-09-11 17:39:17 UTC
Created attachment 30819 [details]
Doc layout fixes for old browsers without conditional comments

This one will apply the changes to the Tomcat 8 docs.
Comment 41 Mark Thomas 2013-09-11 20:10:08 UTC
Both applied. Thanks.
Comment 42 Konstantin Preißer 2013-09-12 15:03:59 UTC
Created attachment 30824 [details]
Updated Tomcat Site XMLs

Hi,

this patch improves the markup in the Tomcat Site XMLs. After applying, the HTMls should validate against a HTML5 validator.
Comment 43 Mark Thomas 2013-09-18 08:01:40 UTC
(In reply to Konstantin Preißer from comment #42)
> Created attachment 30824 [details]

> this patch improves the markup in the Tomcat Site XMLs. After applying, the
> HTMls should validate against a HTML5 validator.

Patch applied. Thanks again.
Comment 44 Konstantin Preißer 2013-09-19 15:15:31 UTC
Created attachment 30862 [details]
Use local ASF image

Hi,

previously, for the Tomcat docs I used this URL for the Apache Logo (an alphatransparent PNG): http://www.apache.org/images/feather.png
However, as the Tomcat Docs are included in the release package, I think it should use a local image instead.

The image added by the patch (webapps/docs/images/asf-feather.png) is the one from the above URL.

The patch also removes the line 'Loading comments…' as it is not removed by the Comments script.
Comment 45 Konstantin Preißer 2013-09-19 16:09:10 UTC
Created attachment 30863 [details]
Improve markup for Welcome pages

This patch improves the HTML markup in the Welcome pages (welcome.main.html and welcome.bin.html).
Comment 46 Konstantin Preißer 2013-09-19 17:14:16 UTC
Created attachment 30864 [details]
Improve markup for Tomcat Examples - Part 1

Hi,

this patch improves the HTML markup in the Tomcat Examples webapp (currently, only the index pages and the websocket examples).

Note: For the WebSocket examples, I switched from HTML to XHTML because every browser that supports WebSockets (e.g. IE >= 10) also supports XHTML (e.g. IE >= 9), and because the Snake Example contained an XHTML doctype (but was not fully XHTML-compatible).
Comment 47 Mark Thomas 2013-09-19 20:52:55 UTC
Patches all applied. Thanks.
Comment 48 Konstantin Preißer 2013-10-15 23:32:52 UTC
Improvements of design and markup have been applied to the Tomcat Native documentation (to match Tomcat 8 documentation) and will be included in TC-Native 1.1.30 onwards.
Comment 49 Konstantin Preißer 2013-11-05 18:26:35 UTC
Hi,

I'd like to switch the font used for the Tomcat Website and Docs (currently "Lucida Sans Unicode") to "Open Sans" [1] which is released by Google using a Apache 2.0 Licence. This also means that the font can be displayed on every platform like Windows, Mac and Linux.

I plan to add the Font files (.woff) (the variant which contains only the Latin characters) directly instead of using a CSS link to Google, so that the Site and the Docs (which may be viewed offline) don't depend on external Google resources.

Is it OK to commit?


[1] http://www.google.com/fonts/specimen/Open+Sans
Comment 50 Christopher Schultz 2013-11-05 18:58:11 UTC
(In reply to Konstantin Preißer from comment #49)
> I'd like to switch the font used for the Tomcat Website and Docs (currently
> "Lucida Sans Unicode") to "Open Sans" [1] which is released by Google using
> a Apache 2.0 Licence. This also means that the font can be displayed on
> every platform like Windows, Mac and Linux.

It's worth noting that the current CSS for font-family is just a suggestion to the browser. The font you get depends very heavily on the environment where the pages are being viewed.

> I plan to add the Font files (.woff) (the variant which contains only the
> Latin characters) directly instead of using a CSS link to Google, so that
> the Site and the Docs (which may be viewed offline) don't depend on external
> Google resources.

I'm not a huge fan of WOFF for a few reasons:

1. It requires yet another file to download, and font files tend to be big (I couldn't find a download link so I don't know the exact size of the Open Sans font).

2. Most browsers I've seen tend to render the page as quickly as possible, and then apply the custom-font afterward, which results in a weird post-adjustment of the font, even for fonts that are already downloaded. I haven't done extensive testing recently, so it's possible that this is no longer an issue.

3. Ultimately, the font choice is up to the browser, anyway, so you can't really "force" them to use Open Sans.

Given the above, why bother with a change at all? I know designers get all hot and bothered by things like kerning, serif angles, etc. but I'm not sure that adding another font-choice here really adds anything.
Comment 51 Konstantin Preißer 2013-11-05 19:42:58 UTC
Hi Christopher, thanks for your comments.

(In reply to Christopher Schultz from comment #50)
> (In reply to Konstantin Preißer from comment #49)
> > I'd like to switch the font used for the Tomcat Website and Docs (currently
> > "Lucida Sans Unicode") to "Open Sans" [1] which is released by Google using
> > a Apache 2.0 Licence. This also means that the font can be displayed on
> > every platform like Windows, Mac and Linux.
> 
> It's worth noting that the current CSS for font-family is just a suggestion
> to the browser. The font you get depends very heavily on the environment
> where the pages are being viewed.
> 
> > I plan to add the Font files (.woff) (the variant which contains only the
> > Latin characters) directly instead of using a CSS link to Google, so that
> > the Site and the Docs (which may be viewed offline) don't depend on external
> > Google resources.
> 
> I'm not a huge fan of WOFF for a few reasons:
> 
> 1. It requires yet another file to download, and font files tend to be big
> (I couldn't find a download link so I don't know the exact size of the Open
> Sans font).

Google Fonts allows to explicitely select the charsets which should be included in the Font, to keep the file sizes down. E.g. in this case it would be (400, 400 italics, 600, 600 italics): 84 KB, which should be an acceptable size in today's relations (e.g. the ASF feather PNG image (asf-feather.png) has 40 KB).

> 2. Most browsers I've seen tend to render the page as quickly as possible,
> and then apply the custom-font afterward, which results in a weird
> post-adjustment of the font, even for fonts that are already downloaded. I
> haven't done extensive testing recently, so it's possible that this is no
> longer an issue.

This applies if you visit the page the first time: Some browsers (Firefox) will display the page with an alternate font until the WOFF is downloaded, then switch to the WOFF. Other browsers (Chrome) will display spaces until the WOFF is loaded.

However, after that if you browse on other pages then the WOFF is already in the cache and the browser will use it immediately (at least this is the case with Firefox, IE and Chrome), so there should be no issues when browsing through various links on the site.

> 3. Ultimately, the font choice is up to the browser, anyway, so you can't
> really "force" them to use Open Sans.

Yes (but this should also be the case with local fonts).

> 
> Given the above, why bother with a change at all? I know designers get all
> hot and bothered by things like kerning, serif angles, etc. but I'm not sure
> that adding another font-choice here really adds anything.

I'm also not a designer but I think it looks a bit more modern than the currently used Lucida Sans Console (and as it is a platform-independent format, other platforms will be able to use the font).

I use it on my own websites and e.g. this site uses it: http://www.html5rocks.com/en/tutorials/websockets/basics/
Comment 52 Konstantin Kolinko 2013-11-30 19:28:27 UTC
(In reply to Konstantin Preißer from comment #49)
> 
> [1] http://www.google.com/fonts/specimen/Open+Sans

The *.woff that you committed in r1546663 - where do they come from?

I am worried whether we need to add some attribution if we are redistributing them,
and how do we get updates for them if there are any.

Thus far I have two trails
a) Google Code repository for Google Fonts project, [2].

There are *.ttf files.

b) I went to [1] clicked on "Open Open Sans in Google Fonts" which navigated to [3].

At [3] I click "download" button (a small "down arrow" button at the top-right part of the page). It downloads a 1.2Mb zip that contains 10 *.ttf files and LICENSE.txt (a copy of Apache License 2.0).

[2] https://code.google.com/p/googlefontdirectory/source/browse/apache/opensans/
[3] https://www.google.com/fonts#UsePlace:use/Collection:Open+Sans

So thus far
1. It is clear that the files are covered by Apache License 2.0
2. There is no NOTICE file
3. These are *.ttf files, not *.woff ones.
Comment 53 Konstantin Preißer 2013-12-01 16:11:13 UTC
Hi Konstantin,
thank you for the review.

(In reply to Konstantin Kolinko from comment #52)
> (In reply to Konstantin Preißer from comment #49)
> > 
> > [1] http://www.google.com/fonts/specimen/Open+Sans
> 
> The *.woff that you committed in r1546663 - where do they come from?
> 
> I am worried whether we need to add some attribution if we are
> redistributing them,
> and how do we get updates for them if there are any.

I took the .woff files by going to [3], selecting the needed fonts, and then opening the generated CSS link [4].

This is a Google-generated CSS that contains links to .ttf, .woff and other formats depending on the browser. I then downloaded the .woff ones.

If there's a problem with taking these .woff files directly, I think it should be possible to use some tool to convert the .ttf to .woff files (but then one needs to take care not include only specific characters of the font, to reduce the file size).

> Thus far I have two trails
> a) Google Code repository for Google Fonts project, [2].
> 
> There are *.ttf files.
> 
> b) I went to [1] clicked on "Open Open Sans in Google Fonts" which navigated
> to [3].
> 
> At [3] I click "download" button (a small "down arrow" button at the
> top-right part of the page). It downloads a 1.2Mb zip that contains 10 *.ttf
> files and LICENSE.txt (a copy of Apache License 2.0).
> 
> [2]
> https://code.google.com/p/googlefontdirectory/source/browse/apache/opensans/
> [3] https://www.google.com/fonts#UsePlace:use/Collection:Open+Sans
> 
> So thus far
> 1. It is clear that the files are covered by Apache License 2.0
> 2. There is no NOTICE file
> 3. These are *.ttf files, not *.woff ones.

[4] http://fonts.googleapis.com/css?family=Open+Sans:400,400italic,600,600italic,700,700italic
Comment 54 Michael Osipov 2016-10-14 18:27:56 UTC
Hi Konstantin,

tremendous improvement with a lot of effort put it. Thank you very much for that!