duktape/website/README.txt

===============
Duktape website
===============

Overview
========

This directory contains all that is necessary to build the Duktape website
(http://www.duktape.org/).

The website has been implemented as a set of static files, to allow the site
to be cached and viewed off-line.  The pages do depend on external resources,
especially Google Fonts and Web Font Loader.  However, the pages are designed
to gracefully degrade:

* No network connection: pages must be readable with at least fallback fonts

* No CSS: pages must be readable with reasonable styling (default HTML styling)

* No Javascript: pages must be readable

The pages are also designed to be reasonably readable with a text browser
like w3m or elinks.

Build process
=============

A custom templating model is used to generate the HTML files, see
``buildsite.py``.  The general process is:

* An initial HTML source document is generated from HTML snippets and with
  Python functions.  For instance, API function descriptions are in the
  ``api/`` directory and they have a specific syntax that the Python functions
  can parse.  The Python code also creates the HTML source for representing
  value stack states.

* The resulting HTML document is parsed with BeautifulSoup into a parse tree.

* Transformation passes are applied to the parse tree.  For instance, C and
  Ecmascript code is colorized with ``source-highlight``.

* Finally, the parse tree is converted into an ASCII HTML document with
  BeautifulSoup.

API documentation
=================

API documentation is essential for developers, so special emphasis has been
placed on making it as useful as possible.  In particular:

* Official function-by-function API documentation is available from
  a standard place.

* API documentation can be easily searched and browsed.  Searching for
  functions is possible with browser page search.

* API documentation can be easily linked to.  In particular, it is possible
  to link to individual concepts or functions.

* API documentation can be read online, or downloaded for offline use.

The API documentation is compiled into a single HTML file, but is edited as
a set of individual source files in this directory.

Web font loading
================

Google Web Fonts are used for the CSS fonts:

* https://developers.google.com/fonts/docs/getting_started

To avoid long load delays, web fonts are loaded asynchronously instead of
using the simple "CSS include" mechanism.  Web Font Loader is used for
the asynchronous loading:

* https://github.com/typekit/webfontloader/blob/master/README.md

Because we want to avoid both (1) showing unstyled text ("FOUT") and
(2) waiting indefinitely for fonts load (very annoying with no network
ocnnection), we use a trick by Kevin Dew.  A custom ``wf-fail`` class
is added to the HTML element if font loading doesn't complete in a
reasonable time; CSS can then use this class to display the page.  This
avoids FOUT in most cases and is still reasonably responsive when font
loading fails very slowly.  See:

* http://kevindew.me/post/47052453532/a-fallback-for-when-google-web-font-loader-fails

Finally, to allow clients without Javascript to render the page, the
HTML element initially has a custom ``wf-nojavascript`` class which is
immediately removed by Javascript code.  If Javascript is disabled, the
class remains, and text can be shown based on this custom class.
Unfortunately this means that clients without Javascript support will
only see fallback fonts.

Minimizing HTML file size and transfer size
===========================================

Since large single-file documents are used, it is important to minimize
file size and file transfer size.  Some notes on that below.

Code snippets
-------------

Colorized code snippets are generated with source-highlight, which produces
very verbose output.  Using the external CSS option for source-highlight
makes the output more easily stylable and also reduces output size.

HTTP compression
----------------

Repetitive HTML code compresses to about 10-15% of uncompressed size, so
HTTP compression should definitely be used.  HTTP compression is supported
by practically all servers and browsers:

* http://www.http-compression.com/

Data URI images
---------------

Very small, non-repeated CSS images can be embedded with data URIs to
minimize load time.  Currently done manually, see ``buildimages.py``.

Misc issues
===========

Table overflows
---------------

Narrow layouts need table overflow handling.  The best solution would be to
CSS style the table elemen itself, but that doesn't seem to work cleanly in
all browsers.  For now, use::

  <div class="table-wrap">
  <table>...</table>
  </div>

Credits
=======

GNU source-highlight:

* http://www.gnu.org/software/src-highlite/

Google fonts:

* http://www.google.com/fonts

Web Font Loader:

* https://github.com/typekit/webfontloader

Kevin Dew's FOUT trick:

* http://kevindew.me/post/47052453532/a-fallback-for-when-google-web-font-loader-fails

CSS reset:

* http://www.cssreset.com/

Future work
===========

Inline elements for source-highlight output
-------------------------------------------

Transform source-highlight output to change most common span elements
into standard inline elements and apply styling to them based on a
wrapper div class (e.g. ``.c-code i { ... }``).  This should reduce size
of highlighted source code considerably, with a small impact on text
browser readability.

Inline elements for value stacks
--------------------------------

Value stack HTML code size can be minimized by using standard inline
elements with minimal explicit classing.

The downside of this approach is that text browsing is impacted.  The
inline elements should be chosen to be reasonable (even meaningful) for
text browsing.

HTML inline elements:

* https://developer.mozilla.org/en-US/docs/HTML/Inline_elements

Best candidates are probably:

* b
* i
* tt
* em