summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/optex/optex-techdoc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/optex/optex-techdoc.tex')
-rw-r--r--Master/texmf-dist/doc/optex/optex-techdoc.tex290
1 files changed, 290 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/optex/optex-techdoc.tex b/Master/texmf-dist/doc/optex/optex-techdoc.tex
new file mode 100644
index 00000000000..4ae25a9c7ec
--- /dev/null
+++ b/Master/texmf-dist/doc/optex/optex-techdoc.tex
@@ -0,0 +1,290 @@
+%% 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]
+
+\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 the plain \TeX/.
+
+\verbinput (6-20) optex.ini
+%
+The \`\optexversion` and \`\fmtname` are defined.
+
+\verbinput (22-25) optex.ini
+%
+We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character
+is set as `\newlinechar`.
+
+\verbinput (27-36) 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 (38-42) optex.ini
+%
+Individual `*.opm` macro files are read.
+
+\verbinput (44-87) optex.ini
+%
+The file `optex.lua` is embedded into the format as byte-code.
+It is documented in section~\ref[lua].
+
+\verbinput (89-92) optex.ini
+
+The `\everyjob` register is initialized and the format is saved by
+the `\dump` command.
+
+\verbinput (94-102) optex.ini
+
+}
+
+\printdoctail prefixed.opm
+\secc The implementation of the namespaces
+\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
+\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 \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
+\printdoc fonts-resize.opm
+
+\printdoctail fonts-select.opm
+\secc 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 math-unicode.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] Implemetation 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
+\secc Hyphenations
+\printdoc hyphen-lan.opm
+\printdoctail hyphen-lan.opm
+\secc[langphrases] Multilingual phrases and quotation marks
+\printdoc languages.opm
+
+\sec 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.
+
+\newtoks \_hisyntaxlua
+\_hisyntaxlua={%
+ \_hicolor C \Green
+ \_replfromto {--}{^^J} {\z C{--#1}^^J}%
+}
+
+{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \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 Printing documentation
+\printdoctail doc.opm
+\printdoc doc.opm
+
+\enddocument
+