Skip to content

Commit

Permalink
code doc updates
Browse files Browse the repository at this point in the history 
see #496
  • Loading branch information
@wspr
wspr committed May 12, 2024
1 parent aaa8cae commit 11e87bb
Show file tree
Hide file tree
Showing 5 changed files with 177 additions and 92 deletions.
73 changes: 54 additions & 19 deletions fontspec-code-msg.dtx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,49 @@
%
% \section{Error/warning/info messages}
%
% \begin{function}{\@@_msg_new:nn,\@@_msg_new:nnn}
% \begin{syntax}
% |\@@_msg_new:nn | \Arg{msg id} \Arg{message}
% |\@@_msg_new:nnn| \Arg{msg id} \Arg{message} \Arg{additional text}
% \end{syntax}
% These functions define messages using the standard \verb|\msg_new:nnn(n)| commands.
% Wrappers are used to pre-set the package name and to trim spaces, allowing form convenient
% definition later in this file.
%
% An additional linebreak is added to avoid awkward breaks when the filename is
% included in the error message.
% \end{function}
%
% \section{Implementation}
%
% \subsection{Messages for package options}
% \begin{macrocode}
%<*options>
\msg_new:nnn {fontspec} {cm-default-obsolete}
{
The~"cm-default"~package~option~is~obsolete.
}
\msg_new:nnn {fontspec} {enc-obsolete}
{
The~"#1"~package~option~is~obsolete.~TU~is~the~default~encoding.
}
\msg_new:nnn {fontspec} {math-opt-unknown}
{
The~ global~ option~ 'math=#1'~ is~ not~ recognised.~ It~ will~ be~ ignored.
}
%</options>
% \end{macrocode}
%
%
% \subsection{Messages for general package behaviour}
%
% \iffalse
% \begin{macrocode}
%<*fontspec>
% \end{macrocode}
% \fi
%
% Shorthands for messages:
% \paragraph{Shorthands for messages}
% \begin{macrocode}
\cs_new:Npn \@@_error:n { \msg_error:nn {fontspec} }
\cs_new:Npn \@@_error:nn { \msg_error:nnn {fontspec} }
Expand All @@ -23,14 +59,25 @@
\cs_new:Npn \@@_trace:n { \msg_trace:nn {fontspec} }
% \end{macrocode}
%
% Allow messages to be written with spaces acting as normal:
% \begin{macro}{\@@_msg_new:nn,\@@_msg_new:nnn}
% \begin{macrocode}
\cs_generate_variant:Nn \msg_new:nnn {nnx}
\cs_generate_variant:Nn \msg_new:nnnn {nnxx}
\cs_new:Nn \@@_msg_new:nn
{ \msg_new:nnx {fontspec} {#1} { ^^J \tl_trim_spaces:n {#2} } }
{
\msg_new:nnx {fontspec} {#1} { ^^J \tl_trim_spaces:n {#2} }
}
% \end{macrocode}
%
% \begin{macrocode}
\cs_new:Nn \@@_msg_new:nnn
{ \msg_new:nnxx {fontspec} {#1} { ^^J \tl_trim_spaces:n {#2} } { \tl_trim_spaces:n {#3} } }
{
\msg_new:nnxx {fontspec} {#1} { ^^J \tl_trim_spaces:n {#2} }
{ \tl_trim_spaces:n {#3} }
}
% \end{macrocode}
% \end{macro}
%
% Allow messages to be written with spaces acting as normal:
% \begin{macrocode}
\char_set_catcode_space:n {32}
% \end{macrocode}
%
Expand Down Expand Up @@ -190,20 +237,8 @@
Use "Ligatures=TeX" instead of "Mapping=tex-text".
}
% \end{macrocode}
% message for package options must be loaded earlier
%
% \begin{macrocode}
%</fontspec>
%<*options>
\msg_new:nnn {fontspec} {cm-default-obsolete}
{
The~"cm-default"~package~option~is~obsolete.
}
\msg_new:nnn {fontspec} {enc-obsolete}
{
The~"#1"~package~option~is~obsolete.~TU~is~the~default~encoding.
}
%</options>
%<*fontspec>
\@@_msg_new:nn {font-index-needs-ttc}
{
The "FontIndex" feature is only supported by TTC (TrueType Collection) fonts.\\
Expand Down
59 changes: 49 additions & 10 deletions fontspec-code-opening.dtx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,44 @@
%
% \section{Opening code}
%
% \begin{function}{\FontspecSetCheckBoolTrue,\FontspecSetCheckBoolFalse}
% Allows easy return of boolean results (\verb|\l_@@_check_bool|) without requiring specific catcode regimes.
% Used within Lua functions.
% \end{function}
%
% \begin{function}{\@@_keys_set_known:nnN,\@@_keys_set_known:nxN}
% Wrapper around standard \verb|\keys_set_known:nnN| which permits debugging.
% \end{function}
%
% \begin{function}{\@@_int_mult_truncate:Nn}
% \begin{syntax}
% |\@@_int_mult_truncate:nn| \meta{int} \Arg{scale}
% \end{syntax}
% Scales \meta{integer variable} by \meta{scale}, discarding any fractional components.
% E.g.,
% \begin{Verbatim}
% \int_new:N \foo
% \int_set:Nn \foo {3}
% \__fontspec_int_mult_truncate:Nn \foo {3.3}
% \int_show:N \foo % \foo = 9
%
% \int_set:Nn \foo {3}
% \__fontspec_int_mult_truncate:Nn \foo {3.4}
% \int_show:N \foo % \foo = 10
% \end{Verbatim}
% \end{function}
%
% \begin{function}{\@@_lua_function:ne,\@@_lua_function:nee,\@@_lua_function:neee,\@@_lua_function:neeee}
% \begin{syntax}
% |\@@_lua_function:ne| \Arg{method} \Arg{arg.~1}
% \end{syntax}
% Wrapper around \verb|\lua_now:e|, hard-coded to refer to a method of the \verb|fontspec| module.
% \verb|\@@_lua_function:ne {foo} {bar}| executes \verb|fontspec.foo("bar")| in the Lua engine.
% Variants for up to four arguments are provided.
% \end{function}
%
% \section{Implementation}
%
% \iffalse
% \begin{macrocode}
%<*options>
Expand All @@ -13,23 +51,25 @@
% \begin{macrocode}
\DeclareKeys
{
cm-default .code:n = { \msg_warning:nn {fontspec} {cm-default-obsolete} }
% \end{macrocode}
%
% \begin{macrocode}
,math .bool_gset:N = \g_@@_math_bool
,math .usage:n = preamble
,math / unknown .code:n = { } % \msg_warning:nnn {fontspec} {math-opt-unknown} {#1}
,no-math .bool_gset_inverse:N = \g_@@_math_bool
,no-math .usage:n = preamble
% \end{macrocode}
% \begin{macrocode}
,config .bool_gset:N = \g_@@_cfg_bool
,config .usage:n = load
,no-config .bool_gset_inverse:N = \g_@@_cfg_bool
,no-config .usage:n = load
,euenc .code:n = { \msg_warning:nnn {fontspec} {enc-obsolete}{euenc} }
,tuenc .code:n = { \msg_warning:nnn {fontspec} {enc-obsolete}{tuenc} }
% \end{macrocode}
%
% \begin{macrocode}
,cm-default .code:n = { \msg_warning:nn {fontspec} {cm-default-obsolete} }
,euenc .code:n = { \msg_warning:nnn {fontspec} {enc-obsolete}{euenc} }
,tuenc .code:n = { \msg_warning:nnn {fontspec} {enc-obsolete}{tuenc} }
% \end{macrocode}
% \begin{macrocode}
,quiet .code:n =
{
Expand All @@ -47,11 +87,6 @@
\msg_redirect_module:nnn { fontspec } { info } { info }
}
}
\msg_new:nnn {fontspec} {math-opt-unknown}
{
The~ global~ option~ 'math=#1'~ is~ not~ recognised.~ It~ will~ be~ ignored.
}

% \end{macrocode}
%
% \begin{macrocode}
Expand Down Expand Up @@ -169,6 +204,10 @@
\cs_generate_variant:Nn \tl_if_eq:nnT {oe}
% \end{macrocode}
%
% \begin{macrocode}
\cs_generate_variant:Nn \msg_new:nnn {nnx}
\cs_generate_variant:Nn \msg_new:nnnn {nnxx}
% \end{macrocode}
%
%
%
Expand Down
65 changes: 38 additions & 27 deletions fontspec-code-vars.dtx
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,60 @@
%%^^A%% fontspec-code-vars.dtx -- part of FONTSPEC <latex3.github.io/fontspec>
%
% \section{Declaration of variables}
% \section{Variables}
%
% \begin{variable}{\l_@@_firsttime_bool}
% As \cs{keys_set:nn} is run multiple times, some of its
% information storing only occurs once while we decide if the font family
% has been defined or not. When the later processing is occuring per-shape
% this no longer needs to happen; this is indicated by the `firsttime'
% conditional.
% \end{variable}
%
% \begin{variable}{\l_@@_never_check_bool}
% Used to disable checking opentype script, language, and tags
% when running checking code that has a user-defined return path we want to allow the higher-level
% code to dictate the logic.
% TODO: tidy this up!
% \end{variable}
%
% \section{Implementation}
%
% \iffalse
% \begin{macrocode}
%<@@=fontspec>
%<*fontspec>
% \end{macrocode}
% \fi
%
% This file consists solely of declaration of variables used by \pkg{fontspec}.
% In some cases these variables are also initialised with default values.
% In time I would like to move these initialisations
%
% \paragraph{Booleans}
% \paragraph{Booleans for package options}
%
% For package options:
% \begin{macrocode}
%<*options>
\bool_new:N \g_@@_cfg_bool
\bool_new:N \g_@@_math_bool
%</options>
%<*fontspec>
% \end{macrocode}
%
% \paragraph{Booleans for flow control}
%
% \begin{macro}{\l_@@_firsttime_bool}
% As \cs{keys_set:nn} is run multiple times, some of its
% information storing only occurs once while we decide if the font family
% has been defined or not. When the later processing is occuring per-shape
% this no longer needs to happen; this is indicated by the `firsttime'
% conditional.
% \begin{macrocode}
\bool_new:N \l_@@_firsttime_bool
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_@@_never_check_bool}
% \begin{macrocode}
\bool_new:N \l_@@_never_check_bool
% \end{macrocode}
% \end{macro}
%
% \paragraph{Booleans for processing logic}
%
% \begin{macrocode}
\bool_new:N \l_@@_nobf_bool
\bool_new:N \l_@@_noit_bool
Expand All @@ -49,15 +78,6 @@
\bool_new:N \g_@@_math_lucida_bool
\bool_new:N \g_@@_pkg_euler_loaded_bool
% \end{macrocode}
% For package options:
% \begin{macrocode}
%</fontspec>
%<*options>
\bool_new:N \g_@@_cfg_bool
\bool_new:N \g_@@_math_bool
%</options>
%<*fontspec>
% \end{macrocode}
%
% \begin{macrocode}
\bool_new:N \l_@@_tmpa_bool
Expand All @@ -70,15 +90,6 @@
\bool_new:N \l_@@_external_kpse_bool
% \end{macrocode}
%
% \begin{macro}{\l_@@_never_check_bool}
% It is used to disable checking opentype script, language, and tags
% when running checking code that has a user-defined return path we want to allow the higher-level
% code to dictate the logic.
% TODO: tidy this up!
% \begin{macrocode}
\bool_new:N \l_@@_never_check_bool
% \end{macrocode}
% \end{macro}
%
% \paragraph{Counters}
% \begin{macrocode}
Expand Down
Loading

0 comments on commit 11e87bb

Please sign in to comment.