%% This is part of the OpTeX project, see http://petr.olsak.net/optex

% This file is read from optex-doc.tex
% Use: optex optex-doc
% (three times) to create whole documentation including all references and the index.

\load [doc.opm]
\input primitives

\thisoutline {TECHNICAL DOCUMENTATION}

\chap Technical documentation

This documentation is written in the source files `*.opm` between
the `\_doc` and `\_cod` pairs or after the `\_endcode` command.
When the format is generated by
\begtt
luatex -ini optex.ini
\endtt
then the text of the documentation is ignored and the format `optex.fmt` is
generated. On the other hand, if you run
\begtt
optex optex-doc.tex
\endtt
then the same `*.opm` files are read when the second chapter of this
documentation is printed.

A knowledge about \TeX/ is expected from the reader.
You can see a short document
\ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]{\TeX/ in a Nutshell}
or more detail
\ulink[https://eijkhout.net/texbytopic/texbytopic.html]{\TeX/ by topic}.

Notices about hyperlinks.
If a control sequence is printed in red color in this documentation then
this denotes its \"main documentation point". Typically, the listing where
the control sequence is declared follows immediately. If a control sequence is
printed in the blue color in the listing or in the text
then it is an active link that points (usually) to the main documentation point.
The main documentation point can be an active link that points to a previous
text where the control sequence was
mentioned. Such occurrences are active links to the main documentation point.

\sec[init] The main initialization file

The `optex.ini` file is read as the main file when the format is generated.

{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip}
 \def\docfile{optex.ini}

\verbinput (-4) optex.ini
%
Category codes are set first. Note that the `_` is set to category code
\"letter", it can be used as a part of control sequence names.
Other category codes are set as in plain \TeX/.

\verbinput (6-20) optex.ini
%
The \`\optexversion` and \`\fmtname` are defined.

\verbinput (22-26) optex.ini
%
We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character
is set as `\newlinechar`.

\verbinput (28-37) optex.ini
%
The basic macros for macro file syntax is defined, i.\,e.\
`\_endcode`, `\_doc` and `\_cod`.
The `\_codedecl` will be re-defined later.

\verbinput (39-43) optex.ini
%
Individual `*.opm` macro files are read.

\verbinput (45-89) optex.ini
%
The file `optex.lua` is embedded into the format as byte-code.
It is documented in section~\ref[lua].

\verbinput (91-94) optex.ini

The `\everyjob` register is initialized and the format is saved by
the `\dump` command.

\verbinput (96-104) optex.ini

}

\printdoctail prefixed.opm
\secc The implementation of the namespaces and macros for macro-files
\printdoc prefixed.opm

\sec pdf\TeX/ initialization
\printdoctail luatex-ini.opm
\printdoc     luatex-ini.opm

\sec Basic macros
We define first bundle of basic macros.
\printdoc basic-macros.opm

\sec Allocators for \TeX/ registers
\printdoctail alloc.opm
\printdoc     alloc.opm

\sec If-macros, loops, is-macros, cases
\printdoc if-macros.opm

\sec Setting parameters
\printdoctail parameters.opm
\printdoc     parameters.opm

\sec More \OpTeX/ macros
The second bundle of \OpTeX/ macros is here.
\printdoc more-macros.opm

\sec Using key=value format in parameters
\printdoctail keyval.opm
\printdoc     keyval.opm

\sec[plain] Plain \TeX/ macros
All macros from plain \TeX/ are rewritten here.
Differences are mentioned in the documentation below.
\printdoc plain-macros.opm

\sec Preloaded fonts for text mode
\printdoctail fonts-preload.opm
\printdoc     fonts-preload.opm

\printdoctail fonts-resize.opm
\secc[fresize] Implementation of resizing
Only \"resizing" macros and \^`\initunifonts` are implemented here.
Other aspects of Font Selection System and their implementation are described in
section~\ref[fselect].
\printdoc     fonts-resize.opm

\printdoctail fonts-select.opm
\secc[fselect] Implementation of the Font Selection System
\printdoc     fonts-select.opm

\sec [math-preload] Preloaded fonts for math mode
\printdoctail math-preload.opm
\printdoc     math-preload.opm

\sec[math-macros] Math macros
\printdoc math-macros.opm

\sec Unicode-math fonts
\printdoctail unimath-macros.opm

\sec[opmac-fonts] Scaling fonts in document (high-level macros)
These macros are documented in section~\ref[sizes] from the user point of view.
\printdoc fonts-opmac.opm

\sec[output] Output routine
\printdoctail output.opm
\printdoc     output.opm

\sec Margins
The `\margins` macro is documented in the section~\ref[marg].
\printdoc margins.opm

\sec[colors] Colors
\printdoctail colors.opm
\printdoc     colors.opm

\sec[ref-file] The \code{.ref} file
\printdoctail ref-file.opm
\printdoc     ref-file.opm

\sec[references] References
\printdoctail references.opm
\printdoc     references.opm

\sec Hyperlinks
\printdoctail hyperlinks.opm
\printdoc     hyperlinks.opm

\sec[maketoc] Making table of contents
\printdoc     maketoc.opm

\sec PDF outlines
\secc Nesting PDF outlines
\printdoctail outlines.opm
\printdoc     outlines.opm
\secc Strings in PDF outlines
\printdoctail pdfuni-string.opm
\printdoc     pdfuni-string.opm

\sec[sections] Chapters, sections, subsections
\printdoc sections.opm

\sec[lists] Lists, items
\printdoc lists.opm

\sec Verbatim, listings
\secc[verb] Inline and \"display" verbatim
\printdoc verbatim.opm
\secc[hisyntax] Listings with syntax highlighting
\printdoctail hi-syntax.opm
\printdoc     hi-syntax.opm

\sec Graphics
\printdoctail graphics.opm
\printdoc     graphics.opm

\sec[table] The \code{\\table} macro, tables and rules
\printdoctail table.opm
\secc[table.impl] Implementation of the \code{\\table} macro and friends
\printdoc     table.opm

\sec Balanced multi-columns
\printdoc multicolumns.opm

\sec Citations, bibliography
\secc[bib] Macros for citations and bibliography preloaded in the format
\printdoc cite-bib.opm
\secc[usebib] The \code{\\usebib} command
\printdoctail usebib.opm
\secc The \code{usebib.opm} macro file loaded when \code{\\usebib} is used
\printdoc     usebib.opm

\secc[isobib] Usage of the \code{bib-iso690} style
{\everyintt={\catcode`\<=13 \visiblesp}
\printdoctail bib-iso690.opm }

\secc Implementation of the \code{bib-iso690} style
\printdoc     bib-iso690.opm

\sec[makeindex] Sorting and making Index
\printdoc makeindex.opm

\sec[fnotes] Footnotes and marginal notes
\printdoc fnotes.opm

\sec Styles
   \OpTeX/ provides three styles: `\report`, `\letter` and `\slides`.
   Their behavior is documented in user part of the manual in the section
   \ref[styles] and `\slides` style (for presentations) is documented in
   `op-slides.pdf` which is an example of the presentation.
\secc \code{\\report} and \code{\\letter} styles
\printdoc styles.opm
\secc[slides] \code{\\slides} style for presentations
\printdoc slides.opm

\sec Logos
\printdoc logos.opm

\sec Multilingual support
\secc Lowercase, uppercase codes
\printdoctail uni-lcuc.opm
%\printdoc     hyphen-lan.opm
%\printdoctail hyphen-lan.opm
\secc[langphrases] Multilingual phrases and quotation marks
\printdoc languages.opm
\secc[langdecl] Languages declaration
\printdoc lang-decl.opm

\sec[others] Other macros
Miscellaneous macros are here.
\printdoc others.opm

\sec[lua] Lua code embedded to the format

The file `optex.lua` is loaded into the format in `optex.ini` as byte-code
and initialized by `\everyjob`, see section~\ref[init].

The file implements part of the functionality from `luatexbase` namespace,
nowadays defined by \LaTeX/ kernel. `luatexbase` deals with modules,
allocators, and callback management. Callback management is a nice extension
and is actually used in \OpTeX/. Other functions are defined more or less just
to suit luaotfload's use.

The allocations are declared in subsection~\ref[lua-alloc], callbacks are
implemented in subsection~\ref[callbacks] and handling with colors can be
found in the subsection~\ref[lua-colors].

{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \_hfuzz=1em \medskip}
  \commentchars-- \def\docfile{optex.lua} \ttline=-1
  \_def\_printcomments{\_medskip
     {\_catcodetable0 \_typosize[10/12]\_everypar={}\_scantextokens\_ea{\_vcomments}\par}%
     \_bigskip
   }

\verbinput \hisyntax{lua} (4-) optex.lua
}


\sec[doc] Printing documentation
\printdoctail doc.opm
\printdoc     doc.opm

\enddocument