summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilipp Gesang <phg42.2a@gmail.com>2013-07-28 14:13:34 +0200
committerPhilipp Gesang <phg42.2a@gmail.com>2013-07-28 14:13:34 +0200
commit23686faaa0861213d61ec22400bb603684324e5e (patch)
tree7689a8c24ddc073466ad2e2d8430cbf0e5e7fda7
parenta10bc5d5ed9ab1c11c951ad1edd90967e93f6ad3 (diff)
downloadluaotfload-23686faaa0861213d61ec22400bb603684324e5e.tar.gz
[doc] expand troubleshooting section
-rw-r--r--luaotfload.dtx110
1 files changed, 90 insertions, 20 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx
index 3892bd8..e42c14e 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -40,7 +40,7 @@
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
-\Msg{* Package: luaotfload v2.3b OpenType layout system}
+\Msg{* Package: luaotfload v2.4 OpenType layout system}
\Msg{************************************************************************}
\keepsilent
@@ -111,7 +111,7 @@ and the derived files
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{luaotfload.drv}%
- [2013/07/23 v2.3b OpenType layout system]%
+ [2013/07/28 v2.4 OpenType layout system]%
\documentclass{ltxdoc}
\usepackage{metalogo,multicol,mdwlist,fancyvrb,xspace}
\usepackage[x11names]{xcolor}
@@ -231,7 +231,7 @@ and the derived files
% \GetFileInfo{luaotfload.drv}
%
% \title{The \identifier{luaotfload} package}
-% \date{2013/07/23 v2.3b}
+% \date{2013/07/28 v2.4}
% \author{Elie Roux · Khaled Hosny · Philipp Gesang\\
% Home: \url{https://github.com/lualatex/luaotfload}\\
% Support: \email{lualatex-dev@tug.org}}
@@ -1005,6 +1005,14 @@ and the derived files
% In \TEX Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
% }
%
+% For a much more detailed report about a given font try the \verb|-I| option
+% instead (\verb|--inspect|).
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -I --find="Iwona Light Italic"
+% \end{verbatim}
+% \end{quote}
+%
% \verb|luaotfload-tool --help| will list the available command line
% switches, including some not discussed in detail here.
% For a full documentation of \identifier{luaotfload-tool} and its
@@ -1383,6 +1391,7 @@ and the derived files
%
% \section{Troubleshooting}
%
+% \subsection {Database Generation}
% If you encounter problems with some fonts, please first update to the latest
% version of this package before reporting a bug, as
% \identifier{luaotfload} is under active development and still a
@@ -1392,18 +1401,42 @@ and the derived files
% tracker for submitting bug reports, feature requests and the likes
% requests and the likes.
%
-% Errors during database generation can be traced by increasing
-% verbosity levels and redirecting log output to \fileent{stdout}:
+% Bug reports are more likely to be addressed if they contain the output of
%
-% \begin{verbatim}
-% luaotfload-tool -fuvvv --log=stdout
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool --diagnose=environment,files,permissions
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent Consult the man page for a description of these options.
+%
+% Errors during database generation can be traced by increasing the
+% verbosity level and redirecting log output to \fileent{stdout}:
%
-% If this fails, the font last printed to the terminal is likely to be
-% the culprit.
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -fuvvv --log=stdout
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent or to a file in \fileent{/tmp}:
+%
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -fuvvv --log=file
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent In the latter case, invoke the \verb|tail(1)| utility on the file
+% for live monitoring of the progress.
+%
+% If database generation fails, the font last printed to the terminal or log
+% file is likely to be the culprit.
% Please specify it when reporting a bug, and blacklist it for the time
% being (see above, page \pageref{font-blacklist}).
%
+% \subsection {Font Features}
% A common problem is the lack of features for some
% \OpenType fonts even when specified.
% This can be related to the fact that some fonts do not provide
@@ -1414,10 +1447,22 @@ and the derived files
% fix it.
% For example with \verb|latn|:
%
-% \begin{verbatim}
-% \font\test=file:MyFont.otf:script=latn;+liga;
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% \font\test=file:MyFont.otf:script=latn;+liga;
+% \end{verbatim}
+% \end{quote}
+%
+% You can get a list of features that a font defines for scripts and languages
+% by querying it in \fileent{luaotfload-tool}:
%
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool --find="Iwona" --inspect
+% \end{verbatim}
+% \end{quote}
+%
+% \subsection {\LUATEX Programming}
% Another strategy that helps avoiding problems is to not access raw \LUATEX
% internals directly.
% Some of them, even though they are dangerous to access, have not been
@@ -1426,14 +1471,39 @@ and the derived files
% \luafunction{aux} namespace over direct manipulation of font objects.
% For example, raw access to the \luafunction{font.fonts} table like:
%
-% \begin{verbatim}
-% local somefont = font.fonts[2]
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% local somefont = font.fonts[2]
+% \end{verbatim}
+% \end{quote}
%
-% can render already defined fonts unusable.
+% \noindent can render already defined fonts unusable.
% Instead, the function \luafunction{font.getfont()} should be used because
% it has been replaced by a safe variant.
%
+% However, \luafunction{font.getfont()} only covers fonts handled by the font
+% loader, e.~g. \identifier{OpenType} and \identifier{TrueType} fonts, but
+% not \abbrev{tfm} or \abbrev{ofm}.
+% Should you absolutely require access to all fonts known to \LUATEX, including
+% the virtual and autogenerated ones, then you need to query both
+% \luafunction{font.getfont()} and \luafunction{font.fonts}.
+% In this case, best define you own accessor:
+%
+% \begin{quote}
+% \begin{verbatim}
+% local unsafe_getfont = function (id)
+% local tfmdata = font.getfont (id)
+% if not tfmdata then
+% tfmdata = font.fonts[id]
+% end
+% return tfmdata
+% end
+%
+% --- use like getfont()
+% local somefont = unsafe_getfont (2)
+% \end{verbatim}
+% \end{quote}
+%
% \part{Implementation}
%
% \section{\fileent{luaotfload.lua}}
@@ -1478,8 +1548,8 @@ config.luaotfload.index_file = config.luaotfload.index_file or "luaot
luaotfload.module = {
name = "luaotfload",
- version = 2.3002,
- date = "2013/07/23",
+ version = 2.40001,
+ date = "2013/07/28",
description = "OpenType layout system.",
author = "Elie Roux & Hans Hagen",
copyright = "Elie Roux",
@@ -2070,7 +2140,7 @@ luaotfload.aux.start_rewrite_fontname () --- to be migrated to fontspec
\else
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{luaotfload}%
- [2013/07/23 v2.3b OpenType layout system]
+ [2013/07/28 v2.4 OpenType layout system]
\RequirePackage{luatexbase}
\fi
\ifnum\luatexversion<76