{% extends "base.html" %}
{% block meta_title %}Glyphviewer Documentation{% endblock %}
{% block meta_keywords %}font, ttf, otf, woff, glyph, character, Unicode{% endblock %}
{% block meta_description %}An application to analyse font files.{% endblock %}
{% block title %}Glyphviewer Documentation{% endblock %}
{% block main %}
    <h2 id="what">What is Glyphviewer?</h2>
    <p><strong><a href="/glyphviewer/">Glyphviewer</a></strong> is a web application that analyses web font files.</p> 
    <ul><li>It lists the characters supported by a font using its glyphs. 
    This is the raison d'être for the application.</li> 
<li>It displays information present in the font's header, such as developer and license details.</li>
<li>It provides a test bed for users to enter their own message, and see it displayed using the font.</li></ul> 
<p id="why"><em>For those unsure about the meaning of &quot;glyph&quot;, &quot;font&quot;, and &quot;web font&quot;, 
a small <a href="#techappendix">glossary</a> is provided at the end.</em></p>
        <h2 id="usage">Glyphviewer Usage</h2>
    <p>Glyphviewer analyses font files, not fonts per se. (A font may consist of multiple files.) 
    Permissible formats are TrueType (.ttf), 
    OpenType (.otf), and best of all, <a href="http://www.w3.org/TR/WOFF/">Web Open Font Format</a> (.woff). 
    WOFF is preferred, because font data is compressed by design, resulting in quicker download.</p>
    <ul><li>Users will find it easiest to analyse a web font file stored on the server hosting this application. This is 
    Glyphviewer's <em>default</em> behavior: when a user first encounters this page, the application
    randomly selects one from its file system, and analyses it for inspection. Viewers can choose other
    font files stored locally, as long as <strong>Local</strong> is checked; they just select an item 
    from the <strong>File</strong> drop down list. All fonts are listed by file name, so <strong>File</strong>
    will display (say) &quot;DejaVuSans.woff&quot; rather than &quot;DejaVu Sans&quot;.</li> 
<li>More adventurous users can choose a font somewhere else on the Internet by checking 
<strong>Remote</strong> instead. They write the full URL for the font file (including the extension) in 
the <strong>URL</strong> control. For example, here's an 
<a href="http://themes.googleusercontent.com/static/fonts/lato/v6/9k-RPmcnxYEPm8CNFsH2gg.woff">URL</a>
for the Lato web font ready for copying-and-pasting. However, the remote font must be accessible for sharing under
<a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-origin Resource Sharing</a> (CORS).</li></ul>
<p>Other controls present are:</p>
<ul><li><strong>Shows characters in font</strong>: If checked, all characters in the font 
are presented as a table to the user (with the exception of any line breaks and control characters present inside). 
The advantage is that users
can discover which characters and languages are supported by the font. Moreover, people can inspect 
individual glyphs for legibility and appearance. The disadvantage is that the resulting page can be quite large.</li> 
<li><strong>Arrange characters as Unicode blocks</strong>: If checked, Glyphviewer splits characters into 
different tables according to their Unicode blocks. If not checked, all characters are displayed in one gigantic
table. If <strong>Shows characters in font</strong> is not selected, this checkbox is ignored altogether.</li></ul>
<p>To finish, users hit the <strong>Submit</strong> button.</p>
    <h3 id="success">On Success</h3>
    <p>If <a href="/glyphviewer/">Glyphviewer</a> succeeds, it will generate a page 
    with the following sections.</p>
    <ul><li><strong>General information</strong>: This data is taken from the font's header; it generally 
    includes details such as name, designer, and copyright information. The last piece of data is extremely useful
    to know, as it may indicate whether the font is <em>legally</em> free to use or not.</li>
      <li><strong>Testbed</strong>: This provides an area where users can play around with the font. 
      Fields of interest are:
      <ul><li><strong>Enter some text to try out the font</strong>: This is a multi-line field for changing the message 
      (because &quot;Hello World!&quot; gets boring quickly).</li>
        <li><strong>Font size (in pixels)</strong>: This sets the size of the message text in pixels. 
        But to actually resize the text, one has to click...</li>
        <li><strong>Try it</strong>: This rewrites and redisplays the message.</li>
        <li><strong>Reset</strong>: This resets the message to the default text and size.</li>
</ul></li>
    <li><strong>Supported characters</strong>: if <strong>Shows characters in font</strong> is selected, 
    Glyphviewer will generate a table (or tables) of the characters provided by the font. For maximum utility,
    characters will be displayed using the actual glyphs in the font, and each character is displayed with 
    its Unicode code point underneath. However, some fonts include characters such as the humble 
    &quot;NULL&quot; (U+0000) which were never intended for display. Rather than writing them to the screen, 
    Glyphviewer lists them instead.</li></ul>
    <h3 id="failure">On Failure</h3>
<p>Glyphviewer will display an error message when it fails. There are several reasons for failure.</p>
<ul><li>The <strong>URL</strong> cannot be resolved to some resource on the Internet.</li>
<li>The <strong>URL</strong> points to an actual <em>resource</em> on the Interwebs, but it's not a font file.</li> 
<li>The <strong>URL</strong> points to a font file, but it is too &quot;big&quot;. This limitation is deliberate. 
Imagine if some smartarse puts all 22MB of <a href="http://en.wikipedia.org/wiki/Arial_Unicode_MS">Arial Unicode MS</a>
on their web server, and directed Glyphviewer to analyse it. This would slow down this server. That's why the 
application refuses to read very large files.</li> 
<li>The font is genuine, but essential information such as the header is missing. (This shouldn't happen, as it's 
against the <a href="http://www.microsoft.com/typography/otspec/">specification</a>).</li>
<li>The font is a <em><a href="http://en.wikipedia.org/wiki/Symbol_%28typeface%29">symbol font</a></em>, a relic
from the days before Unicode. 
Glyphviewer will refuse to analyse it out of disgust.</li></ul>
<h3 id="warning">Cross Origin Resource Sharing</h3>
<p>There is one situation which will result in a <em>warning</em> (rather than an outright failure). It occurs when the user
attempts to analyse a font from a remote server whose 
<a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-origin Resource Sharing</a> (CORS) 
policy refuses resources to be served by third-party sites. Glyphviewer will be able to analyse the font's header for information
such as designer and copyright information. CORS doesn't prevent a resource being accessed by its lonesome. The problem
will be when Glyphviewer - located on a particular server - tries to display the characters in the font when accessing it from
a secondary, remote server. Many browsers - such as IE and Firefox - will refuse to display the characters using the font, and
thus use some "fallback" font for that browser. Since this may mislead users as to the appearance of the font, Glyphviewer
will warn them about this situation.</p>
<p>
Glyphviewer should not encounter this situation when handling remote fonts delivered from 
<a href="https://en.wikipedia.org/wiki/Content_delivery_network">Content Delivery Networks</a> (CDN) such as
<a href="http://www.google.com/webfonts">Google Fonts</a>. That's because these sites are designed to allow their resources
to be shared by other sites. There are several ways to do this, but the most common way is to serve them with these particular
HTTP headers:</p>
<pre>Access-Control-Allow-Origin: *</pre>
<p>If Glyphviewer detects these headers when downloading fonts from a remote server, it will assume that the browser can
display them in the browser, and no warning will be presented to the user. This is not an issue for Glyphviewer when handling
fonts hosted locally, because obviously the font and the server shares the same domain; CORS would not apply.</p>
<p>CORS - although a hindrance to Glyphviewer - is generally a good thing. It can be problematic if a "resource" such as a hostile
piece of JavaScript is injected into a page from a third party website. That's why some browsers (such as Firefox and IE) refuse to
load resources from third party websites unless certain criteria are met. For more information on CORS, please see the 
<a href="http://www.w3.org/TR/cors/">W3C  specification.</a>

    <h3 id="limitations">Limitations</h3>
    <p>Apart from issues arising from CORS, these are several limitations built in to Glyphviewer.</p>
    <ul><li>Glyphviewer can only analyse OpenType, TrueType and Web Open Font Format font files. Other font files such
    as Embedded OpenType (.eot) and Scalable Vector Graphics (.svg) cannot be handled by this application.     
    <li>The application has a font size limitation built in (as stated before).</li>
    <li>The application may be slow when analyzing a remote font, as the server has to access it to create a 
    temporary copy.</li></ul>
<p>Earlier versions had a serious limitation. The application could only show glyphs for characters from the 
    <a href="http://www.unicode.org/roadmaps/bmp/">Basic Multilingual Plane</a> (U+0000 to U+FFFF). Characters out
    of this range were not displayed. Fortunately, this limitation has been removed from Glyphviewer as of version 0.4 (2016).</p>

<h2 id="install">Installation and Dependencies</h2>
  <p><strong>Glyphviewer</strong> depends on the following software:</p>
  <ul><li><a href="http://www.python.org/">Python</a> 2.x</li>
  <li><a href="http://www.djangoproject.com/">Django</a> 1.x</li>
  <li>The <a href="https://github.com/behdad/fonttools">FontTools</a> package for parsing
  TrueType, OpenType, and (new) WOFF files.</li>
   <li><a href="http://sourceforge.net/projects/numpy/">Numerical Python (numpy)</a>, which FontTools 
   depends upon.</li></ul>
     <p><em><strong>Glyphviewer</strong> originally had a dependency on 
     <a href="https://github.com/typesupply/woffTools">WoffTools</a>, a package (built on top of FontTools) 
     for parsing WOFF files. However, FontTools has WOFF support, and WoffTools has not been worked on for several years,
     so this dependency has been removed.</em></p>
  <p>Once these libraries have been installed, the next stage is to install Glyphviewer via the following command:</p>
  <pre>pip install glyphviewer</pre>

<p>The next stage is to add "glyphviewer" to your INSTALLED_APPS list in settings.py, and add the
desired URL in one of the urls.py files.</p>
<p>The final stage is to populate the directory with fonts where you display your chosen font or fonts. The Glyphviewer
application comes with its own set of fonts adapted from the 
<a href="https://savannah.gnu.org/projects/freefont/">Free UCS Outline Fonts</a>; they have been converted to
WOFF form for quicker download. These can be moved into the correct directory via the following shell command:</p>
<pre>python manage.py collectstatic</pre>
<p>The font files wil then be moved into the {STATIC_ROOT}/glyphviewer/fonts/ directory, and the browser will read
the files from the {STATIC_URL}/glyphviewer/fonts/ folder.</p>
<p><em>Note: it is not mandatory to run the collectstatic command. However, if there are no font files in the above directory,
then Glyphviewer will only be able to read remote files.</em></p>
<p>The HTML template files in this application have been
redesigned to work with the <a href="http://mezzanine.jupo.org/">Mezzanine</a> CMS. The 
redesign removed any explicit references to particular stylesheets found with earlier versions.
The app (and the fonts) are released under a <a href="http://www.gnu.org/copyleft/gpl.html">GNU general public license</a>.
If you wish to do any changes,
pop over to the <a href="https://github.com/peterkmurphy/glyphviewer">GitHub repository</a> for the app.</p>
    
<h2>Why Glyphviewer?</h2>
    <p>I created Glyphviewer as a tool to examine the character repetoire of web fonts. It is easy to find
    fonts online; it is harder to find out exactly what characters they support. Almost all contain standard
    capital letters like &quot;A&quot;, &quot;B&quot; and &quot;C&quot;, and that's not hard to discover, 
    because those are among the first characters to be advertised by the foundries. It's harder to find out
    how much support a font has for more <em>unusual</em> characters like (say) &quot;ŋ&quot;. One could
    install a fonts on the computer, and inspect it in a tool like &quot;Character Map&quot;, but this is
    laborous and time-wasting.</p>
    <p>So I created a tool that could analyse a font if it was located somewhere on
    the World Wide Web. Font makers often display their fonts using web pages, and even provide a place
    where people can type text and see it displayed using the typeface. All one has to do to analyse it is examine the
    attached cascading stylesheet for a link to the font file, and place its URL in Glyphviewer.</p>  
<p>This application was designed in response to and <b>in reaction to</b> 
<a href="http://www.google.com/webfonts">Google Fonts</a>, which came out in 2011. The idea is wonderful: tens of web fonts available
for access and download. A laudatory effort - except that <i>it doesn't accurately show the full repertoire of 
characters for each font</i>. Take <a href="http://www.google.com/webfonts/family?family=Lato">Lato</a> - a 
lovely font, and comes in 10 variants too. Now look at the 
<a href="http://www.google.com/fonts/specimen/Lato#charset">character set Google
Web Fonts</a> displays for it. At the time, I was frustrated that "Ł" and "ł" were not displayed, even though the font
supports them, and even though the creator goes by the name of <a href="http://www.typoland.com/">Łukasz Dziedzic</a>. 
<em>Now</em> in 2016, Google Fonts displays them, but it took Google a couple of years to lift their game.</p> 
<h2>Acknowledgements</h2>
<p>The primary inspiration for this is 
<a href="http://en.wikipedia.org/wiki/Mark_Pilgrim_%28software_developer%29">Mark Pilgrim</a>, who wrote
a blog post called <a href="https://web.archive.org/web/20090422173924/http://diveintomark.org/archives/2009/04/21/fuck-the-foundries">Fuck 
the foundries</a> in 2009 (before yanking it off the net two years later). His
essay and/or rant got me interested in web fonts in the first place, as did his use of the utterly superb web font 
<a href="http://www.thibault.org/fonts/essays/">Essays 1743</a> in 
<a href="http://diveintohtml5.org/">Dive into HTML5</a>. 
Thanks to <a href="http://www.thibault.org/newhome/">John Stracke</a> for coming up with the &quot;Essays&quot; 
typeface in the first place.</p>
<p>I also have to acknowledge the developers of the libraries used in the making of Glyphviewer.
A special shout out goes to the folk at <a href="http://www.typesupply.com/">TypeSupply</a> who decided to 
<a href="http://code.typesupply.com/">open-source their code</a> for WoffTools. The project wouldn't have been possible without them.
I must also acknowledge the 
<a href="https://savannah.gnu.org/projects/freefont/">Free UCS Outline Fonts</a> project for providing
the fonts used in this application.</p> 
<h2>History</h2>
<ul>
<li>0.1 (June 11th 2011) - Initial release. </li>
<li>0.2 (June 28th 2013) - Added setup script to create a PyPI package. Removed bugs.</li>
<li>0.3 (February 15th 2014) - Made compatible with Mezzanine and Bootstrap, changed 
                               styles for errors, now handles empty local directories.</li>
<li>0.4 (January 16th 2016) - Now handles cases where remote fonts are inaccessible
using CORS; removed the limitation that restricted characters to the BMP; added
documentation for above.</li>
</ul>
    <h2 id="techappendix">Glossay</h2>
    <dl>
    <dt><dt>Font</dt><dd>A file, or a set of files, that is used to specify the appearance of computer text. 
    Common Windows
    fonts are &quot;Times New Roman&quot;, &quot;Arial&quot; and &quot;Courier New&quot;;
    Mac OS X and Linux have their own equivalents. The  
    "Times New Roman" font consists of 4 files: one for representing regular text, 
    <strong>one for Bold text</strong>, <em>one for Italic text</em> and 
    <strong><em>one for Bold Italic text</em></strong>.</dd>
    <dt>Web font</dt><dd>A font that is designed to be downloaded with a web page <em>only for the 
    purpose of viewing it</em>, and then discarded afterwards. Historically, most web designers assumed
    that users had a limited repertoire of fonts already installed on their machine, and would style
    accordingly. For example, it would be a safe bet to have either Helvetica or Arial on the viewer's
    computer, and if not, there would be some sort of <a href="https://en.wikipedia.org/wiki/Sans-serif">sans-serif</a>
    equivalent available instead.
    One problem with this is that it gets boring to see the same fonts
    all the time. So the W3C had a sit down with industry folk from Microsoft and Adobe and Mozilla and
    other companies, and worked out their own <a href="http://www.w3.org/TR/css3-fonts/">technology
    for embedding fonts</a> on the fly.</dd>
    <dt>Glyph</dt><dd>Glyphs are the shapes used to represent characters in a font. 
    For example, the character &quot;I&quot; is (more or less) shaped a horizontal line - in contrast to
    an &quot;o&quot; character, which resembles (roughly) a hollow circle. Terms like &quot;more or less&quot; and
    &quot;roughly&quot; are used here, because the same character would be generally represented by different
    glyphs in different fonts, and <em>even within them</em>. Continuing the example above, an 
    &quot;<em>I</em>&quot; in a italic version of a font would be inclined relative to a regular 
    version of &quot;I&quot;, while an &quot;I&quot; in a <a href="http://en.wikipedia.org/wiki/Serif">serif</a> font would have serifs coming out at the front
    and the bottom. In short, there are many ways to create a glyph for the same characters.</dd> 
    </dl>
 <p style="text-align: center;"><em>Copyright © <a href="/">Peter Murphy</a>
2011-2016.</em></p>   
{% endblock %}