summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex
blob: 4ae25a9c7ec02ae2a890cde1e79b9c4c1ff92a36 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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