| 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 |
|