Debian Codegraph @

texmf-dist/doc/optex/base/optex-userdoc.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 (three times) to create whole documentation.
5
6 \let\new=\relax
7
8 \sec Starting with \OpTeX/
9 %%%%%%%%%%%%%%%%%%%%%%%%%
10
11 \new
12 \OpTeX/ is compiled as a format for \LuaHBTeX/. Maybe there is a command
13 `optex` in your \TeX/ distribution. Then you can write into the command line
14
15 \begtt
16 optex document
17 \endtt
18 %
19 You can try to process `optex op-demo` or `optex optex-doc`.
20
21 If there is no `optex` command, see more information about installation
22 \OpTeX/ at \url{http://petr.olsak.net/optex}.
23
24 A minimal document should be
25
26 \begtt
27 \fontfam[LMfonts]
28 Hello World! \bye
29 \endtt
30
31 The first line \~`\fontfam[LMfonts]` tells that Unicode Latin Modern
32 fonts (derived from Computer Modern) are used. If you omit this line then
33 preloaded Latin Modern fonts are used but preloaded fonts cannot be in
34 Unicode\fnote
35 {This is a technical limitation of \LuaTeX/ for fonts downloaded in formats:
36 only 8bit fonts can be preloaded.}.
37 So the sentence `Hello World` will be OK without the first line, but you
38 cannot print such sentence in other languages (for example `Ahoj světe!`)
39 where Unicode fonts are needed
40 because the characters like `ě` are not mapped correctly in preloaded
41 fonts.
42
43 A somewhat larger example with common settings should be:
44
45 \begtt \catcode`!=0
46 \fontfam[Termes] % selecting Unicode font family Termes (section !ref[fontfam])
47 \typosize[11/13] % setting default font size and baselineskip (sec. !ref[sizes])
48 \margins/1 a4 (1,1,1,1)in % setting A4 paper, 1 in margins (section !ref[marg])
49 \cslang % Czech hyphenation patterns (section !ref[lang])
50
51 Tady je zkušební textík v českém jazyce.
52 \bye
53 \endtt
54 %
55 You can look at `op-demo.tex` file for a more complex, but still simple example.
56
57 \sec Page layout
58 %%%%%%%%%%%%%%%%
59
60 \secc[marg] Setting the margins
61 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
62
63 The \^`\margins` command declares margins of the document. This command have
64 the following parameters:
65
66 \begtt \catcode`\<=13
67 \margins/<pg> <fmt> (<left>,<right>,<top>,<bot>)<unit>
68 example:
69 \margins/1 a4 (2.5,2.5,2,2)cm
70 \endtt
71
72 Parameters are:
73
74 \begitems
75 * <pg> \dots\ `1` or `2` specifies one-page or two-pages design.
76 * <fmt> \dots\ paper format (a4, a4l, a5, letter, etc. or user defined).
77 * <left>, <right>, <top>, <bot> \dots\ gives the amount of left, right,
78 top and bottom margins.
79 * <unit> \dots\ unit used for values <left>, <right>, <top>, <bot>.
80 \enditems
81
82 Each of the parameters <left>, <right>, <top>, <bot> can be empty.
83 If both <left> and <right> are nonempty then `\hsize` is set. Else `\hsize`
84 is unchanged. If both <left> and <right> are empty then typesetting area is
85 centered in the paper format. The analogical rule works when <top> or <bot>
86 parameter is empty (`\vsize` instead `\hsize` is used). Examples:
87
88 \begtt
89 \margins/1 a4 (,,,)mm % \hsize, \vsize untouched,
90 % typesetting area centered
91 \margins/1 a4 (,2,,)cm % right margin set to 2cm
92 % \hsize, \vsize untouched, vertically centered
93 \endtt
94
95 If `<pg>=1` then all pages have the same margins. If `<pg>=2` then the
96 declared margins are true for odd pages. The margins at the even pages are
97 automatically mirrored in such case, it means that <left> is replaced by
98 <right> and vice versa.
99
100 \OpTeX/ declares following paper formats: a4, a4l (landscape~a4),
101 a5, a5l, a3, a3l, b5, letter and user can declare another own format by \~`\sdef`:
102
103 \begtt
104 \sdef{_pgs:b5l}{(250,176)mm}
105 \sdef{_pgs:letterl}{(11,8.5)in}
106 \endtt
107
108 The `<fmt>` can be also in the form `(<width>,<height>)<unit>` where `<unit>` is
109 optional. If it is missing then `<unit>` after margins specification is
110 used. For example:
111
112 \begtt
113 \margins/1 (100,200) (7,7,7,7)mm
114 \endtt
115 %
116 declares the paper 100$\times$200\,mm with all four margins 7\,mm. The spaces
117 before and after <fmt> parameter are necessary.
118
119 The command \^`\magscale[<factor>]` scales the whole typesetting area.
120 \new The fixed point of such scaling is the upper left corner of the paper sheet.
121 Typesetting (breakpoints etc.) is unchanged. All units are relative after
122 such scaling. Only paper format's dimensions stay unscaled. Example:
123
124 \begtt
125 \margins/2 a5 (22,17,19,21)mm
126 \magscale[1414] \margins/1 a4 (,,,)mm
127 \endtt
128 %
129 The first line sets the `\hsize` and `\vsize` and margins for final
130 printing at a5 format. The setting on the second line centers the scaled
131 typesetting area to the true a4 paper while breaking points for paragraphs
132 and pages are unchanged. It may be usable for
133 review printing. After the review is done, the second line can be commented out.
134
135 \secc Concept of the default page
136 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
137
138 \OpTeX/ uses \"output routine" for page design.
139 It is very similar to the Plain \TeX/ output routine.
140 There is \^`\headline` followed by \"page body" followed by
141 \^`\footline`. The \^`\headline` is empty by default and it can be used
142 for running headers repeated on each page. The \^`\footline` prints
143 centered page number by default. You can set the \^`\footline` to empty
144 using \^`\nopagenumbers` macro.
145
146 The margins declared by \^`\margins` macro (documented in the previous
147 section~\ref[marg]) is concerned to the page body,
148 i.e.\ the \^`\headline` and \^`\footline` are placed to the top and bottom
149 margins.
150
151 The distance between the \^`\headline` and the top of the page body is given by
152 the \^`\headlinedist` register. The distance between bottom of the page body and
153 the \^`\footline` is given by \^`\footlinedist`. The default values are:
154
155 \begtt
156 \headline = {}
157 \footline = {\_hss\_rmfixed \_folio \_hss} % \folio expands to page number
158 \headlinedist = 14pt % from baseline of \headline to top of page body
159 \footlinedist = 24pt % from last line in pagebody to baseline of footline
160 \endtt
161
162 The page body should be divided into top insertions (floating tables and
163 figures) followed by a real text and followed by footnotes.
164 Typically, the only real text is here.
165
166 The \^`\pgbackground` tokens list is empty by default but it can be used for
167 creating a background of each page (colors, picture, watermark for example).
168 The macro \^`\draft` uses this register and puts big text DRAFT as a watermark
169 to each page. You can try it.
170
171 More about the page layout is documented in sections~\ref[oparams] and~\ref[output].
172
173 \secc Footnotes and marginal notes
174 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
175
176 The Plain \TeX/'s macro \^`\footnote` can be used as usual. But a new macro
177 \^`\fnote{<text>}` is defined. The footnote mark is added automatically and it
178 is numbered
179 \new
180 on each chapter from one\fnote
181 {You can declare \^`\fnotenumglobal` if you want footnotes numbered in whole
182 document from one or \^`\fnotenumpages` if you want footnotes numbered at each
183 page from one. Default setting is \^`\fnotenumchapters`}.
184 The <text> is scaled to 80 \%.
185 User can redefine footnote mark or scaling, as shown in the section~\ref[fnotes].
186
187 The \^`\fnote` macro is fully applicable only in \"normal outer" paragraph.
188 It doesn't work inside boxes (tables, for example). If you are solving such
189 a case then you can use the command \^`\fnotemark``<numeric-label>` inside the box: only the
190 footnote mark is generated here. When the box is finished you can use
191 \^`\fnotetext{<text>}`. This macro puts the <text> to the footnote.
192 The <numeric-label> has to be `1` if only one such command is in the box.
193 Second \^`\fnotemark` inside the same box has to have the parameter `2` etc.
194 The same number of \^`\fnotetext`s have to be written
195 after the box as the number of \^`\fnotemark`s inserted inside the box.
196 Example:
197
198 \begtt
199 Text in a paragraph\fnote{First notice}... % a "normal" footnote
200 \table{...}{...\fnotemark1...\fnotemark2...} % two footnotes in a box
201 \fnotetext{Second notice}
202 \fnotetext{Third notice}
203 ...
204 \table{...}{...\fnotemark1...} % one footnote in a box
205 \fnotetext{Fourth notice}
206 \endtt
207
208 The marginal note can be printed by the \^`\mnote{<text>}` macro. The <text>
209 is placed to the right margin on the odd pages and it is placed to the left
210 margin on the even pages. This is done after second \TeX{} run because the
211 relevant information is stored in an external file and read from it again.
212 If you need to place the notes only to the fixed margin write
213 \^`\fixmnotes\right` or \^`\fixmnotes\left`.
214
215 The <text> is formatted as a little paragraph with the maximal width
216 \^`\mnotesize` ragged left on the left margins or ragged right on the right
217 margins. The first line of this little paragraph has its vertical position
218 given by the position of \^`\mnote` in the text. The exceptions are possible
219 by using the `up` keyword: \~`\mnote`` up<dimen>{<text>}`.
220 You can set such <dimen> to each \^`\mnote` manually in final printing
221 in order to margin notes do not overlap. The positive value of <dimen>
222 shifts the note up and negative value shifts it down. For example
223 \^`\mnote`` up 2\baselineskip{<text>}` shifts this marginal note two lines up.
224
225 \sec Fonts
226 %%%%%%%%%%
227
228 \secc[fontfam] Font families
229 %%%%%%%%%%%%%%%%%%%%%%%
230
231 You can select the font family by \^`\fontfam[<Family-name>]`.
232 The argument <Family-name> is case insensitive and spaces are ignored in it. For
233 example, \^`\fontfam[LM Fonts]` is equal to \^`\fontfam[LMfonts]` and it is equal
234 to \^`\fontfam[lmfonts]`. Several aliases are prepared, thus
235 \^`\fontfam[Latin Modern]` can be used for loading Latin Modern family too.
236
237 If you write \^`\fontfam[?]` then all font families registered in \OpTeX/
238 are listed on the terminal and in the log file.
239 If you write \^`\fontfam[catalog]` then a catalog of all fonts registered in
240 \OpTeX/ and available in your \TeX/ system is printed.
241 See also \ulink[http://petr.olsak.net/ftp/olsak/optex/op-catalog.pdf]{this catalog}.
242
243 If the family is loaded then {\em font modifiers} applicable in such font family
244 are listed on the terminal: (`\caps`, `\cond` for example).
245 And there are four basic {\em variant selectors} (\^`\rm`, \^`\bf`, \^`\it`, \^`\bi`).
246 The usage of variant selectors is the same as in Plain \TeX:
247 `{\it italics text}`, `{\bf bold text}` etc.
248
249 The font modifiers (`\caps`, `\cond` for example) can
250 be used before a variant selector and they
251 can be (independently) combined: `\caps\it` or `\cond\caps\bf`. The
252 modifiers keep their internal setting until the group ends or until another
253 modifier that negates the previous feature is used. So
254 `{\caps \rm First text \it Second text}`
255 gives {\caps \rm First text \it Second text}.
256
257 The font modifier without following variant selector does not change the font
258 actually, it only prepares data used by next variant selectors.
259 There is one special variant selector \^`\currvar` which does not change the
260 selected variant but reloads the font due to (maybe newly
261 specified) font modifier(s).
262
263 The context between variants \^`\rm` $\leftrightarrow$ \^`\it` and
264 \^`\bf` $\leftrightarrow$ \^`\bi` is kept by the \^`\em`
265 macro (emphasize text).
266 It switches from current \^`\rm` to \^`\it`, from current \^`\it` to \^`\rm`, from
267 current \^`\bf` to \^`\bi` and from current \^`\bi` to \^`\bf`.
268 The italics correction `\/` is inserted automatically, if needed. Example:
269
270 \begtt
271 This is {\em important} text. % = This is {\it important\/} text.
272 \it This is {\em important} text. % = This is\/ {\rm important} text.
273 \bf This is {\em important} text. % = This is {\bi important\/} text.
274 \bi This is {\em important} text. % = This is\/ {\bf important} text.
275 \endtt
276
277 \new
278 More about the \OpTeX/ Font Selection System is written in the technical
279 documentation in the section~\ref[fontsystem].
280 You can mix more font families in your document, you can
281 declare your own variant selectors or modifiers, etc.
282
283 \secc[sizes] Font sizes
284 %%%%%%%%%%%%%%%%%%%%%
285
286 The command \^`\typosize[<fontsize>/<baselineskip>]` sets the font size of text and
287 math fonts and baselineskip. If one of these two parameters is empty, the
288 corresponding feature stays unchanged. Don't write the unit of these
289 parameters. The unit is internally set to \^`\ptunit` which is 1pt by default.
290 You can change the unit by the command \^`\ptunit=<something-else>`,
291 for instance \^`\ptunit=1mm` enlarges all font sizes declared by \^`\typosize`.
292 Examples:
293
294 \begtt
295 \typosize[10/12] % default of Plain TeX
296 \typosize[11/12.5] % font 11pt, baseline 12.5pt
297 \typosize[8/] % font 8pt, baseline unchanged
298 \endtt
299
300 The commands for font size setting described in this section
301 have local validity. If you put them into a group,
302 the settings are lost when the group is finished. If you set
303 something relevant with paragraph shape (baselineskip given by
304 \^`\typosize` for example) then you must first finalize the
305 paragraph before closing the group:
306 `{\typosize[12/14] ...<text of paragraph>... \par}`.
307
308 The command \^`\typoscale[<font-factor>/<baselineskip-factor>]`
309 sets the text and math fonts
310 size and baselineskip as a multiple of the current fonts size and
311 baselineskip. The factor is written in \"scaled"-like way, it means that 1000
312 means factor one. The empty parameter is equal to the parameter 1000,
313 i.e. the value stays unchanged. Examples:
314
315 \begtt
316 \typoscale[800/800] % fonts and baselineskip re-size to 80 %
317 \typoscale[\magstep2/] % fonts bigger 1,44times (\magstep2 expands to 1440)
318 \endtt
319
320 First usage of \^`\typosize` or \^`\typoscale` macro in your document sets so-called {\em main values}, i.\,e.\ main font size and main baselineskip. They are internally
321 saved in registers \^`\mainfosize` and \^`\mainbaselineskip`.
322
323 \new
324 The \^`\typoscale` command does scaling with respect to current values by default.
325 If you want to do it with respect to the main values, type \^`\scalemain` immediately
326 before \^`\typoscale` command.
327
328 \begtt
329 \typosize[12/14.4] % first usage in document, sets main values internally
330 \typosize[15/18] % bigger font
331 \scalemain \typoscale[800/800] % reduces from main values, no from current.
332 \endtt
333
334 The \^`\typosize` and \^`\typoscale` macros initialize the font family by `\rm`.
335 You can re-size only the current font by the command
336 \^`\thefontsize[<font-size>]` or the font can be rescaled by
337 \^`\thefontscale[<factor>]`. These macros don't change math fonts sizes nor
338 baselineskip.
339
340 \new
341 There is \"low level" \^`\setfontsize{<size-spec>}` command which behaves like
342 a font modifier and sets given font size used by next variant selectors.
343 It doesn't change the font size immediately, but the following variant selector
344 does it. For example \^`\setfontsize{at15pt}`\^`\currvar` sets current variant to 15pt.
345
346 If you are using a font family with \"optical sizes feature" (i.\,e.\ there
347 are more recommended sizes of the same font which are not scaled
348 linearly; a good example is Computer Modern aka Latin Modern fonts)
349 then the recommended size is selected by all mentioned commands automatically.
350
351 More information about resizing of fonts is documented in the
352 section~\ref[setfontsize].
353
354 \secc Typesetting math
355 %%%%%%%%%%%%%%%%%%%%%
356
357 See the additional document
358 \ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf]
359 {Typesetting Math with \OpTeX/} for more details about this issue.
360
361 \OpTeX/ preloads a collection of 7bit Computer Modern math fonts
362 and AMS fonts in its format for math typesetting.
363 You can use them in any size and in the \^`\boldmath` variant.
364 %
365 \new
366 Most declared text font families (see \^`\fontfam` in the section~\ref[fontfam])
367 are configured with a recommended Unicode
368 math font. This font is automatically loaded unless you specify
369 \^`\noloadmath` before first \^`\fontfam` command. See log file for more
370 information about loading text font family and Unicode math fonts. If you
371 prefer another Unicode math font, specify it by \^`\loadmath{[<font-file>]}`
372 or \^`\loadmath{<font-name>}` before first \^`\fontfam` command.
373
374 Hundreds math symbols and operators like in AMS\TeX/ are accessible.
375 For example `\alpha` $\alpha$, `\geq`~$\geq$, `\sum` $\sum$,
376 `\sphericalangle` $\sphericalangle$, `\bumpeq`, $\bumpeq$. See AMS\TeX/
377 manual or
378 \ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf\#ref:objects]
379 {Typesetting Math with \OpTeX/} for complete list of math symbols.
380
381 The following math alphabets are available:
382
383 \begtt \catcode`\$=3 \catcode`/=0 \medmuskip=0mu \adef{ }{ }
384 \mit % mathematical variables $abc-xyz,ABC-XYZ$
385 \it % text italics $/it abc-xyz,ABC-XYZ$
386 \rm % text roman $/rm abc-xyz,ABC-XYZ$
387 \cal % normal calligraphics $/cal ABC-XYZ$
388 \script % script $/script ABC-XYZ$
389 \frak % fracture $/frak abc-xyz,ABC-XYZ$
390 \bbchar % double stroked letters $/bbchar ABC-XYZ$
391 \bf % sans serif bold $/bf abc-xyz,ABC-XYZ$
392 \bi % sans serif bold slanted $/bi abc-xyz,ABC-XYZ$
393 \endtt
394
395 The last two selectors \^`\bf` and \^`\bi` select the sans serif fonts in math regardless of the current text font family. This is a common notation for vectors and
396 matrices. You can re-declare them, see section~\ref[unimath-codes] where
397 definitions of Unicode math variants of \^`\bf` and \^`\bi` selectors are documented.
398
399 The math fonts can be scaled by \^`\typosize` and \^`\typoscale` macros.
400 Two math fonts collections are prepared: \^`\normalmath` for normal weight
401 and \^`\boldmath` for bold. The first one is set by default, the second one
402 is usable for math formulae in titles typeset in bold, for example.
403
404 \new
405 You can use \^`\mathbox{<text>}` inside math mode. It behaves as `{\hbox{<text>}}`
406 (i.e. the <text> is printed in horizontal non-math mode)
407 but the size of the <text> is adapted to the context of math size (text or script or
408 scriptscript).
409
410 \sec Typical elements of the document
411 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
412
413 \secc[chap] Chapters and sections
414 %%%%%%%%%%%%%%%%%%%%%%%%%%
415
416 The documents can be divided into chapters (\^`\chap`),
417 sections (\^`\sec`), subsections (\^`\secc`) and they can be titled
418 by \^`\tit` command. The parameters are separated by the end of current line (no
419 braces are used):
420
421 \begtt \catcode`\<=13
422 \tit Document title <end of line>
423 \chap Chapter title <end of line>
424 \sec Section title <end of line>
425 \secc Subsection title <end of line>
426 \endtt
427
428 The chapters are automatically numbered by one number, sections by two numbers
429 (chapter.section), and subsections by three numbers. If there are no chapters
430 then sections have only one number and subsections two.
431
432 The implicit design of the titles of chapter etc.\ is implemented in the
433 macros \^`\_printchap`, \^`\_printsec` and \^`\_printsecc`. A designer can simply change
434 these macros if he/she needs another behavior.
435
436 The first paragraph after the title of chapter, section, and subsection is
437 not indented but you can type `\let`\^`\_firstnoindent=\relax` if you need all
438 paragraphs indented.
439
440 If a title is so long then it breaks into more lines in the output. It is better to hint at the
441 breakpoints because \TeX/ does not interpret the meaning of the title.
442 Users can put the \^`\nl` (means newline) to the breakpoints.
443
444 If you want to arrange a title to more lines in your source file then you can
445 use `^^J` at the end of each line (except the last one).
446 When `^^J` is used, then the reading of the title continues at the next line.
447 The \"normal" comment character `%` doesn't work in titles.
448 You can use \^`\nl`{\visiblesp` ^^J`} if you want to have corresponding lines in the source
449 and the output.
450
451 The chapter, section, or subsection isn't numbered if the \^`\nonum` precedes.
452 And the chapter, section, or subsection isn't delivered to the table of
453 contents if \^`\notoc` precedes. You can combine both prefixes.
454
455 \secc[cap] Another numbered objects
456 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
457
458 Apart from chapters, sections, and subsections, there are another
459 automatically numbered objects: equations, captions for tables and
460 figures. The user can declare more numbered objects.
461
462 If the user writes the \^`\eqmark` as the last element of the display mode then
463 this equation is numbered. The equation number is printed in brackets. This number
464 is reset in each section by default. You can declare \^`\swapeqno` if you
465 want to put equation marks to the opposite side.
466
467 If the \^`\eqalignno` is used, then user can put \^`\eqmark` to the last column
468 before `\cr`. For example:
469
470 \begtt
471 \eqalignno{
472 a^2+b^2 &= c^2 \cr
473 c &= \sqrt{a^2+b^2} & \eqmark \cr}
474 \endtt
475
476 Another automatically numbered object is a caption which is tagged by \^`\caption/t` for
477 tables and \^`\caption/f` for figures. The caption text follows.
478 The \^`\cskip` can be used between \^`\caption` text and the real object (table
479 or figure). You can use two orders: `<caption>\cskip <object>` or
480 `<object>\cskip <caption>`.
481 The \^`\cskip` creates appropriate vertical space between them. Example:
482
483 \begtt
484 \caption/t The dependency of the computer-dependency on the age.
485 \cskip
486 \noindent\hfil\table{rl}{
487 age & value \crl\noalign{\smallskip}
488 0--1 & unmeasured \cr
489 1--6 & observable \cr
490 6--12 & significant \cr
491 12--20 & extremal \cr
492 20--40 & normal \cr
493 40--60 & various \cr
494 60--$\infty$ & moderate}
495 \endtt
496
497 This example produces:
498
499 \medskip
500 \caption/t The dependency of the computer-dependency on the age.
501 \cskip
502 \noindent\hfil\table{rl}{
503 age & value \crl\noalign{\smallskip}
504 0--1 & unmeasured \cr
505 1--6 & observable \cr
506 6--12 & significant \cr
507 12--20 & extremal \cr
508 20--40 & normal \cr
509 40--60 & various \cr
510 60--$\infty$ & moderate}
511 \medskip
512
513 You can see that the word \"Table" followed by a number is added by the macro
514 `\caption/t`.
515 The caption text is centered. If it occupies more lines then the
516 last line is centered.
517
518 The macro \^`\caption/f` behaves like \^`\caption/t` but it is intended for
519 figure captions with independent numbering.
520 The word (Table, Figure) depends on the selected language (see
521 section~\ref[lang] about languages).
522
523 If you wish to make the table or figure as a floating object, you need to use
524 Plain \TeX/ macros \^`\midinsert` or \^`\topinsert` terminated by \^`\endinsert`.
525 Example:
526
527 \begtt
528 \topinsert % table and its caption printed at the top of the current page
529 <caption and table>
530 \endinsert
531 \endtt
532 %
533 The pair \^`\midinsert`...\^`\endinsert` prefers to put the enclosed object
534 to the current place. Only if this is unable due to page breaking, it
535 behaves like \^`\topinsert`...\^`\endinsert`.
536
537 \new
538 There are five prepared counters `A`, `B`, `C`, `D` and `E`.
539 They are reset in each chapter and section\fnote
540 {This feature can be changed, see the section~\ref[sections] in the technical documentation.}.
541 They can be used in context of \^`\numberedpar` `<letter>{<text>}`
542 macro. For example:
543 \begtt
544 \def\theorem {\numberedpar A{Theorem}}
545 \def\corollary {\numberedpar A{Corollary}}
546 \def\definition {\numberedpar B{Definition}}
547 \def\example {\numberedpar C{Example}}
548 \endtt
549 %
550 Three independent numbers are used in this example. One for Theorems and Corollaries
551 second for Definitions and third for Examples. The user can write
552 `\theorem Let $M$ be...` and the new paragraph is started with the text:
553 {\bf Theorem 1.4.1.} Let $M$ be...
554 You can add an optional parameter in brackets. For example,
555 `\theorem [(L'Hôpital's rule)] Let $f$, $g$ be...`
556 is printed like {\bf Theorem 1.4.2 (L'Hôpital's rule).} Let $f$, $g$ be...
557
558 \secc References
559 %%%%%%%%%%%%%%%
560
561 Each automatically numbered object documented in
562 sections \ref[chap] and \ref[cap] can be referenced
563 \new
564 if optional parameter
565 `[<label>]` is appended to \^`\chap`, \^`\sec`,
566 \^`\secc`, \^`\caption/t`, \^`\caption/f` or \^`\eqmark`. The alternative syntax is
567 to use \^`\label[<label>]` before mentioned commands (not necessarily directly
568 before). The reference is realized by \^`\ref[<label>]` (prints the number
569 of the referenced object) or \^`\pgref[<label>]` (prints the page number).
570 Example:
571
572 \begtt
573 \sec[beatle] About Beatles
574
575 \noindent\hfil\table{rl}{...} % the table
576 \cskip
577 \caption/t [comp-depend] The dependency of the comp-dependency on the age.
578
579 \label[pythagoras]
580 $$ a^2 + b^2 = c^2 \eqmark $$
581
582 Now we can point to the section~\ref[beatle] on the page~\pgref[beatle]
583 or write something about the equation~\ref[pythagoras]. Finally there
584 is an interesting Table~\ref[comp-depend].
585 \endtt
586
587 The text printed by \^`\ref` or \^`\pgref` can be given explicitly by
588 \^`\ref[<label>]{<text>}` or \^`\pgref[<label>]{<text>}`. If the `<text>`
589 includes the `@` character, it is replaced by implicitly printed text.
590 Example: `see \ref[lab]{section~@}` prints the same as `see section~\ref[lab]`,
591 but first case creates larger active area for mouse clicking, when
592 \~`\hyperlinks` are declared.
593
594 If there are forward referenced objects then users have to run \TeX{} twice.
595 During each pass, the working `*.ref` file (with references data) is created
596 and this file is used (if it exists) at the beginning of the document.
597
598 You can use the \^`\label[<label>]` before the `\theorem`, `\definition` etc.\
599 (macros defined with `\numberedpar`) if you want to reference these numbered objects.
600 You can't use `\theorem[<label>]` because the optional parameter
601 is reserved to another purpose here.
602
603 You can create a reference to whatever else by commands
604 \^`\label[<label>]`\^`\wlabel{<text>}`. The connection between <label> and
605 <text> is established. The \^`\ref[<label>]` will print <text>.
606
607 By default, labels are not printed, of course. But if you are preparing a
608 draft version of your document then you can declare \^`\showlabels`. The labels
609 are printed at their destination places after such a declaration.
610
611 \secc Hyperlinks, outlines
612 %%%%%%%%%%%%%%%%%%%%%%%%%
613
614 If the command \^`\hyperlinks` `<color-in> <color-out>` is used at the beginning of
615 the document, then the following objects are hyperlinked in the PDF output:
616
617 \begitems
618 * numbers and texts generated by \^`\ref` or \^`\pgref`,
619 * numbers of chapters, sections, subsections, and page numbers in the table of contents,
620 * numbers or marks generated by \~`\cite` command (bibliography references),
621 * texts printed by \~`\url` or \~`\ulink` commands.
622 \enditems
623
624 The last object is an external link and it is colored by
625 <color-out>. Other links are internal and they are colored by
626 <color-in>. Example:
627
628 \begtt
629 \hyperlinks \Blue \Green % internal links blue, URLs green.
630 \endtt
631
632 You can use another marking of active links: by frames which are visible in
633 the PDF viewer but invisible when the document is printed. The way to do it
634 is to define the macros \^`\_pgborder`, \^`\_tocborder`, \^`\_citeborder`,
635 \^`\_refborder` and \^`\_urlborder` as the triple of RGB components of the used
636 color. Example:
637
638 \begtt
639 \def\_tocborder {1 0 0} % links in table of contents: red frame
640 \def\_pgborder {0 1 0} % links to pages: green frame
641 \def\_citeborder {0 0 1} % links to references: blue frame
642 \endtt
643
644 By default, these macros are not defined. It means that no frames are created.
645
646 The hyperlinked footnotes can be activated by \^`\fnotelinks` `<color-fnt> <color-fnf>`
647 where footnote marks in the text have `<color-fnt>` and the same footnote marks
648 in footnotes have <color-fnf>. You can define relevant borders
649 \^`\_fntborder` and \^`\_fnfborder` analogically as \^`\_pgborder` (for example).
650
651 There are \"low level" commands to create the links. You can specify the
652 destination of the internal link by \^`\dest[<type>:<label>]`. The
653 active text linked to the \^`\dest` can be created by
654 \^`\ilink[<type>:<label>]{<text>}`. The `<type>` parameter is one of
655 the `toc`, `pg`, `cite`, `ref`, or another special for your purpose.
656 These commands create internal links only when \^`\hyperlinks` is declared.
657
658 The \^`\url` macro prints its parameter in \~`\tt` font and creates a potential
659 breakpoints in it (after slash or dot, for example). If the \^`\hyperlinks`
660 declaration is used then the parameter of \^`\url` is treated as an external URL link.
661 An example: `\url{http://www.olsak.net}` creates \url{http://www.olsak.net}.
662 The characters \code{\%}, `\`, `#`, `{`, and `}` have to be protected by
663 backslash in the \^`\url` argument, the other special characters `~`,
664 `^`, `&` can be written as single character\fnote
665 {More exactly, there are the same rules as for `\code` command, see
666 section~\ref[verbatim].}.
667 You can insert the `\|` command
668 in the `\url` argument as a potential breakpoint.
669
670 If the linked text have to be different than the URL, you can use
671 \^`\ulink[<url>]{<text>}` macro. For example:
672 `\ulink[http://petr.olsak.net/optex]{\OpTeX/ page}`
673 outputs to the text
674 \ulink[http://petr.olsak.net/optex]{\OpTeX/ page}.
675 The characters \code{\%}, `\`, `#`, `{`, and `}` must be escaped in
676 the <url> parameter.
677
678 The PDF format provides {\em outlines} which are notes placed in the special frame of
679 the PDF viewer. These notes can be managed as a structured and hyperlinked
680 table of contents of the document. The command \^`\outlines{<level>}` creates
681 such outlines from data used for the table of contents in the document. The
682 <level> parameter gives the level of opened sub-outlines
683 in the default view. The deeper levels can be opened by mouse click on the
684 triangle symbol after that.
685
686 \new
687 If you are using a special unprotected macro in section titles then \^`\outlines` macro
688 may crash. You must declare a variant of the macro for outlines case which is
689 expandable. Use \~`\regmacro` in this case. See the section \ref[toc] for more information
690 about \~`\regmacro`.
691
692 The command \^`\insertoutline{<text>}` inserts a next entry into PDF outlines at
693 the main level~0. These entries can be placed before the table of contents (created
694 by \^`\outlines`) or after it. Their hyperlink destination is in the place
695 where the \^`\insertoutline` macro is used.
696
697 The command \^`\thisoutline{<text>}` uses <text> in the outline instead of default
698 title text for the first following `\chap`, `\sec`, or `\secc`.
699 Special case: \^`\thisoutline{\relax}` doesn't create any outline for the following
700 `\chap`, `\sec`, or `\secc`.
701
702 \secc Lists
703 %%%%%%%%%%
704
705 The list of items is surrounded by \^`\begitems` and \^`\enditems` commands.
706 The asterisk (`*`) is active within this environment and it starts one item.
707 The item style can be chosen by the \^`\style` parameter written after \^`\begitems`:
708
709 \def\otrickd{\ulink[http://petr.olsak.net/optex/optex-tricks.html\#deflists]{OpTeX trick 0108}}
710 \begtt \catcode`|=0
711 \style o % small bullet
712 \style O % big bullet (default)
713 \style - % hyphen char
714 \style n % numbered items 1., 2., 3., ...
715 \style N % numbered items 1), 2), 3), ...
716 \style i % numbered items (i), (ii), (iii), ...
717 \style I % numbered items I, II, III, IV, ...
718 \style a % items of type a), b), c), ...
719 \style A % items of type A), B), C), ...
720 \style x % small rectangle
721 \style X % big rectangle
722 \style d % definition list, use *{word}, see |otrickd
723 \endtt
724
725 For example:
726
727 \begtt
728 \begitems
729 * First idea
730 * Second idea in subitems:
731 \begitems \style i
732 * First sub-idea
733 * Second sub-idea
734 * Last sub-idea
735 \enditems
736 * Finito
737 \enditems
738 \endtt
739 %
740 produces:
741
742 \begitems
743 * First idea
744 * Second idea in subitems:
745 \begitems \style i
746 * First sub-idea
747 * Second sub-idea
748 * Last sub-idea
749 \enditems
750 * Finito
751 \enditems
752
753 Another style can be defined by the command \~`\sdef{_item:<style>}{<text>}`.
754 Default item can be set by \^`\defaultitem={<text>}`.
755 The list environments can be nested. Each new level of items is indented by
756 next multiple of \^`\iindent` value which is set to `\parindent` by default.
757 The \^`\ilevel` register says what level of items is currently processed.
758 Each \^`\begitems` starts \^`\everylist` tokens register. You can set, for
759 example:
760 \begtt
761 \everylist={\ifcase\ilevel\or \style X \or \style x \else \style - \fi}
762 \endtt
763
764 You can say \^`\begitems` \^`\novspaces` if you don't want vertical spaces above
765 and below the list. The nested item list is without vertical spaces
766 automatically. More information about the design of lists of items should be
767 found in the section~\ref[lists].
768
769 A \"selected block of text" can be surrounded by
770 \^`\begblock`\dots\^`\endblock`. The default design of blocks of text is
771 indented text in smaller font. The blocks of text can be nested.
772
773 \secc Tables
774 %%%%%%%%%%%
775
776 The macro \^`\table{<declaration>}{<data>}` provides similar <declaration>
777 of tables as in \LaTeX: you can use letters `l`, `r`, `c`, each letter declares
778 one column (aligned to left, right, center, respectively).
779 These letters can be combined by the `|` character (vertical line). Example
780
781 \begtt
782 \table{||lc|r||}{ \crl
783 Month & commodity & price \crli \tskip2pt
784 January & notebook & \$ 700 \cr
785 February & skateboard & \$ 100 \cr
786 July & yacht & k\$ 170 \crl}
787 \endtt
788 %
789 generates the result:
790
791 \vskip-\medskipamount
792 \noindent\hfil\table{||lc|r||}{ \crl
793 Month & commodity & price \crli \tskip2pt
794 January & notebook & \$ 700 \cr
795 February & skateboard & \$ 100 \cr
796 July & yacht & k\$ 170 \crl}
797 \medskip
798
799 Apart from `l`, `r`, `c` declarators, you can use the `p{<size>}` declarator
800 which declares the column with paragraphs of given width. More precisely,
801 a long text in the table cell is printed as a multiline paragraph with given width.
802 By default, the paragraph is left-right justified. But there are
803 alternatives:
804
805 \begitems
806 * `p{<size>`\^`\fL}` fit left, i.e.\ left justified, ragged right,
807 * `p{<size>`\^`\fR}` fit right, i.e.\ right justified, ragged left,
808 * `p{<size>`\^`\fC}` fit center, i.e.\ ragged left plus right,
809 * `p{<size>`\^`\fS}` fit special, short one-line paragraph centered,
810 long paragraph normal,
811 * `p{<size>`\^`\fX}` fit extra, left-right justified but last line centered.
812 \enditems
813
814 You can use `(<text>)` in the <declaration>. Then this text is applied in
815 each line of the table. For example `r(\kern10pt)l` adds more 10\,pt space
816 between `r` and `l` rows.
817
818 An arbitrary part of the <declaration> can be repeated by a <number>
819 prefixed. For example `3c` means `ccc` or `c 3{|c}` means
820 `c|c|c|c`. Note that spaces in the <declaration> are ignored and you
821 can use them in order to more legibility.
822
823 The command `\cr` used in the <data> part of the table
824 is generally known from Plain \TeX. It marks the end of each row in the table.
825 Moreover \OpTeX/ defines following similar commands:
826
827 \begitems
828 * \^`\crl` \dots\ the end of the row with a horizontal line after it.
829 * \^`\crll` \dots\ the end of the row with a double horizontal line after it.
830 * \^`\crli` \dots\ like \^`\crl` but the horizontal line doesn't intersect the
831 vertical double lines.
832 * \^`\crlli` \dots\ like \^`\crli` but horizontal line is doubled.
833 * \^`\crlp{<list>}` \dots\ like \^`\crli` but the lines are drawn only in the
834 columns mentioned in comma-separated `<list>` of their numbers.
835 The <list> can include `<from>-<to>` declarators, for example
836 \^`\crlp{1-3,5}` is equal to \^`\crlp{1,2,3,5}`.
837 \enditems
838
839 The \^`\tskip``<dimen>` command works like the `\noalign{\vskip<dimen>}`
840 immediately after `\cr*` commands but it doesn't interrupt the vertical lines.
841
842 \new
843 You can use the following parameters for the \^`\table` macro. Default values are listed
844 too.
845
846 \begtt
847 \everytable={} % code used in \vbox before table processing
848 \thistable={} % code used in \vbox, it is removed after using it
849 \tabiteml={\enspace} % left material in each column
850 \tabitemr={\enspace} % right material in each column
851 \tabstrut={\strut} % strut which declares lines distance in the table
852 \tablinespace=2pt % additional vert. space before/after horizontal lines
853 \vvkern=1pt % space between lines in double vertical line
854 \hhkern=1pt % space between lines in double horizontal line
855 \tabskip=0pt % space between columns
856 \tabskipl=0pt \tabskipr=0pt % space before first and after last column
857 \endtt
858
859 Example: if you do \^`\tabiteml={$\enspace}`\^`\tabitemr={\enspace$}` then
860 the \^`\table` acts like \LaTeX's array environment.
861
862 If there is an item that spans to more than one column in the table then
863 the macro \^`\multispan{<number>}` (from Plain \TeX) can help you. Another
864 alternative is
865 the command \^`\mspan``<number>[<declaration>]{<text>}`
866 which spans <number> columns and formats the <text> by the
867 <declaration>. The <declaration> must include a declaration of only one column
868 with the same syntax as common \^`\table` <declaration>.
869 If your table includes vertical rules and you want to
870 create continuous vertical rules by \^`\mspan`, then use rule declarators `|`
871 after `c`, `l` or `r` letter in \^`\mspan` <declaration>. The
872 exception is only in the case when \^`\mspan` includes the first
873 column and the table have rules on the left side. The example of \^`\mspan`
874 usage is below.
875
876 The \^`\frame{<text>}` makes a frame around <text>. You can put the whole \^`\table`
877 into \^`\frame` if you need double-ruled border of the table. Example:
878
879 \begtt
880 \frame{\table{|c||l||r|}{ \crl
881 \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli
882 first & second & third \crlli
883 seven & eight & nine \crli}}
884 \endtt
885 %
886 creates the following result:
887
888 \hfil\frame{\table{|c||l||r|}{\crl
889 \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli
890 first & second & third \crlli
891 seven & eight & nine \crli}}
892 \bigskip
893
894 The \^`\vspan``<number>{<text>}` shifts the <text> down in order it looks
895 like to be in the center of the <number> lines (current line is first).
896 You can use this for creating tables like in the following example:
897
898 \begtt \typosize[8.7/11]
899 \thistable{\tabstrut={\vrule height 20pt depth10pt width0pt}
900 \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt}
901 \table{|8{c|}}{\crlp{3-8}
902 \mspan2[c|]{} & \mspan3[c|]{Singular} & \mspan3[c|]{Plural} \crlp{3-8}
903 \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl
904 \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} & \mspan3[c|]{X} \crlp{2,6-8}
905 & Exclusive & \mspan3[c|]{} & \mspan3[c|]{X} \crl
906 \vspan2{II} & Informal & \mspan3[c|]{X} & \mspan3[c|]{X} \crlp{2-8}
907 & Formal & \mspan6[c|]{X} \crl
908 \vspan2{III} & Informal & \vspan2{O} & X & X & \mspan2[c|]{X} &\vspan2{O} \crlp{2,4-7}
909 & Formal & & \mspan4[c|]{X} & \crl
910 }
911 \endtt
912
913 \puttext 8.9cm -4cm {\pdfsave\pdfscale{.5}{.5}\rlap{%
914 \thistable{\tabstrut={\vrule height 20pt depth10pt width0pt}
915 \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt}
916 \table{|8{c|}}{\crlp{3-8}
917 \mspan2[c|]{} &\mspan3[c|]{Singular} &\mspan3[c|]{Plural} \crlp{3-8}
918 \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl
919 \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} &\mspan3[c|] X \crlp{2,6-8}
920 & Exclusive & \mspan3[c|]{} &\mspan3[c|] X \crl
921 \vspan2{II} & Informal & \mspan3[c|] X &\mspan3[c|] X \crlp{2-8}
922 & Formal & \mspan6[c|] X \crl
923 \vspan2{III} & Informal & \vspan2{O} & X & X &\mspan2[c|] X & \vspan2{O} \crlp{2,4-7}
924 & Formal & &\mspan4[c|] X & \crl
925 }}\pdfrestore}
926
927 \hangindent=-7.5cm \hangafter=0
928 You can use \^`\vspan` with non-integer parameter too if you feel that the
929 result looks better, for example \^`\vspan2.1{text}`.
930
931 \hangindent=-7.5cm \hangafter=0
932 The rule width of tables and implicit width of all `\vrule`s and `\hrule`s
933 can be set by the command \^`\rulewidth=<dimen>`. The default value given
934 by \TeX/ is 0.4\,pt.
935
936 \hangindent=-7.5cm \hangafter=-2
937 The `c`, `l`, `r` and `p` are default \"declaration letters" but you can define
938 more such letters by `\def\_tabdeclare<letter>{<left>##<right>}`.
939 More about it is in technical documentation in section~\ref[table.impl].
940 See the definition of the \^`\_tabdeclarec` macro, for example.
941
942 The `:` columns boundary declarator is described in section~\ref[table.bound].
943 The tables with given width can be declared by `to<size>` or `pxto<size>`.
944 More about it is in section~\ref[table.w].
945 Many tips about tables can be seen on the site
946 \url{http://petr.olsak.net/optex/optex-tricks.html}.
947
948 \label[verbatim]\secc Verbatim
949 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
950
951 The display verbatim text have to be surrounded by the \^`\begtt` and
952 \^`\endtt` couple.
953 The in-line verbatim have to be tagged (before and after)
954 by a character which is declared by
955 \^`\verbchar``<char>`. For example \code{\\verbchar`}
956 declares the character \code{`}
957 for in-line verbatim markup.
958 And you can use \code{`\\relax`} for
959 verbatim `\relax` (for example).
960 \new
961 Another alternative of printing in-line
962 verbatim text is \~`\code{<text>}` (see below).
963
964 If the numerical register \^`\ttline` is set to the non-negative value then
965 display verbatim will number the lines. The first line has the number
966 \^`\ttline+1` and when the verbatim ends then the \^`\ttline` value is equal to the
967 number of the last line printed. Next \^`\begtt``...`\^`\endtt` environment will follow
968 the line numbering. \OpTeX/ sets \^`\ttline=-1` by default.
969
970 The indentation of each line in display verbatim is controlled by
971 \^`\ttindent` register. This register is set to the `\parindent` by default.
972 Users can change the values of the `\parindent` and \^`\ttindent` independently.
973
974 The \^`\begtt` command starts the internal group in which the catcodes are changed.
975 The group ends by \^`\endtt`.
976 You can declare settings valid only inside this group at the same line where
977 \^`\begtt` starts. For example:
978
979 \begtt \adef@{\string\endtt}
980 \begtt \adef!{?} \adef?{!}
981 Each occurrence of the exclamation mark will be changed to
982 the question mark and vice versa. Really? You can try it!
983 @
984 \endtt
985 %
986 The \~`\adef` command sets defined character as the given macro.
987
988 You can declare settings valid inside each \^`\begtt`...\^`\endtt` group by
989 the \^`\everytt` register.
990 There are tips for such global \^`\everytt` declarations here:
991
992 \begtt \adef!{\char9251 }
993 \everytt={\typosize[9/11]} % setting font size for verbatim
994 \everytt={\ttline=0} % each listing will be numbered from one
995 \everytt={\visiblesp} % visualization!of!spaces
996 \endtt
997
998 There is an alternative to \^`\everytt` named \^`\everyintt` which is used for
999 all in-line verbatim surrounded by an \^`\verbchar` or processed by the \~`\code`
1000 command.
1001
1002 The in-line verbatim surrounded by a \^`\verbchar` doesn't work in
1003 parameter of macros and macro definitions. (It works in titles declared by
1004 \~`\chap`, \~`\sec` etc. and in \~`\fnote`s, because these macros are
1005 specially defined in \OpTeX/).
1006 \new
1007 You can use more robust command \^`\code{<text>}` in problematic
1008 situations, but you have to escape the following characters in the <text>:
1009 `\`, `#`, `%`, braces (if the braces are unmatched in the <text>),
1010 and space or `^` (if there are more than one subsequent spaces or `^` in
1011 the <text>). Examples:
1012
1013 \begtt
1014 \code{\\text, \%\#} ... prints \text, %#
1015 \code{@{..}*&^$ $} ... prints @{..}*&^$ $ without escaping, but you can
1016 escape these characters too, if you want.
1017 \code{a \ b} ... two spaces between a b, the second must be escaped
1018 \code{xy\{z} ... xy{z ... unbalanced brace must be escaped
1019 \code{^\^M} ... prints ^^M, the second ^ must be escaped
1020 \endtt
1021
1022 You can print verbatim listing from external files by the \^`\verbinput` command.
1023 Examples:
1024
1025 \begtt
1026 \verbinput (12-42) program.c % listing from program.c, only lines 12-42
1027 \verbinput (-60) program.c % print from begin to the line 60
1028 \verbinput (61-) program.c % from line 61 to the end
1029 \verbinput (-) program.c % whole file is printed
1030 \verbinput (70+10) program.c % from line 70, only 10 lines printed
1031 \verbinput (+10) program.c % from the last line read, print 10 lines
1032 \verbinput (-5+7) program.c % from the last line read, skip 5, print 7
1033 \verbinput (+) program.c % from the last line read to the end
1034 \endtt
1035
1036 \new
1037 You can insert additional commands for \^`\verbinput` before
1038 the first opening bracket. They are processed in the local group.
1039 For example, `\verbinput \hsize=20cm (-) program.c`.
1040
1041 The \~`\ttline` influences the line numbering by the same way as in
1042 \~`\begtt``...`\~`\endtt` environment. If \~`\ttline=-1` then real line numbers are
1043 printed (this is the default). If \code{\\ttline<-1} then no line
1044 numbers are printed.
1045
1046 The \^`\verbinput` can be controlled by \^`\everytt`, \^`\ttindent` just like
1047 in \~`\begtt``...`\~`\endtt`.
1048
1049 The \~`\begtt`...\~`\endtt` pair or \~`\verbinput` can be used for listings of
1050 codes. Automatic syntax highlighting is possible, for example
1051 `\begtt` \^`\hisyntax{C}` activates colors for C programs. Or
1052 `\verbinput` \^`\hisyntax{HTML} (-) file.html` can be used for HTML or XML codes.
1053 \OpTeX/ implements syntax highlighting of C, Lua, Python, \TeX/, HTML, XML and more.
1054 For a declaration of a new language, see the section~\ref[hisyntax].
1055
1056 If the code is read by \^`\verbinput` and there are comment lines prefixed
1057 by two characters then
1058 you can set them by \~`\commentchars``<first><second>`. Such comments are
1059 fully interpreted by \TeX/ (i.e. not verbatim).
1060 Section~\ref[verb] (page \pgref[commentchars]) says more about this feature.
1061
1062 \sec Autogenerated lists
1063 %%%%%%%%%%%%%%%%%%%%%%%%
1064
1065 \secc[toc] Table of contents
1066 %%%%%%%%%%%%%%%%%%%%%%
1067
1068 The \^`\maketoc` command prints the table of contents of all \~`\chap`, \~`\sec`
1069 and \~`\secc` used in the document. These data are read from the external `*.ref` file, so
1070 you have to run \TeX/ more than once (typically three times if the table of
1071 contents is at the beginning of the document).
1072
1073 Typically, we don't want to repeat the name of the section \"Table of contents"
1074 in the table of contents again. The direct usage
1075 of \~`\chap` or \~`\sec` isn't recommended here because the table of contents
1076 is typically not referenced to itself. You can print the unnumbered and unreferenced
1077 title of the section like this:
1078
1079 \begtt
1080 \nonum\notoc\sec Table of Contents
1081 \endtt
1082 If you need a customization of the design of the TOC, read the
1083 section~\ref[maketoc].
1084
1085 \new
1086 If you are using a special macro in section or chapter titles
1087 and you need different behavior of such macro in other cases then use
1088 \^`\regmacro{<case-toc>}{<case-mark>}{<case-outline>}`.
1089 The parameters are applied locally in given cases. The \^`\regmacro` can be
1090 used repeatedly: then its parameters are accumulated (for more macros).
1091 If a parameter is empty then original definition is used in given case.
1092 For example:
1093
1094 \begtt
1095 % default value of \mylogo macro used in text and in the titles:
1096 \def\mylogo{\leavevmode\hbox{{\Red\it My}{\setfontsize{mag1.5}\rm Lo}Go}}
1097 % another variants:
1098 \regmacro {\def\mylogo{\hbox{\Red My\Black LoGo}}} % used in TOC
1099 {\def\mylogo{\hbox{{\it My}\/LoGo}}} % used in running heads
1100 {\def\mylogo{MyLoGo}} % used in PDF outlines
1101 \endtt
1102
1103 \secc Making the index
1104 %%%%%%%%%%%%%%%%%%%%%
1105
1106 The index can be included in the document by the \^`\makeindex` macro. No external
1107 program is needed, the alphabetical sorting is done inside \TeX/ at macro
1108 level.
1109
1110 The \^`\ii` command (insert to index) declares the word separated by the space
1111 as the index item. This declaration is represented as an invisible item on the
1112 page connected to the next visible word. The page number of the page where
1113 this item occurs is listed in the index entry. So you can type:
1114
1115 \begtt
1116 The \ii resistor resistor is a passive electrical component ...
1117 \endtt
1118
1119 You don't have to double the word if you use the \^`\iid` instead of \^`\ii`:
1120
1121 \begtt
1122 The \iid resistor is a passive electrical component ...
1123 or:
1124 Now we'll deal with the \iid resistor .
1125 \endtt
1126
1127 Note that the dot or comma has to be separated by space when \^`\iid` is
1128 used. This space (before dot or comma) is removed by the macro in
1129 the current text.
1130
1131 The multiple-words entries are commonly arranged in the index as follows:
1132
1133 \medskip
1134
1135 linear~dependency 11, 40--50
1136
1137 --- independency 12, 42--53
1138
1139 --- space 57, 76
1140
1141 --- subspace 58
1142
1143 \medskip
1144
1145 To do this you have to declare the parts of the index entries by the `/` separator.
1146 Example:
1147
1148 \begtt
1149 {\bf Definition.}
1150 \ii linear/space,vector/space
1151 {\em Linear space} (or {\em vector space}) is a nonempty set of...
1152 \endtt
1153
1154 The number of the parts of one index entry (separated by `/`) is unlimited. Note, that you can
1155 spare your typing by the comma in the \~`\ii` parameter. The previous example
1156 is equivalent to `\ii linear/space \ii vector/space`~.
1157
1158 Maybe you need to propagate to the index the similar entry to the
1159 linear/space in the form of space/linear. You can do this by the shorthand `,@`
1160 at the end of the \~`\ii` parameter. Example:
1161
1162 \begtt
1163 \ii linear/space,vector/space,@
1164 is equivalent to:
1165 \ii linear/space,vector/space \ii space/linear,space/vector
1166 \endtt
1167
1168 If you really need to insert the space into the index entry, write `~`.
1169
1170 The \~`\ii` or \~`\iid` commands can be preceded by \^`\iitype` `<letter>`, then such
1171 reference (or more references generated by one \~`\ii`) has the specified type.
1172 The page numbers of such references should be formatted
1173 specially in the index. \OpTeX/ implements only \^`\iitype` `b`,
1174 \^`\iitype` `i` and \^`\iitype` `u`:
1175 the page number in bold or in italics or underlined is printed
1176 in the index when these types are used. The default index type is empty, which
1177 prints page numbers in normal font. The \TeX/book index is a good example.
1178
1179 The \^`\makeindex` creates the list of alphabetically sorted index entries
1180 without the title of the section and without creating more columns. \OpTeX/
1181 provides other macros \^`\begmulti` and \^`\endmulti` for more columns:
1182
1183 \begtt \catcode`\<=13
1184 \begmulti <number of columns>
1185 <text>
1186 \endmulti
1187 \endtt
1188 The columns will be balanced. The Index can be printed by the following
1189 code:
1190
1191 \begtt
1192 \sec Index
1193 \begmulti 3 \makeindex \endmulti
1194 \endtt
1195
1196 Only \"pure words" can be propagated to the index by the \~`\ii` command. It
1197 means that there cannot be any macro, \TeX/ primitive, etc.
1198 But there is another possibility to create such a complex index entry. Use
1199 \"pure equivalent" in the \~`\ii` parameter and map this equivalent to a
1200 real word that is printed in the index. Such mapping is done by
1201 \^`\iis` command. Example:
1202
1203 \begtt
1204 The \ii chiquadrat $\chi$-quadrat method is ...
1205 If the \ii relax `\relax` command is used then \TeX/ is relaxing.
1206 ...
1207 \iis chiquadrat {$\chi$-quadrat}
1208 \iis relax {\code{\\relax}}
1209 \endtt
1210 %
1211 The \^`\iis` `<equivalent> {<text>}` creates one entry in the \"dictionary
1212 of the exceptions". The sorting is done by the <equivalent> but the
1213 <text> is printed in the index entry list.
1214
1215 The sorting rules when \^`\makeindex` runs depends on the current language.
1216 See section~\ref[lang] about languages selection. The \string< character is sorted
1217 before A and > after Z and these characters aren't printed if they are
1218 first in the index item.
1219
1220
1221 \secc Bib\TeX/ing
1222 %%%%%%%%%%%%%%%%
1223
1224 The command \^`\cite[<label>]` (or
1225 \hbox{\^`\cite[<label-1>,<label-2>,...,<label-n>]`})
1226 creates the citation in the form [42] (or [15,~19,~26]).
1227 If \^`\shortcitations` is declared at the beginning of the document then
1228 continuous sequences of numbers are re-printed like this:
1229 \hbox{[3--5,~7,~9--11]}. If
1230 \^`\sortcitations` is declared then numbers generated by one \^`\cite` command
1231 are sorted upward.
1232
1233 If \^`\nonumcitations` is declared then the marks instead of numbers are generated
1234 depending on the used bib-style. For example, the citations look like
1235 [Now08] or [Nowak, 2008].
1236
1237 The \^`\rcite[<labels>]` creates the same list as \^`\cite[<labels>]` but without
1238 the outer brackets. Example: `[\rcite[tbn], pg.~13]` creates [4,~pg.~13].
1239
1240 The \^`\ecite[<label>]{<text>}` prints the `<text>` only, but the entry labeled
1241 <label> is decided as to be cited. If \~`\hyperlinks` is used then <text>
1242 is linked to the references list.
1243
1244 You can define alternative formatting of \^`\cite` command. Example:
1245
1246 \begtt \catcode`\<=13
1247 \def\cite[#1]{(\rcite[#1])} % \cite[<label>] creates (27)
1248 \def\cite[#1]{$^{\rcite[#1]}$} % \cite[<label>] creates^{27}
1249 \endtt
1250
1251 The numbers printed by \^`\cite` correspond to the same numbers generated in
1252 the list of references. There are two possibilities to generate this
1253 references list:
1254
1255 \begitems
1256 * Manually using \~`\bib[<label>]` commands.
1257 * By \~`\usebib/<type> (<style>) <bib-base>` command which reads `*.bib`
1258 files directly.
1259 \enditems
1260
1261 \new
1262 Note that the other two possibilities documented in OPmac (using external
1263 Bib\TeX/ program) aren't supported because Bib\TeX/ is an old program that does not
1264 support Unicode. And Biber seems to be not compliant with Plain \TeX.
1265
1266 \medskip\noindent
1267 {\bf References created manually using \^`\bib[<label>]` command.}
1268
1269 \begtt
1270 \bib [tbn] P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 1997.
1271 \bib [tst] P. Olšák. {\it Typografický systém \TeX.}
1272 269~s. Praha: CSTUG, 1995.
1273 \endtt
1274
1275 If you are using \~`\nonumcitations` then you need to declare the <marks>
1276 used by \~`\cite` command. To do it you must use long form of the \^`\bib`
1277 command in the format \^`\bib[<label>] = {<mark>}`. The spaces around
1278 equal sign are mandatory. Example:
1279
1280 \begtt
1281 \bib [tbn] = {Olšák, 2001}
1282 P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 2001.
1283 \endtt
1284
1285 \noindent
1286 {\bf Direct reading of `.bib` files} is possible by \^`\usebib` macro.
1287 This macro reads and uses macro package `librarian.tex` by Paul Isambert.
1288 The usage is:
1289
1290 \begtt \catcode`\<=13
1291 \usebib/c (<style>) <bib-base> % sorted by \cite-order (c=cite),
1292 \usebib/s (<style>) <bib-base> % sorted by style (s=style).
1293 % example:
1294 \nocite[*] \usebib/s (simple) op-biblist % prints all from op-biblist.bib
1295 \endtt
1296
1297 The <bib-base> is one or more `*.bib` database source files (separated by
1298 commas and without extension) and the <style> is the part of the filename
1299 `bib-<style>.opm` where the formatting of the references list is
1300 defined. \OpTeX/ supports `simple` or `iso690` styles. The features of
1301 the `iso690` style is documented in the section~\ref[isobib] in detail.
1302 The \^`\usebib` command is more documented in section~\ref[usebib].
1303
1304 Not all records are printed from <bib-base> files: the command \^`\usebib`
1305 selects only such bib-records which were used in \~`\cite` or \^`\nocite`
1306 commands in your document. The \^`\nocite` behaves as \~`\cite` but prints
1307 nothing. It tells only that the mentioned bib-record should be printed in the
1308 reference list. If \^`\nocite[*]` is used then all records from <bib-base>
1309 are printed.
1310
1311 You can create more independent lists of references (you are creating proceedings,
1312 for example). Use \^`\bibpart` `{<name>}` to set the scope where \~`\cite`s
1313 and references list are printed (and interconnected) independent of another
1314 parts of your document. The \~`\cite` labels used in different parts can be
1315 the same and they are not affected. References lists can be created manually
1316 by \^`\bib` or from a database by `\usebib`.
1317 Example:
1318
1319 \begtt \typosize[10/12]
1320 \bibpart {AA}
1321 ...\cite[labelX] ... \cite[labelY] ... % They belong to AA bib-list
1322 \usebib/c (simple) file.bib % generates AA bib-list numbered 1, 2, ...
1323 % \cite prints [1], [2], ... by bib-list AA
1324 \bibpart {BB}
1325 ...\cite[labelZ] ... \cite[labelX] ... % They belong to BB bib-list
1326 \bibnum=0 \usebib/c (simple) my.bib % generates BB bib-list numbered 1, 2, ...
1327 % \cite prints [1], [2], ... by bib-list BB
1328 \endtt
1329 %
1330 By default, \^`\bibpart` is empty. So \~`\cite`s and the references list are connected
1331 using this empty internal name.
1332
1333
1334 \sec Graphics
1335 %%%%%%%%%%%%%
1336
1337 \secc Colors, transparency
1338 %%%%%%%%%%%
1339
1340 \OpTeX/ provides a small number of color selectors:
1341 {\Blue `\Blue`},
1342 {\Red `\Red`},
1343 {\Brown `\Brown`},
1344 {\Green `\Green`},
1345 {\Yellow `\Yellow`},
1346 {\Cyan `\Cyan`},
1347 {\Magenta `\Magenta`},
1348 {`\White`},
1349 {\Grey `\Grey`},
1350 {\LightGrey `\LightGrey`} and
1351 `\Black`. More
1352 such selectors can be defined
1353 by setting four CMYK components (using \^`\setcmykcolor`),
1354 or three RGB components (using \^`\setrgbcolor`)
1355 or one grey component (using \^`\setgreycolor`). For example
1356
1357 \begtt
1358 \def \Orange {\setcmykcolor{0 0.5 1 0}}
1359 \def \Purple {\setrgbcolor{1 0 1}}
1360 \def \DarkGrey {\setgreycolor{.1}}
1361 \endtt
1362
1363 The color selectors work locally in groups like font selectors.
1364
1365 The command \^`\morecolors` reads more definitions of color selectors from
1366 the \LaTeX/ file `x11nam.def`.
1367 There are about 300 color names like
1368 `\DeepPink`, `\Chocolate` etc. If there are numbered variants of the same
1369 name, then the letters B, C, etc. are appended to the name in \OpTeX/. For example
1370 `\Chocolate` is Chocolate1, `\ChocolateB` is Chocolate2 etc.
1371
1372 The basic colors \^`\Blue`, \^`\Red`, \^`\Cyan`, \^`\Yellow` etc.\ are defined
1373 with CMYK components using \^`\setcmykcolor`.
1374 On the other hand, you can define a color with three
1375 RGB components and \^`\morecolors` defines such RGB colors.
1376 By default, the color model isn't converted but only stored to
1377 PDF output for each used color. Thus, there may be a mix of color
1378 models in the PDF output which is not a good idea. You can overcome this
1379 problem by declaration \^`\onlyrgb` or \^`\onlycmyk`. Then only the selected color
1380 model is used for PDF output and if a used color is declared by another color
1381 model then it is converted.
1382 The \^`\onlyrgb` creates colors more bright (usable for computer
1383 presentations). On the other hand, CMYK makes colors more true\fnote
1384 {Printed output is more equal to the monitor preview especially if you are
1385 using ICC profile for your printer.}
1386 for printing.
1387
1388 You can define your color by a linear combination of previously defined colors using
1389 \^`\colordef`. For example:
1390
1391 \begtt
1392 \colordef \myCyan {.3\Green + .5\Blue} % 30 % green, 50 % blue, 20% white
1393 \colordef \DarkBlue {\Blue + .4\Black} % Blue mixed with 40 % of black
1394 \colordef \myGreen{\Cyan+\Yellow} % exact the same as \Green
1395 \colordef \MyColor {.3\Orange+.5\Green+.2\Yellow}
1396 \endtt
1397 %
1398 The linear combination is done in CMYK subtractive color space by default
1399 (RGB colors used in \^`\colordef` argument are converted first).
1400 If the resulting component is greater than 1 then it is truncated to 1.
1401 If a convex linear combination (as in the last example above) is used then it
1402 emulates color behavior on a painter's palette.
1403 You can use \^`\rgbcolordef` instead of \^`\colordef` if you want to mix colors
1404 in the additive RGB color space.
1405 If \^`\onlyrgb` is set then \^`\colordef` works like \^`\rgbcolordef`.
1406
1407 \def\coloron#1#2#3{%
1408 \setbox0=\hbox{#2#3}\leavevmode
1409 \rlap{#1\strut \vrule width\wd0}\box0
1410 }
1411 The following example defines the macro for
1412 \coloron\Yellow\Brown{colored text on colored background}. Usage:
1413 `\coloron<background><foreground>{<text>}`
1414
1415 The `\coloron` macro can be defined as follows:
1416
1417 \begtt
1418 \def\coloron#1#2#3{%
1419 \setbox0=\hbox{#2#3}%
1420 \leavevmode \rlap{#1\strut \vrule width\wd0}\box0
1421 }
1422 \coloron\Yellow\Brown{Brown text on yellow background}
1423 \endtt
1424
1425 The \^`\transparency``<number>` sets the transparency amount of following
1426 typesetting material until the current group is closed.
1427 The <number> must be in the range 0..255,
1428 zero means no transparency (solid objects), 255 means
1429 full transparency (invisible objects). You can see the effect when
1430 overlapping one object over another.
1431
1432
1433 \secc Images
1434 %%%%%%%%%%%
1435
1436 The \^`\inspic` `{<filename>.<extension>}` or
1437 \^`\inspic` `<filename>.<extension><space>`
1438 inserts the picture stored in
1439 the graphics file with the name `<filename>.<extension>` to the document.
1440 You can set the picture width by \^`\picw=<dimen>`
1441 before \^`\inspic` command which declares the width of the picture.
1442 The image files can be in the PNG, JPG, JBIG2 or PDF format.
1443
1444 The \^`\picwidth` is an equivalent register to \^`\picw`. Moreover, there is an
1445 \^`\picheight` register (or \^`\pich` in short)
1446 which denotes the height of the picture. If both
1447 registers are set then the picture will be (probably) deformed.
1448
1449 The image files are searched in \^`\picdir`. This token list is empty
1450 by default, this means that the image files are searched in the
1451 current directory. Example: \^`\picdir={img/}` supposes that image files are
1452 in `img` subdirectory. Note: the directory name must end by `/` in
1453 the \^`\picdir` declaration.
1454 More parameters can be included using the \^`\picparams` token list.
1455
1456 Inkscape\fnote
1457 {A powerful and free Wysiwyg editor for creating vector graphics.}
1458 is able to save a picture to PDF and labels of the picture to another
1459 file\fnote
1460 {Chose \"Omit text in PDF and create LaTeX file" option.}.
1461 This second file should be read by \TeX/to print labels
1462 in the same font as document font. \OpTeX/ supports this feature by
1463 \^`\inkinspic` `{<filename>.pdf}` command. It reads and displays
1464 both: PDF image and labels generated by Inkscape.
1465
1466 If you want to create vector graphics (diagrams, schema, geometry
1467 skicing) then you can do it by Wysiwyg graphics editor (Inkscape, Geogebra for
1468 example), export the result to PDF and include it by \^`\inspic`.
1469 If you want to \"program" such pictures then Tikz package is recommended.
1470 It works in Plain \TeX/ and \OpTeX.
1471
1472 \secc PDF transformations
1473 %%%%%%%%%%%%%%%%%%%%%%%%
1474
1475 All typesetting elements are transformed by linear
1476 transformation given by the current transformation matrix. The
1477 `\pdfsetmatrix` `{<a> <b> <c> <d>}` command makes the internal multiplication
1478 with the current matrix so linear transformations can be composed.
1479 One linear transformation given by the `\pdfsetmatrix` above transforms
1480 the vector $[0,1]$ to [<a>,\,<b>] and $[1,0]$ to [<c>,\,<d>].
1481 The stack-oriented commands `\pdfsave` and `\pdfrestore` gives a possibility of
1482 storing and restoring the current transformation matrix and the position of the current point.
1483 This position has to be the same from \TeX{}'s point of
1484 view as from the transformation point of view when `\pdfrestore` is processed.
1485 Due to this fact the `\pdfsave\rlap{<transformed text>}\pdfrestore`
1486 or something similar is recommended.
1487
1488 \OpTeX/ provides two special transformation macros
1489 \^`\pdfscale` and \^`\pdfrotate`:
1490
1491 \begtt \catcode`\<=13
1492 \pdfscale{<horizontal-factor>}{<vertical-factor>}
1493 \pdfrotate{<angle-in-degrees>}
1494 \endtt
1495
1496 These macros simply call the properly `\pdfsetmatrix` command.
1497
1498 It is known that the composition of transformations is not commutative. It
1499 means that the order is important. You have to read the transformation
1500 matrices from right to left. Example:
1501
1502 \begtt
1503 First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore
1504 % text1 is scaled two times and it is reflected about vertical axis
1505 % and next it is rotated by 30 degrees left.
1506 second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore
1507 % text2 is rotated by 30 degrees left then it is scaled two times
1508 % and reflected about vertical axis.
1509 third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}%
1510 \pdfrestore % first slanted, then rotated by 15.3 degrees right
1511 \endtt
1512 %
1513 \par\nobreak\bigskip\smallskip
1514 This gives the following result.
1515 First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore
1516 second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore
1517 third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}\pdfrestore
1518 \par\nobreak\bigskip\penalty0%\bigskip
1519
1520 You can see that \TeX/ knows nothing about dimensions of transformed material,
1521 it treats it as with a zero dimension object.
1522 \new
1523 The \^`\transformbox{<transformation>}{<text>}`
1524 macro solves the problem. This macro puts the transformed
1525 material into a box with relevant dimensions. The <transformation> parameter
1526 includes one or more transformation commands `\pdfsetmatrix`, `\pdfscale`,
1527 `\pdfrotate` with their parameters. The <text> is transformed text.
1528
1529 Example: \~`\frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}`
1530 creates \frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}.
1531
1532 The \^`\rotbox{<deg>}{<text>}` is shortcut for
1533 \^`\transformbox{\pdfrotate{<deg>}}{<text>}`.
1534
1535 \secc Ovals, circles
1536 %%%%%%%%%%%%%%%%%%%%
1537
1538 \new
1539 The \^`\inoval{<text>}` creates a box like this: \inoval{text}.
1540 Multiline text can be put in an oval by the command \^`\inoval{\vbox{<text>}}`.
1541 Local settings can be set by
1542 \^`\inoval[<settings>]{<text>}` or you can re-declare global settings by
1543 \^`\ovalparams={<settings>}`. The default settings are:
1544
1545 \begtt
1546 \ovalparams={\roundness=2pt % diameter of circles in the corners
1547 \fcolor=\Yellow % color used for filling oval
1548 \lcolor=\Red % line color used in the border
1549 \lwidth=0.5bp % line width in the border
1550 \shadow=N % use a shadow effect
1551 \overlapmargins=N % ignore margins by surrounding text
1552 \hhkern=0pt \vvkern=0pt} % left-righ margin, top-bottom margin
1553 \endtt
1554 The total distance from text to oval boundary is `\hhkern+\roundness` at the left and right
1555 sides and
1556 `\vvkern+\roundness` at the top and bottom sides of the text.
1557
1558 If you need to set a parameters for the <text> (color, size, font etc.),
1559 put such setting right in front of the <text>:
1560 \^`\inoval{<text settings><text>}`.
1561
1562 \new
1563 The \^`\incircle[\ratio=1.8]{<text>}` creates a box like this \incircle[\ratio=1.8]{text}.
1564 The \^`\ratio` parameter means width/height. The usage is analogical like for oval.
1565 The default parameters are
1566
1567 \begtt
1568 \circleparams={\ratio=1 \fcolor=\Yellow \lcolor=\Red \lwidth=0.5bp
1569 \shadow=N \overlapmargins=N \hhkern=2pt \vvkern=2pt}
1570 \endtt
1571
1572 \new
1573 The macros \^`\clipinoval` `<x> <y> <width> <height> {<text>}`
1574 and \^`\clipincircle` (with the same parameters)
1575 print the `<text>` when a clipping path (oval or circle with given
1576 `<with>` and `<height>` shifted its center by `<x>` to right and by `<y>` to up)
1577 is used.
1578 The `\roundness=5mm` is default for \^`\clipinoval` and user can change it.
1579 Example:
1580
1581 \begtt
1582 \clipincircle 3cm 3.5cm 6cm 7cm {\picw=6cm \inspic{myphoto.jpg}}
1583 \endtt
1584
1585 \secc Putting images and texts wherever
1586
1587 \new
1588 The \^`\puttext` `<x> <y> {<text>}` puts the `<text>` shifted by `<x>` right and by
1589 `<y>` up from the current point of typesetting and does not change the
1590 position of the current point. Assume a coordinate system with origin in the
1591 current point. Then \^`\puttext` `<x> <y> {<text>}` puts the text at the
1592 coordinates `<x>`, `<y>`. More exactly the left edge of its baseline is at that
1593 position. The right edge is used if the optional parameter `[r]` is given, see
1594 section~\ref[graphics] for more details.
1595
1596 \new
1597 The \^`\putpic` `<x> <y> <width> <height> {<image-file>}` puts an image
1598 given by `<image-file>` (including extension) of given
1599 `<width>` and `<height>` at given position (its left-bottom corner).
1600 You can write \^`\nospec` instead `<width>` or `<height>` if this parameter
1601 is not specified.
1602
1603 \sec Others
1604 %%%%%%%%%%%
1605
1606 \secc[lang] Using more languages
1607 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1608
1609 \OpTeX/ prepares hyphenation patterns for all languages if such patterns are
1610 available in your \TeX/ system.
1611 \new
1612 Only USenglish patterns (original from Plain \TeX/) are preloaded.
1613 Hyphenation patterns of all other languages are loaded on demand when you first use
1614 the `\<lang-id>lang` command in your document.
1615 For example \^`\delang` for German, \^`\cslang` for
1616 Czech, \^`\pllang` for Polish. The <lang-id> is a shortcut
1617 of the language (mostly from ISO 639-1).
1618 You can list all available languages including their <lang-id>'s by the
1619 \^`\langlist` macro. It prints now:
1620
1621 \medskip
1622 {\typosize[8.5/11.5]\emergencystretch=4em \hbadness=4000
1623 \noindent \langlist
1624 \par}
1625 \medskip
1626
1627 \new
1628 For compatibility with e-plain macros, there is the command
1629 \^`\uselanguage{<language>}`. The parameter <language> is long-form of
1630 language name, i.e.\ \^`\uselanguage{Czech}` works the same as \^`\cslang`.
1631 The \^`\uselanguage` parameter is case insensitive.
1632
1633 For compatibility with \csplain/, there are macros \^`\ehyph`, \^`\chyph`,
1634 \^`\shyph` which are equivalent to \^`\enlang`, \^`\cslang` and \^`\sklang`.
1635
1636 You can switch between language patterns by `\<iso-code>lang` commands mentioned
1637 above. Default is \^`\enlang`.
1638
1639 \OpTeX/ generates three phrases used for captions and titles in technical
1640 articles or books: \"Chapter", \"Table" and \"Figure". These phrases need to be known
1641 in used language and it depends on the previously used language selectors
1642 `\<iso-code>lang`. \OpTeX/ declares these words only for few languages:
1643 \new
1644 Czech, German, Spanish, French, Greek, Italian, Polish, Russian, Slovak, Hebrew
1645 and English, If you need to use these words in other languages or you want to
1646 auto-generate more words in your macros, then you can declare it by
1647 \~`\sdef` or \^`\_langw` commands as shown in section~\ref[langphrases].
1648
1649 The \~`\makeindex` command needs to know the sorting rules used in your language.
1650 \OpTeX/ defines only a few language rules for sorting: Czech,
1651 Slovak and English. How to declare sorting rules for more languages are
1652 described in the section~\ref[makeindex].
1653
1654 If you declare `\<iso-code>quotes`, then the control sequences `\"` and `\'`
1655 should be used like this: `\"<quoted text>"` or `\'<quoted text>'`
1656 (note that the terminating character is the same but it isn't escaped).
1657 This prints language-dependent normal or alternative quotes around
1658 <quoted text>. The language is specified by <iso-code>. \OpTeX/ declares
1659 quotes only for Czech, German, Spanish, French, Greek, Italian, Polish,
1660 Russian, Slovak and English (\^`\csquotes`, \^`\dequotes`, \dots, \^`\enquotes`).
1661 You can simply define your own quotes as shown in section~\ref[langphrases].
1662 The `\"` is used for quotes visually more similar to the `"` character which
1663 can be primary quotes or secondary quotes depending on the language rules.
1664 Maybe you want to alternate the meaning of these two types of quotes. Use
1665 `\<isocode>quotes\altquotes` in such case.
1666
1667 \secc[styles] Pre-defined styles
1668 %%%%%%%%%%%%%%%%%%%%%%%
1669
1670 \OpTeX/ defines three style-declaration macros \~`\report`, \~`\letter` and
1671 \~`\slides`. You can use them at the beginning of your document if you are
1672 preparing these types of documents and you don't need to create your own
1673 macros.
1674
1675 The \^`\report` declaration is intended to create reports. It
1676 sets default font size to 11\,pt and `\parindent` (paragraph indentation) to 1.2\,em.
1677 The `\tit` macro uses smaller font because we assume that \"chapter level"
1678 will be not used in reports. The first page has no page number, but the next pages
1679 are numbered (from number~2). Footnotes are numbered from one in the whole
1680 document. The macro `\author <authors><end-line>` can be used when
1681 \^`\report` is declared. It prints `<authors>` in italics at the center of the
1682 line. You can separate authors by `\nl` to more lines.
1683
1684 The \^`\letter` declaration is intended to create letters.
1685 See the files `op-letter-*.tex` for examples.
1686 The \^`\letter` style sets default
1687 font size to 11\,pt and `\parindent` to 0\,pt. It sets half-line space
1688 between paragraphs. The page numbers are not printed. The \^`\subject` macro
1689 can be used, it prints the word \"Subject:" or \"Věc" (or something else
1690 depending on current language) in bold. Moreover, the \^`\address` macro
1691 can be used when \^`\letter` is declared. The usage of the \^`\address` macro
1692 looks like:
1693
1694 \begtt \catcode`\<=13
1695 \address
1696 <first line of address>
1697 <second line of address>
1698 <etc.>
1699 <empty line>
1700 \endtt
1701
1702 It means that you need not use any special mark at the end of lines: the ends
1703 of lines in the source file are the same as in printed output. The
1704 \^`\address` macro creates `\vtop` with address lines. The width of such
1705 `\vtop` is equal to the widest line used in it. So, you can use
1706 `\hfill\address...` to put the address box to the right side of the
1707 document. Or you can use `<prefixed text>\address...` to put
1708 `<prefixed text>` before the first line of the address.
1709
1710 The \^`\slides` style creates a simple presentation slides. See an example
1711 in the file `op-slides.tex`. Run `optex op-slides.tex` and see the documentation of
1712 \^`\slides` style in the file `op-slides.pdf`.
1713
1714 Analogical declaration macro `\book` is not prepared. Each book needs
1715 individual typographical care. You need to create specific macros for
1716 design.
1717
1718 \secc Loading other macro packages
1719 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1720
1721 You can load more macro packages by `\input{<file-name>}` or by
1722 \^`\load[<file-names>]`. The first case (`\input`) is \TeX/ primitive command, it can be
1723 used in the alternative old syntax `\input <filename><space>` too. The
1724 second case (\^`\load`) allows specifying a comma-separated list of included files.
1725 Moreover, it loads each macro file only once, it sets
1726 temporarily standard category codes during loading and it tries to
1727 load `<filename>.opm` or `<filename>.tex` or `<filename>`, the first occurrence
1728 wins. Example:
1729 \begtt
1730 \load [qrcode, scanbase]
1731 \endtt
1732 %
1733 does `\input qrcode.opm` \,and \,and `\input scanbase.tex`.
1734 It saves local information about the fact that these file names
1735 (`qrcode`, `scanbase`) were loaded, i.e.\ next \^`\load` will skip them.
1736
1737 It is strongly recommended to use the `\load` macro for loading external
1738 macros if you need them. On the other hand, if your source document is structured
1739 to more files (with individual chapters or sections), use simply the `\input` primitive.
1740
1741 The macro packages intended to \OpTeX/ have the name `*.opm`.
1742 The list of packages supported by \OpTeX/ follows. Most of them are directly part of \OpTeX/:
1743 \begitems \typosize[9/11]
1744 * \ulink[https://petr.olsak.net/ftp/olsak/optex/math-doc.pdf]{\tt math.opm}
1745 provides usable features for math typesetting and shows
1746 \ulink[https://petr.olsak.net/ftp/olsak/optex/math-doc.pdf\#ref:pkgtemplate]
1747 {how to create new packages}.
1748 * `qrcode.opm` enables to create QR codes.
1749 * `tikz.opm` does `\input tikz.tex`, i.e.\ loads Ti{\it k\/}Z. It adds \OpTeX/-specific code.
1750 * \ulink[http://petr.olsak.net/ftp/olsak/optex/mte-doc.pdf]{\tt mte.opm}
1751 includes settings for microtypographic extensions (protrusions+expanding fonts).
1752 * `vlna.opm` enables to protect of one-letter prepositions and more things automatically.
1753 * `emoji.opm` defines `\emoji{<name>}` command for colored emoticons.
1754 * \ulink[https://github.com/vlasakm/optex-minim]{\tt minim-mp.opm} enables
1755 `\directmetapost` using \ulink[https://ctan.org/pkg/minim-mp]{\tt minim-mp}
1756 and \ulink[https://ctan.org/pkg/minim]{\tt minim} packages.
1757 * \ulink[https://ctan.org/tex-archive/macros/luatex/generic/pdfextra/pdfextra-doc.pdf]{\tt pdfextra.opm}
1758 allows the use of many extra features from PDF standard (by M. Vlasák).
1759 \enditems
1760 See these files in `optex/pkg/` or `optex/<pkgname>` for more information about
1761 them. The packages may have their documentation, try `texdoc <pkgname>`.
1762
1763 \secc Lorem ipsum dolor sit
1764 %%%%%%%%%%%%%%%%%%%%%%%%%%%
1765
1766 \new
1767 A designer needs to concentrate on the design of the output and maybe he/she
1768 needs material for testing macros. There is the possibility to generate a
1769 neutral text for such experiments. Use \^`\lorem[<number>]` or
1770 \^`\lorem[<from>-<to>]`. It prints a paragraph (or paragraphs) with neutral
1771 text. The numbers <number> or <from>, <to> must be in the range 1 to 150
1772 because there are 150 paragraphs with neutral text prepared for you.
1773 The \^`\lipsum` macro is equivalent to \^`\lorem`. Example: \^`\lipsum[1-150]`
1774 prints all prepared paragraphs.
1775
1776 If the dot follows the argument before closing `]` (for example \^`\lipsum[3.]`
1777 or \^`\lipsum[3.1]`)
1778 then only first sentence from given paragraph is printed.
1779
1780 \secc Logos
1781 %%%%%%%%%%
1782
1783 \new
1784 The control sequences for typical logos can be terminated by optional `/`
1785 which is ignored when printing. This makes logos more legible in the source file:
1786
1787 \begtt
1788 We are using \TeX/ because it is cool. \OpTeX/ is better than \LaTeX.
1789 \endtt
1790
1791 \secc The last page
1792 %%%%%%%%%%%%%%%%%%%
1793
1794 The number of the last page (it may be different from the number of pages) is
1795 expanded by \^`\lastpage` macro. It expands to `?` in first \TeX/ run and to
1796 the last page in next \TeX/ runs.
1797
1798 There is an example for footlines in the format \"current page / last page":
1799
1800 \begtt
1801 \footline={\hss \fixedrm \folio/\lastpage \hss}
1802 \endtt
1803
1804 \new
1805 The \^`\lastpage` expands to the last \^`\folio` which is a decimal
1806 number or Roman numeral (when \^`\pageno` is negative). If you need to know
1807 the total pages used in the document, use \^`\totalpages` macro. It expands to
1808 zero (in first \TeX/ run) or to the number of all pages in the document
1809 (in next \TeX/ runs).
1810
1811 \secc Use \OpTeX/
1812 %%%%%%%%%%%%%%%%%
1813
1814 \new
1815 The command \^`\useOpTeX` (or \^`\useoptex`) does nothing in \OpTeX/ but it causes
1816 an error (undefined control sequence) when another format is used. You can
1817 put it as the first command in your document:
1818
1819 \begtt
1820 \useOpTeX % we are using OpTeX format, no LaTeX :)
1821 \endtt
1822
1823 \secc \OpTeX/ tricks
1824 %%%%%%%%%%%%%%%%%%
1825
1826 The page \ulink[https://petr.olsak.net/optex/optex-tricks.html]{\OpTeX/ tricks}
1827 shows many other features of \OpTeX/. They are of different nature and they
1828 are typically implemented by short chunks of macro code presented at the
1829 page.
1830
1831 Selected macros defined as an \OpTeX/ trick can be used directly from your
1832 document without copying the code chunks into your macros.
1833 It is because these macros are \"registered" in \OpTeX/ (by \^`\_regtrick`
1834 internally) and if you use such a macro then \OpTeX/ automatically loads the
1835 appropriate code chunk from an external file. These macros are listed here. More
1836 information about them are accessible via the external links.
1837
1838 {\typosize[9/11]
1839 \def\oturl{https://petr.olsak.net/optex/optex-tricks.html}
1840 \def\tpg[#1]{\edef\tpgurl{\oturl\##1}}
1841 \def\t#1{\ea\tA\ea{\string#1}\edef\tmp{\csstring#1}\iindex{;\tmp}\dest[cs:\tmp]\sxdef{cs:\tmp}{}}
1842 \def\tA#1{\ea\ulink\ea[\tpgurl]{\tt#1}}
1843
1844 \medskip
1845 \tpg[algol]\t\algol, \t\algolkw, \tpg[algolcap]\t\algolcap, \t\makeLOA, \tpg[algolnum]\t\algolnum\
1846 enables to create pseudocode listings.
1847
1848 \tpg[beglua]\t\beglua, \t\begLUA, \t\logginglua\ writing LUA codes as LUA codes.
1849
1850 \tpg[cancel]\t\cancel\ prints a given text and the line/cross line over the text.
1851
1852 \tpg[clipbox]\t\clipbox\ creates a box of given dimensions with clipped content.
1853
1854 \tpg[colortab]\t\colortab\
1855 colored cells in the table.
1856
1857 \tpg[correctvsize]\t\correctvsize\
1858 sets `\vsize` to fit lines exactly to pages.
1859
1860 \tpg[begfile]\t\createfile, \t\begfile, \t\endfile\
1861 writes a code from the document to the given file.
1862
1863 \tpg[booktabs]\t\crtop, \t\crmid, \t\crbot\
1864 specific design of tables: only horizontal rules with different thickness.
1865
1866 \tpg[colorlin]\t\crx\
1867 alternating colored lines in tables.
1868
1869 \tpg[csvread]\t\csvread\
1870 reads CSV databases and provides other macros for working with their data.
1871
1872 \tpg[csvread]\t\dbitem, \tpg[dbwhere]\t\dbwhere. \tpg[dbloop]\t\dbloop, \t\dbsort,
1873 \tpg[dbcreate]\t\dbcreate, \t\dbinsert, \tpg[dbshow]\t\dbshow. etc.,
1874 works with databases.
1875
1876 \tpg[directchar]\t\directchar\
1877 prints the character directly, bypasses the ligature processing.
1878
1879 \tpg[directoutput]\t\directoutput\
1880 puts boxes to standalone pages adatped to the box dimensions.
1881
1882 \tpg[easylist]\t\easylist\
1883 the depth of list is given by the number of `*`.
1884
1885 \tpg[fullcite]\t\fcread, \t\fullcite\
1886 citations by full bibliographic records.
1887
1888 \tpg[greyblock]\t\framedblocks\
1889 redefines \^`\begblock`, \^`\endblock` to create blocks in frames splittable to pages.
1890
1891 \tpg[ignoreinspic]\t\ignoreinspic\
1892 the \^`\inspic` commands stop loading images, they are replaced by gray frames.
1893
1894 \tpg[import]\t\import\
1895 allows to have subsets of document input files in separate directories.
1896
1897 \tpg[inspicto]\t\inspicto\
1898 behaves like \^`\inspic`, but saves PDF size when image is printed repeatedly.
1899
1900 \tpg[ismatch]\t\ismatch, \t\isinmacro\
1901 tests, if the given string or the macro body includes the given substring.
1902
1903 \tpg[ispageodd]\t\ispageodd\
1904 tests, if the current point is at odd page regardless of asynchronous processing.
1905
1906 \tpg[perpage]\t\incrpp, \t\thepp, \t\thepplast, \t\truepage\
1907 does per-page counting of objects.
1908
1909 \tpg[keystrokes]\t\keystroke\
1910 prints given text in a keystroke-like frame.
1911
1912 \tpg[longtable]\t\longtable\
1913 allows to break a table to more pages and repeats header.
1914
1915 \tpg[lot]\t\makeLOF, \t\makeLOT, \t\captionF, \t\captionT\
1916 create list of tables and list of figures similar to \^`\maketoc`.
1917
1918 \tpg[mathinexpr]\t\mathinexpr\ allows short names `sin(x)`, `log(x)`
1919 instead `math.sin(x)`, `math.log(x)` in \~`\expr` arguments.
1920
1921 \tpg[onlyifnew]\t\onlyifnew\
1922 only define a macro if it is not already defined.
1923
1924 \tpg[pgforeground]\t\pgforeground\
1925 adds material to the foreground of each page.
1926
1927 \tpg[linnum]\t\pstart, \t\pend\
1928 displays line numbers of the marked text in the margin.
1929
1930 \tpg[rebox]\t\rebox\
1931 modifies the vbox: its width will be equal to the wider line.
1932
1933 \tpg[replmacro]\t\replmacro\
1934 enables to patch existing macros using regular expression rules.
1935
1936 \tpg[roundframe]\t\roundframe\
1937 colored frames with rounded corners and many options.
1938
1939 \tpg[runsystem]\t\runsystem\
1940 runs the given external system command.
1941
1942 \tpg[shadedframe]\t\shadedframe\
1943 colored rectangular frames with simple shadows.
1944
1945 \tpg[scaleto]\t\scaleto, \t\scaletof\
1946 text font size changed to the desired width.
1947
1948 \tpg[seccc]\t\seccc, \t\iniseccc\
1949 implements new level of subsubsections.
1950
1951 \tpg[shownodes]\t\shownodes\
1952 prints the list of nodes to the terminal.
1953
1954 \tpg[dayw]\t\sethours, \t\setminutes, \t\setseconds, \t\setweekday\
1955 printing time, date, and day of week.
1956
1957 \tpg[multilist]\ea\ulink\ea[\oturl\#multilist]{\string\style\space m}, \t\keepstyle\
1958 creates lists with items numbered like subsections.
1959
1960 \tpg[tabs]\t\settabs, \t\tabs\
1961 macros emulate tabulators of old typewriters.
1962
1963 \tpg[pglists]\t\showpglists\
1964 shows good organized list of nodes of given pages to the log file.
1965
1966 \tpg[tnodes]\t\tabnodes\
1967 positions of table items are nodes, they can be used for drawing.
1968
1969 \tpg[tdnum]\t\tdnum\
1970 expands to the three-digits-group format of the given number.
1971
1972 \tpg[tnote]\t\tnote\
1973 creates notes for table data printed just after the table.
1974
1975 \tpg[treedata]\t\treedata, \t\tracingtreedata, \tpg[treenodes]\t\treenodes\
1976 \tpg[showtree]\t\showtree, \tpg[jsonread]\t\jsonread,
1977 support tree data structures.
1978
1979 \tpg[ttlineref]\t\ttlineref\
1980 verbatim lines referenced in text.
1981
1982 \tpg[tablevcent]\t\vcent, \t\vbot\
1983 prints paragraphs in tables vertically centered or placed at bottom.
1984
1985 \tpg[thedimen]\t\thedimen\
1986 prints dimen value using selected unit.
1987
1988 \tpg[twoblocks]\t\twoblocks\
1989 allows printing bilingual texts in two columns veritically aligned.
1990
1991 \tpg[verbhyphens]\t\verbhyphens\
1992 setting breakable points for inline verbatim.
1993
1994 \tpg[xparshape]\t\xparshape\
1995 behaves like `\parshape` but its declaration is valid for more paragraphs.
1996
1997 \tpg[xreplstring]\t\xreplstring, \t\ereplstring\
1998 behave like \~`\replstring` but are expandable and add more features.
1999
2000 }
2001
2002 \sec Summary
2003 %%%%%%%%%%%%
2004
2005 \def\ttref#1'{\ea\~\ea`\csname#1\endcsname`}
2006
2007 \begtt \typosize[9/11]\adef&{\kern.25em}\adef~#1'{\ea\~\ea`\csname#1\endcsname`}
2008 ~tit' Title (terminated by end of line)
2009 ~chap' Chapter Title (terminated by end of line)
2010 ~sec' Section Title (terminated by end of line)
2011 ~secc' Subsection Title (terminated by end of line)
2012
2013 ~maketoc' % table of contents generation
2014 ~ii' item1,item2 % insertion the items to the index
2015 ~makeindex' % the index is generated
2016
2017 ~label' [labname] % link target location
2018 ~ref' [labname] % link to the chapter, section, subsection, equation
2019 ~pgref' [labname] % link to the page of the chapter, section, ...
2020
2021 ~caption'/t % a numbered table caption
2022 ~caption'/f % a numbered caption for the picture
2023 ~eqmark' % a numbered equation
2024
2025 ~begitems' % start a list of the items
2026 ~enditems' % end of list of the items
2027 ~begblock' % start a block of text
2028 ~endblock' % end of block of text
2029 ~begtt' % start a verbatim text
2030 ~endtt' % end verbatim text
2031
2032 ~verbchar' X % initialization character X for in-text verbatim
2033 ~code' % another alternative for in-text verbatim
2034 ~verbinput' % verbatim extract from the external file
2035 ~begmulti' num % start multicolumn text (num columns)
2036 ~endmulti' % end multicolumn text
2037
2038 ~cite' [labnames] % refers to the item in the list of references
2039 ~rcite' [labnames] % similar to \cite but [] are not printed.
2040 ~sortcitations' ~shortcitations' ~nonumcitations' % cite format
2041 ~bib' [labname] % an item in the list of references
2042 ~usebib'/? (style) bib-base % direct using of .bib file, ? in {s,c}
2043
2044 ~load' [filenames] % loadaing macro files
2045 ~fontfam' [FamilyName] % selection of font family
2046 ~typosize' [font-size/baselineskip] % size setting of typesetting
2047 ~typoscale' [factor-font/factor-baselineskip] % size scaling
2048 ~thefontsize' [size] ~thefontscale' [factor] % current font size
2049
2050 ~inspic' file.ext % insert a picture, extensions: jpg, png, pdf
2051 ~table' {rule}{data} % macro for the tables like in LaTeX
2052
2053 ~fnote' {text} % footnote (local numbering on each page)
2054 ~mnote' {text} % note in the margin (left or right by page number)
2055
2056 ~hyperlinks' {color-in}{color-out} % PDF links activate as clickable
2057 ~outlines' {level} % PDF will have a table of contents in the left tab
2058 ~magscale'[factor] % resize typesetting, line/page breaking unchanged
2059 ~margins'/pg format (left, right, top, bottom)unit % margins setting
2060 ~report' ~letter' ~slides' % style declaration macros
2061 \endtt
2062
2063 \sec API for macro writers
2064 %%%%%%%%%%%%%%%%%%%%%%%%%%
2065
2066 All \TeX/ primitives and almost all \OpTeX/ macros are accessible by two
2067 names: `\foo` (public or user namespace) and `\_foo` (private name space).
2068 For example `\hbox` and `\_hbox` means the same \TeX/ primitive. More about
2069 it is documented in section~\ref[namespaces].
2070
2071 If this manual refers `\foo` then `\_foo` equivalent exists too. For example,
2072 we mention the `\addto` macro below. The `\_addto` equivalent exists too, but it
2073 is not explicitly mentioned here. If we refer only `\_foo` then its public
2074 equivalent does not exist. For example, we mention the `\_codedecl` macro below, so
2075 this macro is not available as `\codedecl`.
2076
2077 If you are writing a document or macros specific for the document, then use
2078 simply public namespace (`\foo`). If you are writing more general macros,
2079 then you should declare your own namespace
2080 by \~`\_namespace` macro and you have to follow the naming discipline described in
2081 sections~\ref[namespaces] and \ref[pkg-namespace].
2082
2083 The alphabetically sorted list of macros typically usable for macro writers follows.
2084 More information about such macros can be found in the technical documentation.
2085 You can use hyperlinks here in order to go to the appropriate place of the technical
2086 documentation.
2087
2088 \bgroup \medskip \noindent \typosize[9/11]
2089 \^`\addto` `\macro{<text>}` adds <text> at the end of `\macro` body,
2090 \^`\aheadto` `\macro{<text>}` puts <text> at the begin.\nl
2091 \^`\adef` `<char>{<body>}` defines <char> active character with meaning <body>. See also \^`\mathadef`.\nl
2092 \^`\afterfi` `{<text>}<ignored>\fi` expands to `\fi<text>`, see also \^`\afterxfi`.\nl
2093 \^`\basefilename` \^`\currfile` returns the name of the file currently read.\nl
2094 \^`\bp`` {<dimen expression>}` expands \TeX/ dimension to decimal number in `bp` without unit.\nl
2095 \^`\casesof` `<token> <list of cases>` expands to a given case by the given `<token>`.
2096 See also \^`\qcasesof`, \^`\xcasesof`.\nl
2097 \~`\_codedecl`` <sequence> {<info>}` is used at beginning of macro files.\nl
2098 \~`\colordef`` \macro {<mix of colors>}` declares `\macro` as color switch.\nl
2099 \^`\cs` `{<string>}` expands `\<string>`.\nl
2100 \^`\cstochar` `<sequence>` converts <sequence> to <character> if there was `\let<sequence>=<character>`.\nl
2101 \~`\_doc` `...` \~`\_cod` encloses documentation text in the macro code.\nl
2102 \^`\eoldef`` \macro #1{<body>}` defines `\macro` with parameter separated to end of line.\nl
2103 \~`\_endcode` closes the part of macro code in macro files.\nl
2104 \~`\_endnamespace` closes name space declared by \~`\_namespace`.\nl
2105 \~`\eqbox`` [<label>]{<text>}` creates `\hbox{<text>}` with common width across whole document.\nl
2106 \^`\expr`` {<expression>}` expands to result of the <expression> with decimal numbers.\nl
2107 \~`\fontdef`` \f {<font spec.>}` declares `\f` as font switch.\nl
2108 \~`\fontlet` `\fa=\fb <sizespec.>` declares `\fa` as the same font switch
2109 like `\fb` at given <sizespec.>.\nl
2110 \^`\foreach` `<list>\do <parameters>{<what>}` is exapandable loop over <list>.\nl
2111 \^`\foreachdef` `\macro <parameters>{<what>}` declares expandable `\macro` as loop over <list>.\nl
2112 \^`\fornum` `<from>..<to>\do {<what>}` is expanadable loop with numeric variable.\nl
2113 \^`\incr` `<counter>` increases and \^`\decr` `<counter>` decreases `<counter>` by one globally.\nl
2114 \^`\ignoreit` `<one>`, \^`\ignoresecond` `<one><two>` ignores given parameter.\nl
2115 `\expandafter` \^`\ignorept` `\the<dimen>` expands to decimal number <dimen> without `pt`.\nl
2116 \~`\isempty`, \~`\istoksempty`, \~`\isequal`, \~`\ismacro`, \~`\isdefined`, \~`\isinlist`
2117 \~`\isfile`, \~`\isfont` do various tests.\nl
2118 Example: \~`\isinlist\list{<text>}\iftrue` does `\iftrue` if <text> is in `\list`.\nl
2119 \^`\isnextchar`` <char>{<text1>}{<text2>}` performs <text1> if next
2120 character is <char>, else <text2>.\nl
2121 \~`\kv` `{<key>}` expands to a value given by key=value.
2122 See also \~`\trykv`, \~`\iskv`, \~`\readkv`, \~`\kvx`, \~`\nokvx`.\nl
2123 \^`\loop` `...` \^`\repeat` is classical Plain \TeX/ loop.
2124 \^`\xloop` `...\do ...` \^`\repeat` is an extension of \^`\loop`.\nl
2125 \^`\mathstyles`` {<math list>}` enables to create macros dependent on current math style.\nl
2126 \~`\_namespace`` {<pkg>}` declares name space used by package writers.\nl
2127 \^`\newcount`, \^`\newdimen` etc. are classical Plain \TeX/ allocators.\nl
2128 \^`\newif` `\iffoo` declares boolean `\iffoo` as in Plain \TeX/.\nl
2129 \^`\_newifi` `\_iffoo` declares boolean `\_iffoo`.\nl
2130 \^`\nospaceafter``\macro`, \^`\nospaceafter{text}`, \^`\nospacefuturelet`: they ignore the following optional space.\nl
2131 \^`\opinput`` {<filename>}` reads file like `\input` but with standard catcodes.\nl
2132 \^`\optdef`` \macro [<opt-default>] <parameters>{<body>}` defines `\macro` with [opt.parameter].\nl
2133 \^`\opwarning` `{<text>}` prints <text> to the terminal and .log file as warning.\nl
2134 \~`\posx``[<label>]`, \~`\posy``[<label>]`, \~`\pospg``[<label>]`
2135 provide coordinates of absolute position of the \~`\setpos``[<label>]`.
2136 \~`\private`` <sequence> <sequence> ... ;` declares <sequence>s for private name space.\nl
2137 \~`\public`` <sequence> <sequence> ... ;` declares <sequence>s for public name space.\nl
2138 \^`\replstring`` \macro{<stringA>}{<stringB>}` replaces all <stringA> to <stringB> in `\macro`.\nl
2139 \^`\sdef` `{<string>}<parameters>{<body>}` behaves like `\def\<string><parameters>{<body>}`.\nl
2140 \^`\setctable` and \^`\restorectable` manipulate with stack of catcode tables.\nl
2141 \^`\slet` `{<stringA>}{<stringB>}` behaves like `\let\<stringA>=\<stringB>`\nl
2142 \^`\sxdef` `{<string>}<parameters>{<body>}` behaves like `\xdef\<string><parameters>{<body>}`.\nl
2143 \^`\trycs`` {<string>}{<text>}` expands `\<string>` if it is defined else expands <text>.\nl
2144 \^`\useit` `<one>`, \^`\usesecond` `<one><two>` uses given parameter.\nl
2145 \^`\wlog`` {<text>}` writes <text> to .log file.\nl
2146 \^`\wterm`` {<text>}` writes <text> to the terminal and .log file.\nl
2147 \^`\xargs`` <what> <token> <token> ... ;` repeats <what><token> for each <token>.\nl
2148 \unpenalty\unskip \par \egroup
2149
2150 \sec Compatibility with Plain \TeX/
2151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2152
2153 All macros of Plain \TeX/ are re-written in \OpTeX/. Common macros should
2154 work in the same sense as in original Plain \TeX. Internal control sequences
2155 like `\f@@t` are removed and mostly replaced by control sequences
2156 prefixed by `_` (like `\_this`). Only a basic set of old Plain
2157 \TeX/ control sequences like `\p@`, `\z@`, `\dimen@` are provided
2158 but not recommended for new macros.
2159
2160 All primitives and common macros have two
2161 control sequences with the same meaning: in prefixed and unprefixed form.
2162 For example `\hbox` is equal to `\_hbox`.
2163 Internal macros of \OpTeX/ have and use only prefixed form. User should use
2164 unprefixed forms, but prefixed forms are accessible too because the `_` is
2165 set as a letter category code globally (in macro files and users document too). Users
2166 should re-define unprefixed forms of control sequences without worries that
2167 something internal will be broken.
2168
2169 \new
2170 The Latin Modern 8bit fonts instead Computer Modern 7bit fonts are
2171 preloaded in the format, but only a few ones. The full family set is ready to
2172 use after the command \~`\fontfam[LMfonts]` which reads the fonts in OTF
2173 format.
2174
2175 \new
2176 Plain \TeX/ defines `\newcount`, `\bye` etc. as `\outer` macros. \OpTeX/
2177 doesn't set any macro as `\outer`. Macros like `\TeX`, `\rm` are defined as
2178 `\protected`.
2179
2180 \new
2181 The text accents macros `\"`, `\'`, `\v`, `\u`, `\=`, `\^`, `\.`, `\H`,
2182 `\~`, \code{\\`}, `\t` are undefined\fnote
2183 {The math accents macros like `\acute`, `\bar`, `\dot`, `\hat` still work.}
2184 in \OpTeX/. Use real
2185 letters like á, ř, ž in your source document instead of these old accents macros.
2186 If you really want to use them, you can initialize them by the \^`\oldaccents`
2187 command. But we don't recommend it.
2188
2189 \new
2190 The default paper size is not set as the letter with 1\,in margins but as A4 with
2191 2.5\,cm margins. You can change it, for example by
2192 \^`\margins/1 letter (1,1,1,1)in`. This example sets the classical Plain \TeX/
2193 page layout.
2194
2195 \new
2196 The origin for the typographical area is not at the top left 1\,in 1\,in coordinates
2197 but at the top left paper corner exactly. For example, `\hoffset` includes directly left
2198 margin.
2199
2200 The tabbing macros `\settabs` and `\+` (from Plain \TeX/)
2201 are not defined in \OpTeX/ because they are obsolete. But you can use the
2202 \ulink[http://petr.olsak.net/optex/optex-tricks.html\#tabs]{\OpTeX/ trick 0021}
2203 if you really need such feature.
2204
2205 The `\sec` macro is reserved for sections but original Plain \TeX/ declares this
2206 control sequence for math secant\fnote{Use \code{$\\secant(x)$} to get $\secant(x)$.}.
2207
2208 \sec Related documents
2209
2210 \begitems
2211 * \ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf]
2212 {Typesetting math with \OpTeX} --
2213 More details about math typesetting.
2214 * \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]
2215 {\TeX/ in a Nutshell} --
2216 Summary about \TeX/ principles, \TeX/ primitive commands etc.
2217 * \ulink[http://petr.olsak.net/ftp/olsak/optex/op-catalog.pdf]
2218 {\OpTeX/ catalog} --
2219 All fonts collected to `\fontfam` families are shown here.
2220 * \ulink[http://petr.olsak.net/ftp/olsak/optex/omls.pdf]
2221 {OMLS} --
2222 \OpTeX/ Markup Language Standard.
2223 * \ulink[http://petr.olsak.net/optex/optex-tricks.html]
2224 {\OpTeX/ - tips, tricks, howto} --
2225 Tips of macro codes for various purposes.
2226
2227 \enditems
2228
2229 \enddocument
2230
2231
2232 \sec Dependencies
2233 %%%%%%%%%%%%%%%%%
2234
2235 When `optex.fmt` is created then the following must be installed
2236
2237 \begitems
2238 * The `\luatex` program.
2239 * Latin moder font metrics
2240 `ec-lmr10.tfm`, `ec-lmbx10.tfm`, `ec-lmri10.tfm`,
2241 `ec-lmbxi10.tfm`, `ec-lmtt10.tfm` (for basic text font initializing).
2242 * Computer rmodern font metrics
2243 `cmr10.tfm`, `cmmi10.tfm`, `cmsy10.tfm`, `cmex10.tfm` (for basic math
2244 initializing). If there are more Computer Modern fonts then they are read
2245 too.
2246 * The file `hyphen.tex` form plain \TeX.
2247 \enditems
2248
2249 When `\fontfam` is used then the ability of Unicode fonts reading
2250 is initialized using Lua scripts: `ltluatex.lua` (from \LaTeX/ package),
2251 `luaotfload-main.lua` and more 20 similar `.lua` files (from `luaotfload`
2252 package).
2253
2254 When a font family is needed using `\fontfam` then such font family must be
2255 installed in the OTF format otherwise, the `\fontfam` command is ignored
2256 (only warning about no-existent font family is printed).
2257
2258 When `\cslang`, `\delang` etc. commands are used in the document
2259 then the hyphenation patterns of relevant languages must be installed.
2260 Moreover the Lua script `luatex-hyphen.lua` (from `hyph-utf8` package)
2261 and data file `language-dat.lua` (from `hyphen-base` package)
2262 must be installed.
2263
2264 When `\usebib` command is used then `librarian.tex` file
2265 (from the `librarian` macro package) must be installed.
2266
2267 When `\morecolors` command is used then `x11nam.def` file
2268 (from the `xcolor` package) must be installed.
2269
2270 When `\lorem` command is used then `lipsum.ltd.tex` file
2271 (from the `lipsum` package) must be installed.
2272