1 files changed, 285 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/mk/mk-plain.tex b/doc/context/sources/general/manuals/mk/mk-plain.tex
new file mode 100644
index 000000000..67c5a3463
--- /dev/null
+++ b/doc/context/sources/general/manuals/mk/mk-plain.tex
@@ -0,0 +1,285 @@
+% language=uk
+
+\environment mk-environment
+
+\startcomponent mk-plain
+
+\chapter {Just plain}
+
+\subject{running}
+
+For testing basic \LUATEX\ functionality it makes sense to have a
+minimal system, and traditionally plain \TEX\ has been the most
+natural candidate. It is for this reason that it had been on the
+agenda for a while to provide basic \OPENTYPE\ font support for
+plain \TEX\ as well. Although the \MKIV\ node mode subsystem is
+not yet perfect, the time was right to start experimenting with a
+subset of the \MKIV\ code.
+
+Using plain roughly comes down to the following. First you need
+to generate a format:
+
+\starttyping
+luatex --ini --fmt=luatex.fmt luatex-plain.tex
+\stoptyping
+
+This format has to be moved to a place where it can be found by
+the \KPSE\ library. Since this can differ per distribution there
+is no clear recipe for it, but for \TEXLIVE\ some path ending in
+\type {web2c/luatex} is probably the right spot. After that you
+can run
+
+\starttyping
+luatex luatex-test.tex
+\stoptyping
+
+This file lives under \type {generic/context}. When it
+is run it is quite likely that you will get an error message
+because the font name database cannot be found. You
+can generate one with the following command (which assumes that
+you have \CONTEXT\ installed):
+
+\starttyping
+mtxrun --usekpse --script fonts --names
+\stoptyping
+
+The resulting file \type {luatex-fonts-names.lua} has to be placed
+somewhere in your \TEX\ tree so that it can be found anytime.
+Beware: the \type {--usekpse} flag is only used outside \CONTEXT\
+and provides very limited functionality, just enough for this
+task. Again this is a distribution specific issue so we will not
+dwell upon it here.
+
+The way fonts are defined is modelled after \XETEX, as it makes no
+sense to support the somewhat more fancy \CONTEXT\ way of doing
+things. Keep in mind that although \CONTEXT\ \MKIV\ does support
+the \XETEX\ syntax too, the preferred way there is to use a more
+symbolic feature definition approach.
+
+As this is an experimental setup, it might not always work out as
+expected. Around \LUATEX\ version 0.50 we expect the code to be
+more or less okay.
+
+\subject{implementation}
+
+The \type {luatex-fonts.lua} file is the first in a series of
+basic functionality enhancements for \LUATEX\ derived from the
+\CONTEXT\ \MKIV\ code base. Please don't pollute the \type
+{luatex-*} namespace with code not coming from the \CONTEXT\
+development team as we may add more files.
+
+This file implements a basic font system for a bare \LUATEX\
+system. By default \LUATEX\ only knows about the classic \TFM\
+fonts but it can read other font formats and pass them to \LUA.
+With some glue code one can then construct a suitable \TFM\
+representation that \LUATEX\ can work with. For more advanced font
+support a bit more code is needed that needs to be hooked
+into the callback mechanism.
+
+This file is currently rather simple: it just loads the \LUA\ file
+with the same name. An example of a \type {luatex.tex} file that is
+just the plain \TEX\ format:
+
+\starttyping
+\catcode`\{=1 % left brace is begin-group character
+\catcode`\}=2 % right brace is end-group character
+
+\input plain
+
+\everyjob\expandafter{\the\everyjob\input luatex-fonts\relax}
+
+\dump
+\stoptyping
+
+We could load the \LUA\ file in \type {\everyjob} but maybe some
+day we will need more here.
+
+When defining a font, in addition to the \XETEX\ way, you can use
+two prefixes. A \type {file:}\ prefix forces a file search, while
+a \type {name:}\ prefix will result in consulting the names
+database. The font definitions shown in figure~1 are all valid.
+
+\starttyping
+\font\testa=file:lmroman10-regular at 12pt
+\font\testb=file:lmroman12-regular:+liga; at 24pt
+\font\testc=file:lmroman12-regular:mode=node;+liga; at 24pt
+\font\testd=name:lmroman10bold at 12pt
+\font\testh=cmr10
+\font\testi=ptmr8t
+\font\teste=[lmroman12-regular]:+liga at 30pt
+\font\testf=[lmroman12-regular] at 40pt
+\font\testj=adobesongstd-light % cid font
+\font\testk=cambria(math) {\mathtest 123}
+\font\testl=file:IranNastaliq.ttf:mode=node;script=arab;\
+    language=dflt;+calt;+ccmp;+init;+isol;+medi;+fina;+liga;\
+    +rlig;+kern;+mark;+mkmk at 14pt
+\stoptyping
+
+You can load maths fonts but as Plain \TEX\ is set up for Computer
+Modern (and as we don't adapt Plain \TEX) loading Cambria does
+not give you support for its math features automatically.
+
+If you want access by name you need to generate a font
+database, using:
+
+\starttyping
+mtxrun --script font --names
+\stoptyping
+
+and put the resulting file in a spot where \LUATEX\ can find it.
+
+\subject {remarks}
+
+The code loaded in \type {luatex-fonts.lua} does not come out of
+thin air, but is mostly shared with \CONTEXT; however, in that
+macro package we go beyond what is provided in the plain variant.
+When using this code you need to keep a few things in mind:
+
+\startitemize
+
+\item This subsystem will be extended, improved etc.\ at about the
+same pace as \CONTEXT\ \MKIV. However, because \CONTEXT\ provides a
+rather high level of integration not all features will be supported
+in the same quality. Use \CONTEXT\ if you want more goodies.
+
+\item There is no official \API\ yet, which means that using
+functions implemented here is at your own risk, in the sense that
+names and namespaces might change. There will be a minimal \API\
+defined once \LUATEX\ version 1.0 is out. Instead of patching the
+files it's better to overload functions if needed.
+
+\item The modules are not stripped too much, which makes it
+possible to benefit from improvements in the code that take place
+in the perspective of \CONTEXT\ development. They might be split a
+bit more in due time so the baseline might become smaller.
+
+\item The code is maintained and tested by the \CONTEXT\
+development team. As such it might be better suited for this macro
+package and integration in other systems might demand some
+additional wrapping. The plain version discussed here is the
+benchmark and should be treated as a kind of black box.
+
+\item Problems can be reported to the team but as we use \CONTEXT\
+\MKIV\ as our baseline, you'd better check if the problem is a general
+\CONTEXT\ problem too.
+
+\item The more high level support for features that is provided in
+\CONTEXT\ is not part of the code loaded here as it makes no sense
+elsewhere. Some experimental features are not part of this code
+either but some might show up later.
+
+\item Math font support will be added but only in its basic form
+once the Latin Modern and \TEX\ Gyre math fonts are
+available. Currently traditional and \OPENTYPE\ math fonts can
+be loaded.
+
+\item At this moment the more nifty speedups are not enabled
+because they work in tandem with the alternative file handling
+that \CONTEXT\ uses. Maybe around \LUATEX\ 1.0 we will bring some
+speedup into this code too (if it pays off at all).
+
+\item The code defines a few global tables. If this code is used
+in a larger perspective then you can best make sure that no
+conflicts occur. The \CONTEXT\ package expects users to work in
+their own namespace (\type {userdata}, \type {thirddata}, \type
+{moduledata} or \type {document}). We give ourselves the freedom to
+use any table at the global level but will not use tables that are
+named after macro packages. Later, \CONTEXT\ might operate in
+a more controlled namespace but it has a low priority.
+
+\item There is some tracing code present but this is not enabled
+and not supported as it integrates quite tightly into \CONTEXT. In
+case of problems you can use \CONTEXT\ for tracking down problems.
+
+\item Patching the original code in distributions is dangerous as
+it might fix your problem but introduce new ones for \CONTEXT. So,
+best keep the original code as it is and overload functions and
+callbacks when needed. This is trivial in \LUA.
+
+\item Attributes are (automatically) taken from the range 127||255 so
+you'd best not use these yourself. Don't count on an attribute number
+staying the same and don't mess with these attributes.
+
+\stopitemize
+
+If this all sounds a bit strict, keep in mind that it makes no sense
+for us to maintain multiple code bases and we happen to use \CONTEXT.
+
+\subject{advanced features}
+
+The latest versions now also support font extending, slanting,
+protrusion and expansion. Here are a few examples:
+
+\starttyping
+\pdfprotrudechars2 \pdfadjustspacing2
+
+\font\testa=file:lmroman12-regular:+liga;extend=1.5         at 12pt
+\font\testb=file:lmroman12-regular:+liga;slant=0.8          at 12pt
+\font\testc=file:lmroman12-regular:+liga;protrusion=default at 12pt
+\font\testd=file:lmroman12-regular:+liga;expansion=default  at 12pt
+\stoptyping
+
+The extend and slant options are similar to those used in
+map files. The extend is limited to 10 and the slant to 1.
+
+In the protrusion and expansion specification the keyword \type
+{default} is an entry in a definition table. You can find an
+example at the end of \type {font-dum.lua}.
+
+A setup for expansion looks as follows:
+
+\starttyping
+fonts.expansions.setups['default'] = {
+    stretch = 2, shrink = 2, step = .5, factor = 1,
+
+    [byte('A')] = 0.5, [byte('B')] = 0.7,
+    ...........
+    [byte('8')] = 0.7, [byte('9')] = 0.7,
+}
+\stoptyping
+
+The stretch, shrink and steps become font properties
+and characters gets a value assigned. In pseudo code
+it looks like:
+
+\starttyping
+chr(A).expansion_factor = 0.5 * factor
+\stoptyping
+
+The protrusion table has left and right protrusion
+factors for each relevant character.
+
+\starttyping
+fonts.protrusions.setups['default'] = {
+    factor = 1, left = 1, right = 1,
+
+    [0x002C] = { 0, 1 }, -- comma
+    [0x002E] = { 0, 1 }, -- period
+    [0x003A] = { 0, 1 }, -- colon
+    ........
+    [0x061B] = { 0, 1 }, -- arabic semicolon
+    [0x06D4] = { 0, 1 }, -- arabic full stop
+}
+\stoptyping
+
+So, the comma will stick out in the right margin:
+
+\starttyping
+chr(comma).right_protruding = right * 1 * factor
+\stoptyping
+
+As we prefer measures relative to the width (precentages) we
+actualy use:
+
+\starttyping
+chr(comma).right_protruding = right * 1 * factor * (width/quad)
+\stoptyping
+
+You can add additional tables and access them by keyword in the
+font specification.
+
+The model used in the plain variant is a simplification of the
+\CONTEXT\ model so \CONTEXT\ users should not take this as
+starting point.
+
+\stopcomponent