mirror of
https://github.com/ganelson/inform.git
synced 2024-07-07 17:44:22 +03:00
81 lines
4.4 KiB
OpenEdge ABL
81 lines
4.4 KiB
OpenEdge ABL
What This Module Does.
|
|
|
|
An overview of the html module's role and abilities.
|
|
|
|
@h Prerequisites.
|
|
The html module is a part of the Inform compiler toolset. It is
|
|
presented as a literate program or "web". Before diving in:
|
|
(a) It helps to have some experience of reading webs: see //inweb// for more.
|
|
(b) The module is written in C, in fact ANSI C99, but this is disguised by the
|
|
fact that it uses some extension syntaxes provided by the //inweb// literate
|
|
programming tool, making it a dialect of C called InC. See //inweb// for
|
|
full details, but essentially: it's C without predeclarations or header files,
|
|
and where functions have names like |Tags::add_by_name| rather than |add_by_name|.
|
|
(c) This module uses other modules drawn from the compiler (see //structure//), and also
|
|
uses a module of utility functions called //foundation//.
|
|
For more, see //foundation: A Brief Guide to Foundation//.
|
|
|
|
@h Purpose.
|
|
Many functions of the Inform toolset involve the generation of HTML in some
|
|
way, but almost all of that work is actually done by the //foundation// module.
|
|
If you're interested in how HTML pages are made, how tags are opened and closed,
|
|
and such, see //foundation: HTML// and //foundation: Epub Ebooks//. All of that
|
|
code is general-purpose.
|
|
|
|
By contrast, the //html// module is very much a part of the Inform compiler
|
|
and provides highly Inform-specific functions needed to make the intranet-like
|
|
miniature websites it generates on the fly -- problem pages, the Index, the
|
|
extensions documentation. In particular, it offers:
|
|
|
|
(a) clickable links to positions in source text, opening the Source panel
|
|
in the Inform GUI apps as needed -- see //SourceLinks::link//;
|
|
(b) paste buttons which, when clicked, insert text into the Source panel,
|
|
or which open certain files or folders -- see //Paste Buttons//;
|
|
|
|
@h Custom HTML link protocols.
|
|
This seems a useful place to document something which the Inform GUI apps
|
|
must provide. These render index, problem and extension mini-website pages
|
|
in embedded web browser views: for example, Inform on MacOS is essentially
|
|
running a copy of Safari (or rather, its underlying engine WebKit) under
|
|
the hood to display these. The material displayed consists of standard web
|
|
pages, except that there are two custom "transport protocols" or "URL schemas".
|
|
|
|
Protocols like this go under a number of names, partly because there are many
|
|
subtly different ideas here which only experts can distinguish (see
|
|
//https://en.wikipedia.org/wiki/Application_layer// for the entrance to the
|
|
rabbit-hole). To us, anyway, protocols are the prefixes of URLs which end
|
|
with a colon -- all browsers recognise a standard set of these, of which |http:|
|
|
|https:| and |file:| are by far the most commonly used.
|
|
|
|
Inform uses two non-standard ones in these internal pages, and so the GUI app
|
|
must implement them for its embedded web engine:
|
|
(a) |source:| is used in link |href|s to make source text references -- see //Source Links//;
|
|
(b) |inform:| is used both for links to internal or external pages generated
|
|
by Inform, and also for image |src|s. It behaves just like |http:|, except
|
|
that it derives the location of a file from the given URL in a different way.
|
|
|
|
@ The reason |inform:| is needed is that HTML files generated by Inform have
|
|
no way to know the relative URLs necessary to access e.g. icon images for
|
|
the World index, which will be in different places in the file system on
|
|
different Inform apps. More formally, the specification of |inform:| is that --
|
|
|
|
(a) |inform://...| is interpreted as a reference to one of the built-in images,
|
|
i.e., to wherever the app has internally stashed the Inform distribution's
|
|
directory |resources/Imagery|. Barring errors in Inform, or in the app, this
|
|
should never 404.
|
|
|
|
(b) For any path |*|, |inform://Extensions/*| should be fetched as |*| in the
|
|
external resources area -- that is, the place to which the app is installing
|
|
new extensions. If no file was found, the link should simply do nothing:
|
|
the application is required not to produce a 404 error page, or to
|
|
blank out the page currently showing.
|
|
|
|
@h Localisation.
|
|
This module also contains a very simple system for "localisation" of text,
|
|
that is, enabling the user to output text in multiple human languages. (Inform
|
|
makes heavy use of this in the Index.) This may not appear at first to have
|
|
anything to do with HTML, but in fact we will mainly use it when generating
|
|
web pages in the Index, so it has some conveniences for stylistic markup as well.
|
|
|
|
See //Localisation// for details.
|