Extension:WebFonts

This is technical documentation of the extension. There is also a user documentation

What can this extension do?
Many languages do not have proper fonts easily available to users. This may be because the operating systems do not ship these fonts, the script has fonts but users don't know from where they will get them or how to install them in their system, or even the user is reading the wiki from a shared computer without these fonts. Sometimes it may be because the user does not know how to configure the operating system for a language or the user does not have enough permissions to do this. Because of all these reasons, providing the content in certain languages is facing issues. This extension tries to solve this by embedding the fonts in the wiki itself. Fonts will be served from the server and the user's system would not need to have the fonts installed.

Usage
When the extension is installed and enabled, along with the login, preferences link in the wiki page, a menu will appear to select a font for the page. By default, the first font in that menu will be applied to the wiki. A user can change the font and it will be remembered across the pages. Optionally user can disable the font embedding too, this choice will also remembered across pages, even for next visits, for 30 days.

If the font is available in user's local system, font will not be downloaded from the mediawiki server. It will be taken from the user's computer. Otherwise, font will be downloaded from the server only once. ie when the user selects the font first time. Next time onwards, font will be taken from the local cache.

Download instructions
Download WebFonts and put it in to a directory named  under   Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

Installation
To install this extension, add the following to LocalSettings.php:

Configuration parameters

 * Whether the web fonts should be active as default or not

By default, the preference page option to enable web fonts is set based on the value of $wgWebFontsEnabledByDefault
 * To enable or disable the web fonts, the user can go to My Preferences -> Appearance -> Enable font embedding (WebFonts)

Caching configuration
To ensure that the web fonts files are cached on the clients' machines, font file types must be added to the web server configuration. In Apache2 this consists of:
 * Adding font file extensions to the FileTimes regex at FilesMatch for the relevant directory, example:
 * Adding ExpiresByType values to the relevant MIME types, similarly to image MIME types.
 * Note that there's no standard MIME type for TTF. application/x-font-ttf is used for Wikimedia.
 * Adding the MIME types:
 * AddType application/x-woff .woff
 * AddType application/vnd.ms-fontobject .eot
 * AddType application/x-font-ttf .ttf

For a full example see the caching configuration update done for the Wikimedia cluster.

Adding a new language support
Basic knowledge about GNU/Linux based operating system is required to follow the below steps. If you feel difficulty in following this, file an enhancement bug against WebFonts extension in Mediawiki bugzilla.

Please note that we will add support only for Freely Licensed fonts, for example fonts licensed under GNU GPL, SIL OFL, etc.

Preparing webfonts
Fontforge can be used to generate a truetype font from its source file ie sfd file. SFD is not mandatory. If you have truetype font (.ttf) open it with fontforge, File->Generate Fonts .. Select any of the above format.

You cannot create eot font using fontforge. Use http://code.google.com/p/ttf2eot/ for converting it. Install the tool, run

ttf2eot yourfont.ttf > yourfont.eot

The font conversion can also be scripted using fontforge scipting feature. See fontforge.sourceforge.net/scripting-tutorial.html.

For example, to convert a truetype font to svg, use the following fontforge script

#!/usr/bin/fontforge Open($1) Generate($1:r + ".svg")

You may save this script to a file named say, ttf2svg.pe, give execution permission and execute like this

./ttf2svg.pe yourfont.ttf

Similarly, for creating a WOFF font:

#!/usr/bin/fontforge Open($1) Generate($1:r + ".woff")

Adding fonts

 * Place the eot, ttf, woff font files inside the matching folder. The fonts are sorted under WebFonts/fonts folder in folders named according to ISO 15924 script codes. If a folder for your script doesn't exit, create it.
 * Open js/webfonts.fontlist.js and add an entry for the font. You may refer the existing fonts or use the following syntax
 * (Optional) If you want to do some normalization on the page content when you display it the font, such are replacing certain characters with other characters, you can specify it as normalization rules.
 * Add a entry to the languages section of the file. The following example maps two fonts to Hindi (hi is Hindi's ISO 639 language code). The first font will be used as default font. The font names should match with the font name we used above.

By specifying font-family
Inside the wiki text YourText, webfonts extension will check whether the font is available with the extension, if so it will download it to the client. So the reader will not face any difficulty in reading the text even if the font specified is not available in their computer.

By specifying language
Inside the wiki text YourText, webfonts extension will check whether any font is available for the given language with the extension, if so it will download it to the client. So the reader will not face any difficulty in reading the text even if the font specified is not available in their computer. If there are multiple fonts for the language, the default font will be used. If default font is not preferred, use the font-family approach to specify the font. If the tag has both lang and font-family definitions, font-family get precedence.

Supported Skins
Vector, Monobook and Modern.

Known issues

 * IE 6 is not capable of doing font-fallback properly. Because of this, if the page contains text within elements having no lang information, squares are getting displayed. The extension is disabled in IE 6 browser. See bug report.
 * IE 8 sometimes shows junk characters on the screen instead of the actual text in the specified font. The issue is not always reproducible and disappears upon page refresh. The junk characters may be because of a partially downloaded font. See Bug 32775.
 * Google chrome (chromium too) upto version 15 has a bug that cause some complex script webfont being rejected by the browser. This issue is observed only for Meera font of Malayalam. The OTS tool does not show any errors in the font. But the issue is not present in Chrome 17. See Bug report.
 * In Mac OS X 10.7, Opera browser is not capable of rendering complex scripts like Malayalam. See our detailed test report about various OS-browser combinations. Also see Bug 31823 - Opera 11.51 does not display saz font.
 * Google Crome on Windows XP dispays gibberish - Observed very rarely on a page on Wikimedia Incubator, and we have not been able to reproduce this observation, let alone reproduce it reliably. A screenshot is present in the bug report. Except for reporting upstream, no action is being taken on this issue at this point in time.
 * OSX 10.7.2/Opera 11.60 has no fallback for Latin characters.

Reporting issues
While we are constantly trying to improve the quality of fonts and scripts coverage, it is quite possible that you notice issues with the provided fonts in terms or missing glyphs, wrong rendering, low quality rendering etc. Please report that issues to us using Bugzilla and we will work with upstream font maintainers to resolve such bugs.

More information

 * Writing systems - information on writing systems in MediaWiki
 * Fonts on the Web -W3C- http://www.w3.org/Fonts/
 * CSS3 WebFonts specification - http://www.w3.org/TR/css3-fonts/
 * @font-face performance
 * WebFonts assessment
 * The Free Software Foundation's page about free licenses for fonts
 * Code review of this extension