Debian Codegraph @

texmf-dist/doc/optex/base/optex-techdoc.tex

raw
1 %% This is part of the OpTeX project, see http://petr.olsak.net/optex
2
3 % This file is read from optex-doc.tex
4 % Use: optex optex-doc
5 % (three times) to create whole documentation including all references and the index.
6
7 \load [doc.opm]
8 \input primitives
9
10 \thisoutline {TECHNICAL DOCUMENTATION}
11
12 \chap Technical documentation
13
14 This documentation is written in the source files `*.opm` between
15 the `\_doc` and `\_cod` pairs or after the `\_endcode` command.
16 When the format is generated by
17 \begtt
18 luatex -ini optex.ini
19 \endtt
20 then the text of the documentation is ignored and the format `optex.fmt` is
21 generated. On the other hand, if you run
22 \begtt
23 optex optex-doc.tex
24 \endtt
25 then the same `*.opm` files are read when the second chapter of this
26 documentation is printed.
27
28 A knowledge about \TeX/ is expected from the reader.
29 You can see a short document
30 \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]{\TeX/ in a Nutshell}
31 or more detail
32 \ulink[https://eijkhout.net/texbytopic/texbytopic.html]{\TeX/ by topic}.
33
34 Notices about hyperlinks.
35 If a control sequence is printed in red color in this documentation then
36 this denotes its \"main documentation point". Typically, the listing where
37 the control sequence is declared follows immediately. If a control sequence is
38 printed in the blue color in the listing or in the text
39 then it is an active link that points (usually) to the main documentation point.
40 The main documentation point can be an active link that points to a previous
41 text where the control sequence was
42 mentioned. Such occurrences are active links to the main documentation point.
43
44 \sec[init] The main initialization file
45
46 The `optex.ini` file is read as the main file when the format is generated.
47
48 {\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip}
49 \def\docfile{optex.ini}
50
51 \verbinput (-4) optex.ini
52 %
53 Category codes are set first. Note that the `_` is set to category code
54 \"letter", it can be used as a part of control sequence names.
55 Other category codes are set as in plain \TeX/.
56
57 \verbinput (6-20) optex.ini
58 %
59 The \`\optexversion` and \`\fmtname` are defined.
60
61 \verbinput (22-26) optex.ini
62 %
63 We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character
64 is set as `\newlinechar`.
65
66 \verbinput (28-37) optex.ini
67 %
68 The basic macros for macro file syntax is defined, i.\,e.\
69 `\_endcode`, `\_doc` and `\_cod`.
70 The `\_codedecl` will be re-defined later.
71
72 \verbinput (39-43) optex.ini
73 %
74 Individual `*.opm` macro files are read.
75
76 \verbinput (45-89) optex.ini
77 %
78 The file `optex.lua` is embedded into the format as byte-code.
79 It is documented in section~\ref[lua].
80
81 \verbinput (91-94) optex.ini
82
83 The `\everyjob` register is initialized and the format is saved by
84 the `\dump` command.
85
86 \verbinput (96-104) optex.ini
87
88 }
89
90 \printdoctail prefixed.opm
91 \secc The implementation of the namespaces and macros for macro-files
92 \printdoc prefixed.opm
93
94 \sec pdf\TeX/ initialization
95 \printdoctail luatex-ini.opm
96 \printdoc luatex-ini.opm
97
98 \sec Basic macros
99 We define first bundle of basic macros.
100 \printdoc basic-macros.opm
101
102 \sec Allocators for \TeX/ registers
103 \printdoctail alloc.opm
104 \printdoc alloc.opm
105
106 \sec If-macros, loops, is-macros, cases
107 \printdoc if-macros.opm
108
109 \sec Setting parameters
110 \printdoctail parameters.opm
111 \printdoc parameters.opm
112
113 \sec More \OpTeX/ macros
114 The second bundle of \OpTeX/ macros is here.
115 \printdoc more-macros.opm
116
117 \sec Using key=value format in parameters
118 \printdoctail keyval.opm
119 \printdoc keyval.opm
120
121 \sec[plain] Plain \TeX/ macros
122 All macros from plain \TeX/ are rewritten here.
123 Differences are mentioned in the documentation below.
124 \printdoc plain-macros.opm
125
126 \sec Preloaded fonts for text mode
127 \printdoctail fonts-preload.opm
128 \printdoc fonts-preload.opm
129
130 \printdoctail fonts-resize.opm
131 \secc[fresize] Implementation of resizing
132 Only \"resizing" macros and \^`\initunifonts` are implemented here.
133 Other aspects of Font Selection System and their implementation are described in
134 section~\ref[fselect].
135 \printdoc fonts-resize.opm
136
137 \printdoctail fonts-select.opm
138 \secc[fselect] Implementation of the Font Selection System
139 \printdoc fonts-select.opm
140
141 \sec [math-preload] Preloaded fonts for math mode
142 \printdoctail math-preload.opm
143 \printdoc math-preload.opm
144
145 \sec[math-macros] Math macros
146 \printdoc math-macros.opm
147
148 \sec Unicode-math fonts
149 \printdoctail unimath-macros.opm
150
151 \sec[opmac-fonts] Scaling fonts in document (high-level macros)
152 These macros are documented in section~\ref[sizes] from the user point of view.
153 \printdoc fonts-opmac.opm
154
155 \sec[output] Output routine
156 \printdoctail output.opm
157 \printdoc output.opm
158
159 \sec Margins
160 The `\margins` macro is documented in the section~\ref[marg].
161 \printdoc margins.opm
162
163 \sec[colors] Colors
164 \printdoctail colors.opm
165 \printdoc colors.opm
166
167 \sec[ref-file] The \code{.ref} file
168 \printdoctail ref-file.opm
169 \printdoc ref-file.opm
170
171 \sec[references] References
172 \printdoctail references.opm
173 \printdoc references.opm
174
175 \sec Hyperlinks
176 \printdoctail hyperlinks.opm
177 \printdoc hyperlinks.opm
178
179 \sec[maketoc] Making table of contents
180 \printdoc maketoc.opm
181
182 \sec PDF outlines
183 \secc Nesting PDF outlines
184 \printdoctail outlines.opm
185 \printdoc outlines.opm
186 \secc Strings in PDF outlines
187 \printdoctail pdfuni-string.opm
188 \printdoc pdfuni-string.opm
189
190 \sec[sections] Chapters, sections, subsections
191 \printdoc sections.opm
192
193 \sec[lists] Lists, items
194 \printdoc lists.opm
195
196 \sec Verbatim, listings
197 \secc[verb] Inline and \"display" verbatim
198 \printdoc verbatim.opm
199 \secc[hisyntax] Listings with syntax highlighting
200 \printdoctail hi-syntax.opm
201 \printdoc hi-syntax.opm
202
203 \sec[graphics] Graphics
204 \printdoctail graphics.opm
205 \printdoc graphics.opm
206
207 \sec[table] The \code{\\table} macro, tables and rules
208 \printdoctail table.opm
209 \secc[table.impl] Implementation of the \code{\\table} macro and friends
210 \printdoc table.opm
211
212 \sec Balanced multi-columns
213 \printdoc multicolumns.opm
214
215 \sec Citations, bibliography
216 \secc[bib] Macros for citations and bibliography preloaded in the format
217 \printdoc cite-bib.opm
218 \secc[usebib] The \code{\\usebib} command
219 \printdoctail usebib.opm
220 \secc The \code{usebib.opm} macro file loaded when \code{\\usebib} is used
221 \printdoc usebib.opm
222
223 \secc[isobib] Usage of the \code{bib-iso690} style
224 {\everyintt={\catcode`\<=13 \visiblesp}
225 \printdoctail bib-iso690.opm }
226
227 \secc Implementation of the \code{bib-iso690} style
228 \printdoc bib-iso690.opm
229
230 \sec[makeindex] Sorting and making Index
231 \printdoc makeindex.opm
232
233 \sec[fnotes] Footnotes and marginal notes
234 \printdoc fnotes.opm
235
236 \sec Styles
237 \OpTeX/ provides three styles: `\report`, `\letter` and `\slides`.
238 Their behavior is documented in user part of the manual in the section
239 \ref[styles] and `\slides` style (for presentations) is documented in
240 `op-slides.pdf` which is an example of the presentation.
241 \secc \code{\\report} and \code{\\letter} styles
242 \printdoc styles.opm
243 \secc[slides] \code{\\slides} style for presentations
244 \printdoc slides.opm
245
246 \sec Logos
247 \printdoc logos.opm
248
249 \sec Multilingual support
250 \secc Lowercase, uppercase codes
251 \printdoctail uni-lcuc.opm
252 %\printdoc hyphen-lan.opm
253 %\printdoctail hyphen-lan.opm
254 \secc[langphrases] Multilingual phrases and quotation marks
255 \printdoc languages.opm
256 \secc[langdecl] Languages declaration
257 \printdoc lang-decl.opm
258
259 \sec[others] Other macros
260 Miscellaneous macros are here.
261 \printdoc others.opm
262
263 \sec[lua] Lua code embedded to the format
264
265 The file `optex.lua` is loaded into the format in `optex.ini` as byte-code
266 and initialized by `\everyjob`, see section~\ref[init].
267
268 The file implements part of the functionality from `luatexbase` namespace,
269 nowadays defined by \LaTeX/ kernel. `luatexbase` deals with modules,
270 allocators, and callback management. Callback management is a nice extension
271 and is actually used in \OpTeX/. Other functions are defined more or less just
272 to suit luaotfload's use.
273
274 The allocations are declared in subsection~\ref[lua-alloc], callbacks are
275 implemented in subsection~\ref[callbacks] and handling with colors can be
276 found in the subsection~\ref[lua-colors].
277
278 {\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \_hfuzz=1em \medskip}
279 \commentchars-- \def\docfile{optex.lua} \ttline=-1
280 \_def\_printcomments{\_medskip
281 {\_catcodetable0 \_typosize[10/12]\_everypar={}\_scantextokens\_ea{\_vcomments}\par}%
282 \_bigskip
283 \_ifx\_normalprintfilename\_undefined\_else \_let\_printfilename=\_normalprintfilename \_fi
284 }
285
286 \verbinput \hisyntax{lua} (4-) optex.lua
287 }
288
289
290 \sec[doc] Printing documentation
291 \printdoctail doc.opm
292 \printdoc doc.opm
293
294 \enddocument
295