Extension:WebFonts

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

MediaWiki extensions manual - list

WebFonts Release status: beta
Implementation	User interface, Skin
Description	Embed fonts on pages
MediaWiki	1.17, 1.18
License	GNU General Public Licence 3.0 or later
Download	Download snapshot Subversion [Help] Browse source code View code changes
Check usage (experimental)

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 WebFonts under $IP/extensions/ 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:

require_once( "$IP/extensions/WebFonts/WebFonts.php" );

Configuration parameters

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

 $wgWebFontsEnabledByDefault = true;

• To enable or disable the web fonts, the user can go to My Preferences -> Appearance -> Enable font embedding (WebFonts)

By default, the preference page option to enable web fonts is set based on the value of $wgWebFontsEnabledByDefault

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: <FilesMatch "\.(gif|jpe?g|png|css|js|woff|svg|eot|ttf)$">
• 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.

Supported languages

Language	Fonts	Upstream
Ahirani	Lohit Devanagari	Lohit Project, Red Hat
Amharic	Abyssinica SIL	SIL
Assamese	Lohit Assamese	Lohit Project, Red Hat
Bengali	Lohit Bengali,Siyam Rupali	Lohit Project, Red Hat
Bhojpuri	Lohit Devanagari	Lohit Project, Red Hat
Bishnupria Manipuri	Lohit Bengali	Lohit Project, Red Hat
Buginese	Saweri (for Lontara script)	Saweri
Gujarati	Lohit Gujarati	Lohit Project, Red Hat
Hebrew	Miriam CLM	Culmus
	Taamey Frank CLM	Culmus
Hebrew-Old	Taamey Frank CLM	Culmus
Hindi	Lohit Devanagari	Lohit Project, Red Hat
	Samyak Devanagari	Samyak
Kannada	Lohit Kannada	Lohit Project, Red Hat
	Kedage	Sanchaya
Khmer	KhmerOSbattambang, KhmerOSsiemreap, KhmerOS, KhmerOSbokor, KhmerOSmuollight, KhmerOSmuol, KhmerOSmuolpali, KhmerOSfreehand	KhmerOS
Konkani	Lohit Devanagari	Lohit Project, Red Hat
Makassarese	Saweri (for Lontara script)	Saweri
Malayalam	AnjaliOldLipi	Varamozhi Project
	Meera	SMC
	RaghuMalayalam	SMC
Maithili	Lohit Devanagari	Lohit Project, Red Hat
Marathi	Lohit Devanagari	Lohit Project, Red Hat
	Samyak Devanagari	Samyak
Min Dong Chinese	Charis SIL	SIL
Myanmar	Masterpiece Uni Sans	Prahita
	Padauk-Regular	SIL
	Myanmar3	Myanmar Unicode & NLP Research Center
	Yunghkio	Yunghkio
Odia	Lohit Oriya	Lohit Project, Red Hat
	Utkal	Oriya, Sarovar
Punjabi	Lohit Punjabi	Lohit Project, Red Hat
	Saab	GUCA
Persian	IranianSans	Iranian National Initiative for FOSS
Sourashtra	Pagul	Pagul
Sanskrit	Lohit Devanagari, Samyak Devanagari	Lohit Project, Red Hat
Tamil	Lohit Tamil	Lohit Project, Red Hat
	Thendral	Thamizha
	Thenee	Thamizha
Telugu	Lohit Telugu	Lohit Project, Red Hat
	Pothana2000	K.Desikachary
	Vemana2000	K.Desikachary
Tigrinya	Abyssinica SIL	SIL

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 -lang=ff
  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 -lang=ff
  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

'FontName' : {
    eot: "Script_code/FontName.eot",
    ttf: "Script_code/FontName.ttf",
    woff: "Script_code/FontName.woff",
}

• (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.

normalization : {
    "searchString1": "replaceString1",
    "searchString2": "replaceString2",
}

• 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.

    hi: [ 'Samyak Devanagari', 'Lohit Hindi' ]

Alternate ways to load fonts

By specifying font-family

Inside the wiki text <span style="font-family:'YourFontName';">YourText</span>, 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 <span lang="my">YourText</span>, 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 Chrome 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 of 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
• translatewiki:WebFonts assessment
• The Free Software Foundation's page about free licenses for fonts
• Code review of this extension