From 3125499a8c2b497b0f964e23c53d9c9fe3fe4e58 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 19 Apr 2021 21:25:21 +0000 Subject: optex its own format, so directly under tex/ and doc/ git-svn-id: svn://tug.org/texlive/trunk@58918 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/luatex/optex/README | 120 -- Master/texmf-dist/doc/luatex/optex/omls.tex | 832 -------- Master/texmf-dist/doc/luatex/optex/optex-doc.pdf | Bin 1380041 -> 0 bytes Master/texmf-dist/doc/luatex/optex/optex-doc.tex | 114 -- Master/texmf-dist/doc/luatex/optex/optex-math.tex | 1662 ---------------- .../texmf-dist/doc/luatex/optex/optex-techdoc.tex | 290 --- .../texmf-dist/doc/luatex/optex/optex-userdoc.tex | 2019 -------------------- Master/texmf-dist/doc/optex/README | 120 ++ Master/texmf-dist/doc/optex/omls.tex | 832 ++++++++ Master/texmf-dist/doc/optex/optex-doc.pdf | Bin 0 -> 1380041 bytes Master/texmf-dist/doc/optex/optex-doc.tex | 114 ++ Master/texmf-dist/doc/optex/optex-math.tex | 1662 ++++++++++++++++ Master/texmf-dist/doc/optex/optex-techdoc.tex | 290 +++ Master/texmf-dist/doc/optex/optex-userdoc.tex | 2019 ++++++++++++++++++++ 14 files changed, 5037 insertions(+), 5037 deletions(-) delete mode 100644 Master/texmf-dist/doc/luatex/optex/README delete mode 100644 Master/texmf-dist/doc/luatex/optex/omls.tex delete mode 100644 Master/texmf-dist/doc/luatex/optex/optex-doc.pdf delete mode 100644 Master/texmf-dist/doc/luatex/optex/optex-doc.tex delete mode 100644 Master/texmf-dist/doc/luatex/optex/optex-math.tex delete mode 100644 Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex delete mode 100644 Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex create mode 100644 Master/texmf-dist/doc/optex/README create mode 100644 Master/texmf-dist/doc/optex/omls.tex create mode 100644 Master/texmf-dist/doc/optex/optex-doc.pdf create mode 100644 Master/texmf-dist/doc/optex/optex-doc.tex create mode 100644 Master/texmf-dist/doc/optex/optex-math.tex create mode 100644 Master/texmf-dist/doc/optex/optex-techdoc.tex create mode 100644 Master/texmf-dist/doc/optex/optex-userdoc.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/luatex/optex/README b/Master/texmf-dist/doc/luatex/optex/README deleted file mode 100644 index b8f925e47c1..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/README +++ /dev/null @@ -1,120 +0,0 @@ -OpTeX: the LuaTeX format based on Plain TeX and OPmac - -Author: Petr Olsak, - -This software is in public domain. - -See http://petr.olsak.net/optex - -Files: - -base/ ... basic set of macro files used when optex.fmt is generated - and more basic macros loaded on demand during document processing. -demo/ ... examples: short document: op-demo.tex, short letter: op-letter.tex, - presentation slides: op-slides.tex. -pkg/ ... external macros. Maybe, they can be created by other authors if - the macro file conforms to the rules given in the section 2.2.5 - in the OpTeX documentation. -doc/ ... PDF version of the OpTeX documentation and sources. - -History: - -<1.01> Mar. 2021 - Minor code fixes (thanks to reports from users). - LibreCaslon font file added. - two new callbacks from new LuaTeX 1.13 added to optex.lua - active * (in lists) works as normal in math mode. - f-heros(\slides): additional font XITSMath loaded (to the base FiraMath font). - \_xhsize seting added to \margins. -<1.00> Feb. 2021 - The OMLS (OpTeX Markup Language Standard) was developed. It helps to create - convertors from/to OpTeX documents and similar applications. - \pdfunidef re-imeplemted. - \thisoutline introduced. - \verbchar introduced instead \activettchar. - Bugs fixing. -<0.19> Jan. 2021 - emoji support as pkg/emoji.opm. - non-braakable places generated by luavlna, suported as pkg/vlna.opm. - \begblock...\endblock introduced. - comment character allowed after \begtt. - more robust macros: \replstring, \table. - complete revision of documentation, spelling corrections. - Several bugs fixed. -<0.18> Dec. 2020 - Font support for next 9 families added. - Font selection system improved. - Documentation (especially about font selection system) corrected. - Macros supporting key=value included to the format. - \foreach macro improved. - Concept of multilang in bib rewritten. - \opwarning format changed (line numbers are printed too). - Several bugs fixed. -<0.17> Nov. 2020 - optex.lua introduced (instead external ltluatex.lua) - hyph.patterns are loaded directly by \patterns, not using lua code - \commentchars introduced (comments which are able to interrupt verbatim mode) -<0.16> Oct. 2020 - callback.register_x introduced, namespaces for packages corrected - kerkis and EBGaramond fontfiles added - little corrections - optex-math manual: Index added -<0.15> Jun. 2020 - Release for Overleaf - TL2020. - More vertical space above in \chap and \secc. -<0.14> Jun. 2020 - Typeseting Math with OpTeX: new document added. - Math macros corrected. - In-line verbatim in section titles allowed. - \eqbox implemented. - "\mnote up", "\displaylines to" (new features implemented) -<0.13> May 2020 - \table have more features: \tabskip, \table to, \table pxto, \vspan - The \eqalign reimplemented to be more flexible. - The boundary character ":" introduced in the \table. - \| undefined in 8bit math: bug fixed. - \isnextchar: \let\tmp=#1 -> \let\tmp= #1 -<0.12> May 2020 - The external macro qrcode.opm introduced - New directory structure: base/, demo/, pkg/, doc/ introduced. - \load macro introduced - \newif: bug fixed, other bug fixed. -<0.11> Apr. 2020 - \phi, \varpi in Unicode: bug fixed - \mathstyles introduced. -<0.10> Apr. 2020 - Technical documentation added - \_famdecl instedad \_fontdecl in font family files (incompatible change). -<0.09> Syntax highlighting implemented. -<0.08> \numberedpar implmented. \emergencystretch=20pt added as default. - \inoval, \incircle, \clipinoval, \clipincircle imlemented. - \puttext, \putpic x,y instead -y,x (incompatible change!) - footnotes have separated color stack now. - \fnotelinks implemented. - Lists by \begitems...\enditems improved (\novspaces \_vspacehalf, \ilevel). -<0.07> demos: op-letter.tex and op-slides.tex added. - \inkinspic, \transformbox, \slides added. - documentation improved and updated. -<0.06> tables re-implemented, opmac-rest removed. - footnotes, marginal notes reimplemented. - sections.opm, graphics.opm, colors.opm, languages re-implemented - Cite-bib re-implemented. - Index, sorting re-implemented. -<0.05> \boldmath reimplemented - \fontcolor, \letterspacing implemented - font catalogue improved -<0.04> references.opl, hyperlinks.opl re-implemented. - \fontfam, f-* rewritten: no usage of boundary "..." in \_fontnamegen - \fnote{...} corrected: (parameter is not really parameter) - verbatim.opl re-implemented + doc added - file-ref.opl implemented (new \_Xrefversion{3}) - bugfixing -<0.03> optex-doc optex.1 included, - verbatim.opm re-implmented, - math-unicode implemented, - usebib.opm + bib-style.opm included - \catcodetable stack implemented - bugfixing of macros. - catcodes.opl: removed, one can use \catcodetable, ... primitives, - pdfuni-string: lua code for lua5.3 fixed. -<0.02> Released. diff --git a/Master/texmf-dist/doc/luatex/optex/omls.tex b/Master/texmf-dist/doc/luatex/optex/omls.tex deleted file mode 100644 index bcc5749a512..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/omls.tex +++ /dev/null @@ -1,832 +0,0 @@ -\fontfam[lm] - -\adef<#1>{\ifcsname s:#1\endcsname - \link[s:#1]{}{\Blue$\langle$\hbox{\it#1\/}$\rangle$}% - \else {\Blue$\langle$\hbox{\it#1\/}$\rangle$}\fi} -\everyintt={\catcode`<=13 \Red} -\verbchar` -\enlang -\enquotes - -\def\r[#1]{\label[#1]\wlabel{\the\_itemnum}} -\def\:{$\to$} -\let\_narrowlastlinecentered=\ignoreit -\_def\_printsecc#1{\_par - \_abovetitle{\_penalty-200}{\_medskip\_smallskip} - {\_seccfont \_noindent \_raggedright \_printrefnum[@\_quad]% - \_label[\the\_secnum.\the\_seccnum]\wlabel{\the\_secnum.\the\_seccnum}#1\_nbpar}% - \_nobreak \_belowtitle{\_medskip}% - \_firstnoindent -} -\def\.`{\bgroup\catcode`\ =12 \scancs} -\def\scancs#1{\egroup - \immediate\_wref\Xknowncs{\string#1{\the\_secnum.\the\_seccnum}}% - \ea`\string#1% -} -\def\printcs#1{\ea\printcsred\csstring#1;~\ref[#1] \ } -\def\printcsred,#1;{{\Red\tt \bslash#1}} -\def\printknowncs{\ifx\knowncslist\undefined \let\knowncslist=\empty \fi - \ifx\knowncslist\empty TeX me again...\else - \_dosorting\knowncslist \ea\xargs \ea\printcs \knowncslist;\fi} - -\def\~`<#1>`{<#1>\sxdef{s:#1}{}\dest[s:#1]} - -\refdecl{ - \def\knowncslist{}^^J - \def\Xknowncs#1#2{% - \sxdef{,\csstring#1}{#2}% - \global\ea\addto\ea\knowncslist\ea{\csname,\csstring#1\endcsname}% - } -} -\sdef{_item:c}{\pdfsave\llap{\pdfscale{1.3}{1.3}$\circ$\enspace}\pdfrestore} - -%\parindent=15pt \iindent=\parindent \ttindent=\parindent -%\ttindent=0pt -\everylist={\advance\ttindent by-1em} -\hyperlinks \Green \Green -\def\cskip{\par\nobreak} -\def\begblock{\medskip\hbox\bgroup\vrule\vbox\bgroup\hrule\smallskip - \_fnset\leftskip=\parindent \rightskip=\parindent \medskip\noindent} -\def\endblock{\medskip\hrule\egroup\vrule\egroup} - -\def\raggedright{\rightskip=10pt plus1fil\relax} -\def\optexmanual{\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf]{\OpTeX/ manual}} - -\titskip=1cm - -\hfill Version 0.1 - -\tit \OpTeX/ Markup Language Standard - -{\it\hfil Petr Olšák, 2021}\bigskip - -The \OpTeX/ markup language standard (OMLS) declares a list of control -sequences used in \OpTeX/ documents including their syntax and sematic. The -listed control sequences in OMLS in section~\ref[listcs] in table~\ref[alistcs] -are called {\it known} and other control sequences are {\it unknown}. - -The main reason for OMLS is to give instructions on how to program convertors -from \OpTeX/ documents to another formats (Html, Markdown, \LaTeX/) or how -to interpret the \OpTeX/ document sources in such applications as -{\tt texcount} or text editors\fnote -{We suppose advanced editor features: color highlighting, sections/chapters folding, - auto-completions, etc.}. -These converters and applications are called {\it cnv-programs} in this document. - -We suppose that if you need absolute control over the typography of the -document when it is converted to PDF pages, then you use \OpTeX/ itself. If -you need to create other formats of the same document then you can use a -cnv-program which accepts OMLS. The result is a document without -typographical instructions like dimensions of pages, margins, paginations -and headers, selection of a font-family, dimensions of the fonts, etc.\ You can -imagine the result of such a conversion as a single Html page where more -typographical features can be controlled in a different way, for example by -an external CSS file. This is a reason why control sequences like `\fontfam` or -`\margins` are ignored by cnv-programs. - -Obviously, \TeX/ and \OpTeX/ itself gives possibility to declare various -input formats for various purposes. Sometimes (in very special cases) there -exists a good reason to declare a different and special input format by -\TeX/ macros. But if the source of the document respects the OMLS then it is -reasonably transformable to other formats by cnv-programs. We hope that -OMLS-ready documents cover a very large set of typical documents used these -days. - -We suppose that cnv-programs work internally with strings of source lines -without tokenization. This is one of the great differences in processing the -document directly by \OpTeX/ and using a cnv-program. The second difference is -that the expansion process of macros is not implemented in cnv-programs in -its full range. We respect that the result of cnv-programs will be different -than from processing directly by \OpTeX/. But this is not a bug, this is -the feature. We concentrate on the fixed syntax and sematic given by OMLS of the -\OpTeX/ document and we throw behind the head the typographical -exactness of the document which can be done only directly by \TeX/ (and it is -exactly described in \TeX/book, for example). - -\notoc\nonum\sec Table of contents - -\begmulti 2 -\maketoc -\endmulti -\vfil\break - -\sec Syntactical rules - -The syntactical elements are described as strings here. No \TeX/'s tokenization is -taken into account. The rule with a smaller number has precedence. - -\begitems \style n -* end of line or end of file \: \~``.\r[eol] -* `%%:` at beginning of the line \: \~``, see section~\ref[cnv-decl]. -* `` is interpreted specially. -* space or a tab-character \: \~``. -* non-empty sequence of ``s \: \~``.\r[spcs] -* an empty line or a line only with `` \: \~``. -* a character `a`--`z` or `A`--`Z` \: \~``. -* a `` or `_` \: \~``. -* a character different from previous rule or `` or `` \: \~`` -* `\` \: \~``.\r[scs] -* a non-empty sequence of ``s \: \~``. -* `\` \: \~````. -* `%` \: `` and it is completely ignored including ``.\r[com] -* `` at beginning of the line marks that the line as {\it indented}. -* `` at beginning of the line \: are ignored.\r[bspace] -* `` or `` \: ``.\r[eolrm] -* `` \: ``.\r[csspace] -* `` or `` \: \~``.\r[cs] -* `` \: ``.\r[sspace] -* `~` \: non-breakable space. -* text where all pairs `{` and `}` match at arbitrary level \: \~``.\r[balt] -* `{}` can be interpreted as a parameter of a ``, see section~\ref[listcs]. -* The `{` alone not used by previous rule opens a group and the `}` alone closes the same group.\r[group] -* There are two main modes: h-mode, v-mode\fnote - {this is great simplification of real \TeX/ modes.}. - The document processing starts in v-mode. -* In v-mode: a `` character or a control sequence listed - in table~\ref[vtohmode] swithes to h-mode. -* In h-mode: an `` or a control sequence listed in table~\ref[htovmode] switches to v-mode.\r[htov] -* The switching from v-mode to h-mode \: a paragraph begins. -* The switching from h-mode to v-mode \: the current paragraph ends. -* `$$` or `$$$$` \: process `` in math-mode, see section~\ref[math]. -* a non-empty sequence of digits with optional `+` or `-` in the front \: \~``. -* `` with optional dot inside the sequence of digits \: \~``. -* a pair of letters listed in the table~\ref[tex-units] \: \~``. -* optional space, i.e.\ `` or nothing \: \~``. -* `` \: \~``. -* `` not listed in table~\ref[alistcs] nor in configuration \: \~``.\r[unkncs] -* `=` or `` \: \~``. -* `` \: should be completely ignored.\r[eqdim] -* `` \: should be completely ignored. -* `={}` \: should be completely ignored. -* `[]` \: should be completely ignored.\r[ibkt] -* `` \: should be ignored.\r[ignore] -* ``s are processed as described in section~\ref[listcs] or - by a configuration of the cnv-program. -\enditems - -\bigskip -\label[vtohmode]\caption/t -List of control sequences which switch from v-mode to h-mode. -\cskip -\begblock -`\`, -`\hfil`, -`\hfill`, -`\hskip`, -`\hss`, -`\indent`, -`\leavevmode`, -`\noindent`, -`\quad`, -`\qquad`, -`\vrule`. -\endblock - -\bigskip -\label[htovmode]\caption/t -List of control sequences which switch from h-mode to v-mode. -\cskip -\begblock -`\begblock`, -`\begitems`, -`\begmulti`, -`\begtt`, -`\bib`, -`\bigskip`, -`\bye`, -`\caption`, -`\chap`, -`\cskip`, -`\end`, -`\endblock`, -`\enditems`, -`\endmulti` -`\hrule`, -`\medskip`, -`\par`, -`\sec`, -`\secc`, -`\secl`, -`\smallskip`, -`\vfil`, -`\vskip`. -\endblock - -\bigskip -\label[tex-units]\caption/t -List of \TeX/ units. -\cskip -\begblock -`bp`, -`cc`, -`cm`, -`dd`, -`em`, -`ex`, -`in`, -`mm`, -`pc`, -`pt`, -`sp`. -\endblock - -\nonum\secc Examples - -\begitems -* `\%` is `` by rules \ref[scs], \ref[cs]. It does not start - comment, because rule \ref[scs] has precedence before rule \ref[com]. -* `\%`: the `` is kept, but `\foo`: the space is removed - by rule~\ref[csspace]. -* `wordAwordB` is `wordAwordB` by rules~\ref[bspace], - \ref[eolrm], and~\ref[sspace]. -* `\kern-3pt` should be ignored, because `\kern` is `` and rule - \ref[eqdim] is applied. -* `\vskip42mm` should finalize paragraph in h-mode by rule~\ref[htov] and then it - is ignored by rule~\ref[eqdim] because `\vskip` is - `` not listed in table~\ref[alistcs]. -* `\typosize[12/16]` is ignored by rule~\ref[ibkt]. -* `\foo{text}` is `{text}` (i.e. `text` in a group) by rules~\ref[ignore] and~\ref[group]. -\enditems - -\sec Scanning parameters - -If a control sequence listed in rules above or in the section~\ref[listcs] -has a parameter, the parameter is scanned -as a string with interpretation only those rules which are needed to -determine the boundary of the parameters. For example `\tit <eol>` -applies only rule~\ref[eol] during scanning the parameter, i.e.\ `<title>` -is a string telemetered by the end of the line or the end of the file. -Or `\fnote{<balanced-text>}` applies only rule~\ref[balt]. - -If the parameter is in the format `{<something>}` then the `<something>` is -always meant as `<balanced-text>`. We don't specify the type `<balanced-text>` -explicitly here, so we refer to `\fnote{<text>}` and not -`\fnote{<balanced-text>}`, for example. - -The spaces before the scanned parameter are optional -and they are ignored. Spaces inside `{`...`}` are not ignored. - -If the parameter is in the format `{<something>}` and the first non-space -character is not `{` then the parameter is this first non-space character or -a `<control-sequence>` if the first non-space character is~`\`. For example -`\fnote a` is equal to `\fnote{a}`. The difference from this rule is given -for `\input`, `\verbinput`,`\inspic` and `\inkinspic` control sequences in -section~\ref[listcs]. - -If the parameter is scanned as a string already then -all syntactical rules are applied when it is used. For example: -\begtt -\tit This is a title -\endtt -the parameter is scanned as `This is a title` and the rules~\ref[spcs] -and~\ref[sspace] are applied when it is used. - - -\sec Declaration and text parts of the document - -A typical \OpTeX/ document has two parts. A declaration part, where -macros are defined by `\def` and friends, fonts and sizes are declared, etc. -This part should be ignored by cnv-programs. -The second part includes the document text with a markup using well-declared control -sequences. The cnv-program has to interpret the second part. - -So, the cnv-program starts in declaration-skipping mode and it switches to -the text mode later. - -When cnv-program is in declaration-skipping mode then all indented lines are -ignored. And lines which begins by `}` or by a <control-sequence> not listed -in table~\ref[textopen] are ignored too. - -If the line begins by a character other than `}` or by a <control-sequence> -listed in table~\ref[textopen] then cnv-program switches to text mode. All -texts are interpreted from this line including this one. - -User can say explicitly where the second part of the document starts by -`%%:text` given at beginning of a line. Moreover, if `%%:decl` is given at -beginning of a line, then all text between `%%:decl` and `%%:text` is -ignored, only other possible `<cnv-declarator>`s are processed here. -It means that the declaration part and the text part of the document can be -simply determined by the pair `%%:decl` and `%%:text`. - -\bigskip -\label[textopen]\caption/t -List of control sequences which start the text mode. -\cskip -\begblock \raggedright -`\address`, -`\begblock`, -`\begitems`, -`\begmulti`, -`\begtt`, -`\bf`, -`\bi`, -`\bib`, -`\caption`, -`\cite`, -`\clipinoval`, -`\clipincircle`, -`\ecite`, -`\fnote`, -`\frame`, -`\hfil`, -`\hfill`, -`\ii`, -`\iid`, -`\incircle`, -`\inkinspic`, -`\inoval`, -`\inspic`, -`\it`, -`\LaTeX`, -`\LuaTeX`, -`\maketoc`, -`\mnote`, -`\OpTeX`, -`\putpic`, -`\puttext`, -`\rcite`, -`\rm`, -`\rotbox`, -`\sec`, -`\secc`, -`\secl`, -`\table`, -`\TeX`, -`\tit`, -`\usebib`, -`\verbinput`. -\endblock - - -\sec[cnv-decl] The `%%:` declarators - -The `%%:` declarators are ignored when the document is processed by \TeX/ -but they can give instructions to cnv-programs. The `%%:` must be placed at -beginning of the line. The list of `%%:` declarators follows: - -\begitems -* `%%:decl` -- the following text is ignored until `%%:text` occurs. Only - other `%%:` declarators are interpreted. -* `%%:text` -- the following text must be interpreted in text mode. -* `%%:to <format> <config-file>` -- if the cnv-program converts to the - <format> then it has to use the <config-file>. For example: - \begtt - %%:to html html-mydocument.cfg - %%:to markdown markdown-mydocument.cfg - %%:to latex preamble-mydocument.cfg - \endtt - The language of the config files are not a part of this standard, we - suppose something to be natural for used cnv-program. The config file should - give additional rules for interpreting control sequences not listed in the - section~\ref[listcs] (see rule~\ref[unkncs]). For example a tool for - defining a behavior of unknown control sequences can be here. - These definitions can depend on the converted document and on the output - format and they can be given in the configuration files. -* `%%:app <application> <config-file>` -- behaves like `%%;to` but the - cnv-program name instead output format is given here. -* `%%:do <format-or-app> <action>` -- does an `<action>` if `<format-or-app>` - is output format or used cnv\hbox{-}program name. The `<action>` syntax depends - on used cnv-program and it typicaly does a change in its configuration or - give a command to it. -* `%%:skip <formats-or-apps>` -- ignores all following lines until another `%%:` occurs - if the output format or application name is included in the `<formats-or-apps>` - space-separated list. Example: - \begtt - %%:skip html markdown - This text is not interpreted when Html or Markdown output is generated. - %%: - \endtt - If the `<formats-or-apps>` is empty then the `%%:skip` is applied for - each cnv-program and for each output. -* `%%:if <formats-or-apps>` -- processes following lines until another `%%:` - only if the output format or application name is included in the - `<formats-or-apps>` space-separated list. Other cnv-programs or output formats - not mentioned here skip these lines. Note that \TeX/ processes such lines always. - But you can use `\ignoreit{<text>}` which is processed as - `{<text>}` by cnv-programs (see rule~\ref[ignore]) but it is ignored by \OpTeX. - Example: - \begtt - %%:if html latex - \ignoreit{\input{file.tex}} - %%: - \endtt - The `file.tex` in this example is processed only if \LaTeX/ or Html output is generated. -* `%%:use` -- the next single line is fully interpreted unless cnv-program ignores - declarations by `%%:decl` or because it is in declaration-skipping mode. - Example: - \begtt - %%:use - \verbchar` \picdir={img/} - \endtt - The example shows how cnv-program is able to read `\verbchar` or - `\picdir` settings in the declaration\hbox{-}skipping mode although these control - sequences are not listed in table~\ref[textopen]. -* `%%:quotes <qql> <qqr> <ql> <qr>` -- declares \~`<qql>` and \~`<qqr>` (left - and right double quotation marks), \~`<ql>` and \~`<qr>` (left and right single - quotation mark). They are used when `\"` or `\'` control sequences are - processed. Default: unset, i.e.\ `\"` and `\'` are interpreted as - unknown control sequences. -\enditems - - -\sec[listcs] List of known control sequences - -The phrase \"should be" is used very often when the interpretation of -control sequences is declared here. It means that this is only a common -interpretation, but differences are possible due to the type of the output -format and used cnv-program. For example, when we convert to \LaTeX\, then -`\-` and `\/` are not ignored but they are re-written without change to the -output of the \LaTeX/ source file. - -\bigskip -\label[alistcs] -\caption/t List of known control sequences alphabeticaly sorted. -\cskip -\begblock -\raggedright \printknowncs -\endblock - - -\secc Character-like control sequences - -\begitems -* \.`\%`, \.`\$`, \.`\&`,\.`\#` respectively \: should be normal characters - `%`, `$`, `&`, `#` respectively. -* \.`\bslash` \: normal character `\`. -* \.`\space`, `\<space>`, `\<eol>` \: space. -* `\,` \: should be small space or space. -* \.`\quad`, \.`\qquad` \: should be bigger space or more spaces. -* \.`\-`, \.`\/` \: should be ignored. -* \.`\"<text>"` or \.`\'<text>'` \: `<qql><text><qqr>` or `<ql><text><qr>`, - only if `%%:quotes` are set. -\enditems - -\secc Input files - -\begitems -* \.`\input {<file-name>}` or `\input <file-name><space>` should redirect the - input to given file. At the end of the input-ed file or at \.`\endinput` the - reading of the current file continues. The file is read from the current - directory, but the <file-name> should include the full path to the file - or relative path starting from the current directory. First, the file - `<file-name>.tex` is tried to read and if it doesn't exist then - the file `<file-name>` is read. -* \.`\picdir <o-equal>{<text>}` saves `<text>` to `<picdir-value>`. By - default, `<picdir-value>` is empty. -* \.`\inspic {<file-name>}` or `\inspic <file-name><space>` should include the - given picture from the `<picdir-value><file-name>`. -* \.`\inkinspic {<file-name>}` or `\inkinspic <file-name><space>` behaves like - `\inspic`. -* \.`\verinput <ignore> (<lines>) <file-name><space>` should include the - <file-name> (only given lines) as a verbatim text, i.\,e. without any - syntactical interpretation. -* \.`\usebib/<letter> (<style>) <file-names>` should use files from - `<file-names>` to generate the list of bib references. The `<file-names>` - is comma separated list (the `.bib` extension is appended to - each such file name). Only cited bib records should be used in this - bib-references, i.e. their label must be used in a `\cite[<labels>]` or - `\rcite[<labels>]` or `\ecite[<label>]`. - What bib fields are used in bib records depends on the cnv-program and - on its configuration. Maybe, simple cnv-programs should generate nothing here. -\enditems - -\secc Titles - -\begitems -* \.`\tit <title><eof>` should be a title of the document. -* \.`\chap <title><eof>` or `\chap [<label>] <title><eof>` is the title of - first level. -* \.`\sec <title><eof>` or `\sec [<label>] <title><eof>` is the title of - second level. -* \.`\secc <title><eof>` or `\secc [<label>] <title><eof>` is the title of - third level. -* \.`\secl<level> <title><eof>` is the title of given level. -\enditems - -\secc Fonts - -\.`\rm` selects upright normal font (it is selected by default), \.`\it` selects -italic, \.`\bf` selects upright bold font, \.`\bi` selects bold italic and -\.`\tt` selects a monospaced font, \.`\em` select italic (if upright is current) or upright -(if italic is current). The font sizes or other font features are typically ignored -by cnv-programs. The actual font selection is closed at the end of the current group. -The groups are given: -\begitems -* explicitly by `{` and `}` characters (which are not delimiters of - parameters of known control sequences), -* implicitly: parameters of control sequences listed in table~\ref[groupcs] - are processed in a group and blocks of text enclosed by - `\begitems`...`\enditems`, `\begblock`...`\endblock`, `\begmulti`...`\endmulti` - are processed in a group. - Each item in `\table` is in a group. -\enditems - -\label[groupcs] -\caption/t Parameters of following control sequences are processed in a group. -\cskip -\begblock -`\caption`, -`\chap`, -`\fnote`, -`\mnote`, -`\sec`, -`\secc`, -`\tit`. -\endblock - -\secc Colors - -\.`\Red`, \.`\Green`, \.`\Blue`, \.`\Cyan`, \.`\Magenta`, \.`\Yellow`, \.`\White`, -\.`\Black`, and \.`\Brown` should select the given color of the font. The selection -is closed at the end of the current group (like font selectors). - -\secc Blockquotes - -The blockquote\fnote -{The terminology is borrowed from Markdown.} -is opened by \.`\begblock` and closed by \.`\endblock`. -Blockquotes can contain multiple paragraphs and can contain nested -blockquotes. - -\secc Lists - -The list is opened by \.`\begitems` and closed by \.`\enditems`. The `*` starts -a new item in this environment. Nested lists are allowed. - -The type of items (ordered/unordered) -is given by \.`\style <character>`, see section 1.4.5 in the -\optexmanual. Default type is unordered (bullets are used). - - -\secc Code blocks (verbatim texts) - -Code blocks are inline verbatim or display verbatim. - -\begitems -* \.`\begtt <ignored><eol><text>\endtt<ignored><eol>` processes `<text>` in - \"display verbatim mode", i.\,e. there are no special characters, each character - is processed without special interpretation, the <eol>s are end of lines. - The text at the same line after `\begtt` and after `\endtt` (if any) is - ignored. -* \.`\verbchar <character>` declares `<verbchar>`. By default, it is undeclared.\nl - New `\verbchar <character>` rewrites previous setting. The setting is - local in the group. -* Inline verbatim is enclosed in the pairs of `<verbchar>`s. - The text between two `<verbchar>`s is processed without special interpretation. - Only possibly <eol>s are replaced by space. - Example: - \begtt - %%:use - \verbchar` - Now, `$this %text ~\` is processed as inline verbatim. - \endtt - gives: Now, `$this %text ~\` is processed as inline verbatim. -* \.`\code{<text>}` processes `<text>` like inline verbatim, but - all `\<character>` are processed as `<character>`, specially `\{` and `\}` - are `{` and `}` but without taking them into `<balanced-text>` rule, - `\\` is `\` but do not create a `<control-sequence>`, etc. -\enditems - - -\secc Multicolumns - -\.`\begmulti <number><space>` opens the group and \.`\endmulti` -closes the group. If output format allows multi-columns then -the text enclosed between `\begmulti <number><space>` and matching -`\endmulti` should be printed in `<number>` balanced columns. - - -\secc Links - -\begitems -* \.`\url{<text>}` creates `<text>` as an external link which points to `<text>`. - The `\<character>` is interpreted as `<character>` in `<text>` with one - exception: `\|` is ignored. -* \.`\ulink[<url>]{<text>}` creates `<text>` as an external link which points - to `<url>`. The `\<character>` is interpreted as `<character>` only in - `<url>` parameter. -* \.`\label[<label>]` sets the `<label>`. First following occurence of `\chap`, `\sec`, - `\secc`, `\caption` or `\eqmark` sets this `<label>` as bounded to its - position in the document. -* \.`\ref[<label>]` should create an internal link to the position given by - `\chap`, `\sec`, `\secc`, `\caption` or `\eqmark`, - if `[<label>]` is used as the parameter of this control sequence - else if `<label>` is bounded here by previous `\label[<label>]` - The visual aspect of the link - is not declared by OMLS because we don't suppose that the chapters, - sections, equations, etc.\ are automatically numbered by exactly the same way as in - \OpTeX/. A recommendation should be: create a simple sequence of numbers over - all internal links. -* \.`\pgref[<label>]` should be replaced by `??` if cnv-program generates single-page - output (like Html, Markdown). Unfortunately, we get the irrelevant phrases in the output: - \"{\tt The problem is shown at the page ??}". - Users can declare `%%:skip` for such cases. -* \.`\bib[<label>]` or `\bib[<label>]<o-space>=<o-space>{<ignored>}` should open the new bib - record. More exactly, it closes previous paragraph (if h-mode is current) - and opens new h-mode. Then prints an auto-generated reference number in - `[...]`. Following text is interpreted as a bib record until the h-mode ends. -* \.`\cite[<labels>]` should create internal links to corresponding bib - records generated by `\usebib` or by `\bib`. The `<labels>` is a comma-separated list - of labels used in `.bib` files or in `\bib` commands to indicate - the corresponding bib record. The labels should be replaced by auto-generated - reference numbers used in bib records. All reference numbers created by - single `\cite` should be enclosed by single `[...]`. These numbers are - internal links. If the cnv-program does not implement this complicated - bib machinery then `\cite[<labels>]` should print only `[<labels>]`. -* \.`\rcite[<labels>]` does the same as `\cite[<labels>]` but doesn't print - outer `[...]`. -* \.`\ecite[<label>]{<text>}` creates the link to corresponding bib record, - `<text>` is is hyperlinked (no the auto-generated reference number). -* \.`\maketoc` should create a list of titles from all `\chap`, `\sec` and `\secc` - used in the document if they are not preceded by \.`\notoc`. All lines in - this list should include internal links to the position where the corresponding title - is used. -\enditems - -\secc Tables - -\begitems -* \.`\caption/<letter>` opens a caption. More exactly, if current mode is - h-mode, then switch to v-mode first (i.e.\ close the current paragraph). - Then switch from v-mode to h-mode and put a <caption-head>. The following - text should be interpreted as the caption text until h-mode ends. - If <letter> is `t` then <caption-head> is `Table` followed - by an auto-generated number. If the <letter> is `f` then <caption-head> is - `Figure` followed by an auto-generated number. The configuration of - cnv-programs shoud allow different words than default `Table` or `Figure` (for - example, if another language is used). -* \.`\table<ignored>{<declaration>}{<data>}` should create a table. The fidelity - rate of created output depends heavily on the used cnv-program and the output - format. We don't suppose that all aspects of \OpTeX/ tables are implemented. - The following features are listed in their priority of implementation. - \begitems \style c - * Items in `<data>` are separated by `&`. - The last item in each row is separated by end-row separator: \.`\cr`, \.`\crl`, \.`\crll`, - \.`\crli`, \.`\crlli`, or \.`\crlp{<list>}`. If there are $n$ columns in - the table then we have $n-1$ `&` separators and one end-row separator - for each table row. - There can be an optional end-row separator at the first item in `<data>` and - it should be ignored. The `<data>` can end without the end-row separator, it - should be added here. - * Spaces around `&` and before end-row separator are ignored. - * \.`\noalign{<text>}` and \.`\tskip <dimen>` should be ignored. - * Colum declarators in <declaration> should be interpreted: `l` (left aligned), `c` (center - aligned), `r` (right aligned) or `p{<ignored>}` (paragraph-like item). - * The `<number><letter>` or `<number>{<text>}` should be interpreted as - `<number>`-times repeated `<letter>` or `<text>` in `<declaration>`. - * \.`\vspan<decimal-number>{<text>}` should be an item with only `<text>`. - * \.`\mspan<number>[<decl>]{<text>}` should create `<text>` as an item which - spans over `<number>` columns. It is used instead `<number>` real - items, i.e.\ `<number>`$-1$ separators `&` aren't used here. - * Rules in the table should be interpreted, i.e. `|` in <declaration> - should be not ignored and - various end-row separators should be distinguished (see \optexmanual, - section 1.4.6). - * The aligning of `p{<p-data>}` columns should be interpreded by reading - \.`\fL`, \.`\fR`, \.`\fC`, \.`\fS` and \.`\fX` control sequences in `<p-data>`. - See \optexmanual, section 1.4.6. - \enditems -\enditems - -\secc Footnotes, marginal notes - -\begitems -* \.`\fnote{<text>}` should create a footnote link as an auto-generated - reference number. - The `<text>` should be appended at the end of the document labeled by this - reference number. Another alternative (for Html output, for example): the mouse over - the reference number riases an auto-popup `<text>`. -* \.`\fnotemark<number>` should create a pointer to a next declared - footnote as auto-generated reference number. The `<text>` of the footnote is - declared after that by \.`\fnotetext{<text>}`. Exact behavior: if the - reference number of the last processed `\fnote` is $n$ then - `\fnotemark<number>` uses the value - $n+{}$`<number>` as its reference number. A set of `\fnotemark`s - is followed by an equally large set of `\fnotetext{<text>}`. First one - have reference number $n+1$, second $n+2$, etc. When whole set of `\fnotetext{<text>}` - is processed then $n$ is reset to the last reference number used here. -* \.`\mnote <ignored>{<text>}` should be created as auto-popup `<text>` or the `<text>` - is inserted at the margin. -\enditems - -\secc Tagging for index - -We don't suppose that the cnv-program can generate the alphabetically sorted -index. So, the markup for creating the index should be ignored: - -\begitems -* \.`\ii <word><space>` (where `<word>` is a sequence of non-space characters) - should be ignored. -* \.`\iid <word><space>` is `<word><space>` by default, but - if `,` or `.` follows after `<space>` then the `<space>` is removed. -\enditems - -\secc Logos - -\.`\TeX`, \.`\LuaTeX`, \.`\OpTeX`, \.`\LaTeX`, respectively \: -`TeX`, `LuaTeX`, `OpTeX`, `LaTeX`, respectively. If `/` follows -these control sequences then it is ignored. Other logos should be declared -in the configuration of the cnv-program. - -\secc What should be ignored - -\begitems -* \.`\def<text>{<text>}` and other variants with \.`\gdef`, \.`\edef`, \.`\xdef`. - Reason: user can insert a special definition in the `%%:text` part of the - document in order to solve a problem. But cnv-program should ignore~it. -* \.`\outlines{<text>}`, \.`\insertoutline{<text>}` and \.`\thisoutline{<text>}`. -\enditems - - -\sec[math] Math mode processing - -There are two math modes, inline: `$<formula>$` or display: `$$<formula>$$`. -We suppose that `<formula>` will be processed by MathJax or similar -software. So, the `<formula>` should be kept without changes in cnv-program -output, but there are exceptions: - -\begitems -* `$<sign><decimal-number>$` should be transformed to non-math text - `<sign><decimal-number>`. The `<sign>` is~`+` or~`-` or nothing. - The `<decimal-number>` can include `,` (comma) instead `.` (period). - If the `<sign>` is~`-` (character U+002D) then - it must be converted to `−` (character U+2212, math minus). -* `{\bbchar <text>}` should be converted to `\mathbb{<text>}`, because - MathJax doesn't understand `\bbchar`. `$\bbchar <text>$` should be - converted to `$\mathbb{<text>}$`. -* `{\frak <text>}` or `$\frak <text>$` \: - `\mathfrak{<text>}` or `$\mathfrak{<text>}$`. -* `{\script <text>}` or `$\script <text>$` \: - `\mathscr{<text>}` or `$\mathscr{<text>}$`. -* `\eqmark`, `\eqmark[<label>]` \: `\leqno (<num>)`, where `<num>` is - auto-generated number. Or it should be completely ignored. -* It is strongly recommended to allow users to declare another replacement - rules over `<formula>` in configuration files of cnv-programs. -\enditems - - -\sec Notes on various conversions - -The cnv-programs behave differently because output formats have different -concepts and are intended for different purposes. The following sections -mention the main differences for typical conversions. - -\secc To Html - -The Html document is one single page. If we want to split the document to more -pages, then we can use `%%:do html <action>` in positions where the document -should be split (the syntax of `<action>` depends on the used cnv-program.) - -The design of Html pages should be declared by CSS files. - -Pictures inserted by `\inspic` should be inserted into the Html page as -\code{<img src="...">}, so the picture files must be installed in -the webserver to render the Html page correctly in a web browser. - -The `\maketoc` used in the \OpTeX/ document means that the Table of contents should -be here. It should be generated by the cnv-program, two-pass processing is -needed because the cnv-program needs to read all titles of `\chap`, `\sec` and -`\secc`. Another approach is to read the `.ref` file produced by \OpTeX/. - - -\secc To Markdown - -Markdown source file is \"one-page document" too. The principles a -re similar to conversion to Html. - -\secc From Markdown - -The cnv-program which does such a reverse conversion should be very useful for -people they prefer even clearer markup than in \OpTeX/. - -\secc To \LaTeX - -\LaTeX/ gives the same main feature as \OpTeX/: it can generate PDF -output from a source file. But different macros, a different concept, and -a different markup are used. - -The main reason for such conversion is that journal editors -require \LaTeX/ source file, but user want to prepare their real document in -more comfortable (\OpTeX/) markup and with more simple macros. - -This conversion should keep almost all features. For example, the -`\pgref[<label>]` is converted to `\pageref{<label>}`. The cnv-program -needs not to generate a Table of contents, bibliography references, etc. Only -appropriate \LaTeX/ markup must be used. - -The contents of generated \LaTeX/ preamble should be configurable. - - -\secc From \LaTeX - -The reverse conversion from \LaTeX/ to \OpTeX/ can be usable -for people, they want to switch to creating their documents in \OpTeX/. - -The cnv-program must solve additional problem in this type of conversion. -There are various math \LaTeX/ environments, they must be converted to -plain~\TeX/ syntax of math typesetting. For example:\nl -`\begin{array}...\end{array}` \: `\matrix{...}`,\nl -`\begin{align*}...\end{align*}` \: `$$\eqalign{...}$$`\nl -`\frac{...}{...}` \: `{...\over...}`. - -\bye diff --git a/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf b/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf deleted file mode 100644 index a4df4f013ab..00000000000 Binary files a/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/luatex/optex/optex-doc.tex b/Master/texmf-dist/doc/luatex/optex/optex-doc.tex deleted file mode 100644 index 9f2fadeeb4a..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/optex-doc.tex +++ /dev/null @@ -1,114 +0,0 @@ -%% This is part of the OpTeX project, see http://petr.olsak.net/optex - -% Run optex optex-doc -% (three times) to generate OpTeX documentation including references and the index. - -\load [doc.opm] \let\enddocument=\endinput - -\typosize[10/12] % Main size (used in techdoc) - -\begingroup \typosize [11/13.5] % Different size used in useroc. - -\insertoutline{OpTeX} % PDF outlines generated from TOC - -% Title: - -\vglue1cm -\centerline{\setfontsize{at50pt}\rm\OpTeX} -\vskip-8mm - -\tit Format Based on Plain \TeX/ and OPmac\fnotemark1 -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\hfill Version 1.01 - -\centerline{\it Petr Olšák, 2020, 2021} - -\bigskip -\centerline{\url{http://petr.olsak.net/optex}} - -\fnotetext {OPmac package is a set of simple additional macros to Plain \TeX{}. -It enables users to take advantage of \LaTeX/ functionality but keeps -Plain \TeX/ simplicity. See -\url{http://petr.olsak.net/opmac-e.html} for more information about it.} - -\bigskip -\noindent -\OpTeX/ is \LuaTeX/ format with Plain \TeX/ and OPmac. Only \LuaTeX/ engine -is supported. - -\OpTeX/ should be a modern Plain \TeX/ with power from OPmac (Fonts -Selection System, colors, graphics, references, hyperlinks, -indexing, bibliography, ...) with preferred Unicode fonts. - -The main goal of \OpTeX/ is: - -\begitems -* \OpTeX/ keeps the simplicity (like in Plain \TeX/ and OPmac macros). -* There is no old obscurities concerning various 8-bit encodings and - various engines. -* \OpTeX/ provides a powerful Fonts Selection System (for Unicode font - families, of course). -* \OpTeX/ supports hyphenations of all languages installed in your \TeX/ system. -* All features from OPmac macros are copied. For example sorting words in - the Index\fnotemark1, reading `.bib` files directly\fnotemark1, syntax - highlighting\fnotemark1, colors, graphics, hyperlinks, references). - \fnotetext{All these features are implemented by \TeX/ macros, no external - program is needed.} -* Macros are documented in the same place where code is. -* User namespace of control sequences is separated from the internal namespace - of \OpTeX/ and primitives (`\foo` versus `\_foo`). - The namespaces for macro writers are designed too. -\enditems - -If you need to customize your document or you need to use something -very specific, then you can copy relevant parts of \OpTeX/ macros into your macro -file and do changes to these macros here. This is a significant difference from -\LaTeX/ or ConTeXt, which is an attempt to create a new user level with a -plenty of non-primitive parameters and syntax hiding \TeX/ internals. -The macros from \OpTeX/ are simple and straightforward because they solve only -what is explicitly needed, they do not create a new user level for -controlling your document. We are using \TeX/ directly in this case. -You can use \OpTeX/ macros, understand them, and modify them. - -\OpTeX/ offers a markup language for authors of texts (like \LaTeX), -i.\,e.\ the fixed set of tags to define the structure of the document. This -markup is different from the \LaTeX{} markup. It may offer to write the -source text of the document somewhat clearer and more attractive. - -The manual includes two parts: user documentation and technical -documentation. The second part is generated directly from the sources of -\OpTeX/. There are many hyperlinks from one part to second and vice versa. - -This manual describes \OpTeX/ features only. We suppose that the user knows \TeX/ -basics. They are described in many books. You can see a short -document \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf] -{\TeX/ in nutshell} too. - -\vfil\break - -\insertoutline{CONTENTS} \outlines{0} - -\notoc\nonum \sec Contents -\maketoc - -\thisoutline {USER DOCUMENTATION} - -\chap User documentation - -\input optex-userdoc -\endgroup - -%\end - -\input optex-techdoc - -\vfil\break - -\def\_printchap#1{\noindent{\_printrefnum[@]\_secfont #1}\medskip} - -\nonum\chap Index - -\begmulti 3 \tt \makeindex \endmulti - -\bye diff --git a/Master/texmf-dist/doc/luatex/optex/optex-math.tex b/Master/texmf-dist/doc/luatex/optex/optex-math.tex deleted file mode 100644 index 789dd5a1877..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/optex-math.tex +++ /dev/null @@ -1,1662 +0,0 @@ -%% This is part of the OpTeX project, see http://petr.olsak.net/optex - -% Run optex optex-math (two times) to generate this document -% or look at PDF here: http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf - -\fontfam[lmfonts] - -\font\ttlib=[LiberationMono-Regular] -\def\ttspec{\let\_ttfont=\ttlib} - -\report - -\def\new #1 {\mnote{\Red$\blacktriangleleft$\,\sans\setfontsize{at9pt}\rm#1}} -\fixmnotes\right -\enquotes -\verbchar` -\catcode`\<=13 -\def<#1>{$\langle\hbox{\it#1\/}\rangle$} -\everyintt={\catcode`\<=13 } -\def\ss#1{$\vrule height3pt#1\vrule height3pt$} - -\addto\_secfont\Blue \addto\_seccfont\Blue -\_def\_printsec#1{\_par - \_abovetitle{\_penalty-400}\_bigskip - {{\_secfont \_noindent \_raggedright \llap{\_printrefnum[@\_quad]}#1}\_nbpar}\_insertmark{#1}% - \_nobreak \_belowtitle{\_medskip}% - \_firstnoindent -} -\_def\_printsecc#1{\_par - \_abovetitle{\_penalty-200}\_medskip - {{\_seccfont \_noindent \_raggedright \llap{\_printrefnum[@\_quad]}#1}\_nbpar}% - \_nobreak \_belowtitle{\_medskip}% - \_firstnoindent -} - -\def\i #1 {\ii .#1 \iis .#1 {{\code{\\#1}}}} -\def\x`{\bgroup\_setverb\xx} -\bgroup \lccode\string`\.=\string`\` \lowercase{\egroup \def\xx #1#2.{\i #2 \egroup `#1#2.}} - - -\hyperlinks\Green\Green - -\insertoutline{MATH} -\outlines{0} - - - -\tit Typesetting Math with \OpTeX/ - -\hfill Version 03, January 2021 - -\author Petr Olšák - - -This document is a brief summary of typesetting math. It describes \TeX/, -Plain \TeX/ and \OpTeX/ features concerned to math. The first two types of -features are documented in \TeX/book in chapters 16, 17, and 18, but it is -summarized here in short again in order to give a complete guide about math -typesetting for \OpTeX/ users. - -\new {} -The \OpTeX/ features which differs from standard \TeX/ or Plain \TeX/ are -documented with the red triangle at the margin (like in this paragraph). -Reader can simply distinguish between \"standard" features (given by -\TeX/ or Plain \TeX/) and new \OpTeX/ features. - -There are more types of extensions: e\TeX, lua\TeX/, Unicode math and -\OpTeX/ macros. The appropriate label (e\TeX, Lua\TeX/, Unicode, \OpTeX/) -is appended to the red triangle to inform you about the extension type. -Nevertheless, \OpTeX/ user doesn't have to worry about it, all extensions -are available if Unicode Math font is loaded (e.g., by the command -`\fonfam[lmfonts]`). See section 1.3.3 in \OpTeX/ documentation about -loading Unicode math fonts. - -{\iindent=2em -\bigskip -\maketoc } -\vfil\break - -\sec Basics structure of math formulas - -\secc General rules and terminology - -The \ii in-line/math in-line math (in the paragraph) is created by `$<math list>$`. The -\ii display/math display math (a standalone line between paragraphs) is created by `$$<math list>$$`. -More than one line can be here if an appropriate macro is used. In-line math is -processed in a \TeX/ group in \ii in-line/math/mode {\em in-line math mode}. The display math is -processed in a \TeX/ group in \ii display/math/mode {\em display math mode}. Spaces are -ignored in math modes, so `$x+y$` and `$x + y$` gives the same result: $x+y$. - -The \ii math/list <math list> is a sequence of \ii math/atom,atom {\em math atoms} and -\ii other/material {\em other material}. -The math atoms are \ii single/math/object {\em single math objects} or -\ii composed/math/atom composed math atoms. - -\begitems \hfuzz=.6pt -* The single math object is a single character to be printed in math mode - like `x`, `+`, `\int`. -* The math atom is constructed in general by `{<math list 1>}^{<math list 2>}_{<math list 3>}`. - It consists from \ii nucleus {\em nucleus} <math list 1>, \ii exponent exponent <math list 2> - and \ii subscript subscript <math list 3>. Each part of the atom should be empty. - If <math list 2> or <math list 3> is empty, we need not to write brackets and - the prefix `^` or `_`. - If the <math list 1> or <math list 2> or <math list 3> - consist only from a single math object then we need not use brackets. - For example - `x^2` is a math atom with `x` in the nucleus, `2` in the exponent, and with empty subscript. - Or `a_{i,j}` is a math atom with `a` in the nucleus, empty exponent, and `i,j` in the subscript.% - \fnote{In \OpTeX/, the character `_` can be interpreted as a part of - the control sequence name, not as the subscript constructor. But in common cases, - constructions of math atoms are interpreted exactly as in plain \TeX. See sections - 2.2.2 and 2.14 of \OpTeX/ documentation for more details. If you want to - be sure that `_` is just a subscript constructor in \OpTeX/ then you can set \code{\\catcode`\\_=8} - but after this, you cannot use control sequences with `_` character.} - The constructors for exponent `^` and subscript `_` can be used in arbitrary order - after the nucleus, for example, `z_1^{x+y}` is the same math atom as - `z^{x+y}_1`. The single math objects not followed by `^` nor `_` are - considered as math atoms with this object in the nucleus and with empty - exponent and subscript (this is a very common case). - \TeX/ assigns the \ii class {\em class} for each math atom, see section~\ref[class]. -* Other material can be \TeX/ box or glue (space) or `\kern` or `\vrule` etc. -\enditems - -Example: The `Z = \int``_\Omega x^{2y} + z\, dx` generates -$Z = \int_\Omega x^{2y} + z\, dx$ and it is <math list> which consists from: - -\begitems -* `Z` is math atom with empty exponent and subscript, class: Ord, -* `=` is math atom with empty exponent and subscript, class: Rel, -* `\int``_\Omega` is math atom with empty exponent and with subscript `\Omega`, class: Op, -* `x^{2y}` is math atom with exponent `2y` and empty subscript, class: Ord, - \begitems \let\_bullet=\circ - * `2` is math atom with empty exponent and subscript, class: Ord, - * `y` is math atom with empty exponent and subscript, class: Ord, - \enditems -* `+` is math atom with empty exponent and subscript, class: Bin, -* `z` is math atom with empty exponent and subscript, class: Ord, -* `\,` is another material, the glue (space) in this case, -* `d` is math atom with empty exponent and subscript, class: Ord, -* `x` is math atom with empty exponent and subscript, class: Ord. -\enditems - -\secc[class] Classes of math atoms - -\TeX/ assigns \ii class {\em a class} for each math atom.\fnote -{Using terminology of \TeX/book, each single math object has its {\em class} but the - math atom has its {\em kind} derived from this class. I use only one word - for both meanings in this document.} -This data type is used when -\TeX/ decides about \ii horizontal/spacing horizontal spaces between atoms in the output. (Note -that spaces in the input are ignored.) For example, -`$xy$` prints two atoms without space between them but `$x+y$` is printed with -small spaces around the `+` binary operator. Compare: $xy$ and $x+y$. - -The class is assigned depending on the nucleus of the atom. If the nucleus is -not a single math object, i.e. it is constructed by `{<math list>}` with braces -then the atom has its class Ord. If the nucleus is a single math object constructed -without braces then the class of the atom depends on this single math -object. Each single math object must be declared in \TeX/ with its default -class. The following table lists the classes with typical examples. -The full set of all math objects used in math typesetting -is listed in section~\ref[objects] with their default classes. - -\bigskip -\noindent\hfil\table{llll}{ - & \ii class Class & Meaning & Example \crl - 0 & \iid Ord & ordinary object & variables, digits, $x, {\bbchar R}, \Gamma, 0, 1$ \cr - 1 & \iid Op & big opertator & $\sum, \int, \bigcup$ \cr - 2 & \iid Bin & binary operator & $+, \times, -, \pm, \cup$ \cr - 3 & \iid Rel & reations & $=, \ne, \leq, \supseteq, \succsim$ \cr - 4 & \iid Open & opening bracket & $\{, (, [, \langle$ \cr - 5 & \iid Close & closing bracket & $\}, ), ], \rangle$ \cr - 6 & \iid Punct & punctuation & comma \cr - & \iid Inner & left-right & \code{\\left...\\right} outputs, see section~\ref[delims] -} -\bigskip - -There are \ii horizontal/spacing,spacing three space types used -by the algorithm for horizontal spacing in the math formulas. - -\begitems -* \ii thin/space Thin space: \x`\thinmuskip` primitive register, `\,` macro. Used around Op atoms. -* \ii medium/space Medium space: \x`\medmuskip` primitive register, `\>` macro. Used around Bin atoms. -* \ii thick/space Thick space: \x`\thickmusip` primitive register, `\;` macro. Used around Rel atoms. -\enditems - -\puttext 7.8cm -3.7cm {\rotbox{90}{Left atom}} -\puttext 11.5cm -.5cm {Right atom} -\puttext 8.2cm -4.4cm {\typosize[9/11] -\thistable{\def\_enspace{ }}% -\table {l|8c|} { - \omit & Ord & Op & Bin & Rel & Open & Close & Punct & \omit \hfil Inner \crlp{2-9} - Ord & 0 & 1 & 2 & 3 & 0 & 0 & 0 & 1 \cr - Op & 1 & 1 & & 3 & 0 & 0 & 0 & 1 \cr - Bin & 2 & 2 & & & 2 & & & 2 \cr - Rel & 3 & 3 & & 0 & 3 & 0 & 0 & 3 \cr - Open & 0 & 0 & & 0 & 0 & 0 & 0 & 0 \cr - Close & 0 & 1 & 2 & 3 & 0 & 0 & 0 & 1 \cr - Punct & 1 & 1 & & 1 & 1 & 1 & 1 & 1 \cr - Inner & 1 & 1 & 2 & 3 & 1 & 0 & 1 & 1 \crlp{2-9} -}} - -\hangindent=-8.7cm \hangafter=0 -Ord atoms are printed without spaces between them. The spaces are not -cumulated, so the rule about spaces mentioned above is only a rough idea. -The exact rule for horizontal spaces is given for each pairs of atoms -in the table here. The symbol 0 means no space, 1 thin space, 2 medium space, -and 3 means thick space. - -\hangindent=-8.7cm \hangafter-2 -The Bin atom is automatically transformed to the -Ord atom if no atom precedes or if Op, Bin, Rel, Open, or Punct atom -precedes. And it is transformed to the Ord atom if Rel, Close or Punct atom -follows. This corresponds to the empty cells in the table. -Why such behavior? Compare \"\hbox{$0-3$}" and \"$-3$". The Bin atom in -the second case behaves like Ord atom because it is \ii unary/minus {\em unary minus}. -There is no space between the unary minus and the following object. - -All medium spaces and thick spaces and some thin spaces from this table are -omitted if the <math list> is processed in -\ii script/style,scriptscript/style script or scriptscript styles -(smaller size). See section~\ref[styles] about math styles. - -You can overwrite the default class derived from the nucleus of the atom by -\TeX/ primitives \x`\mathord`, \x`\mathop`, \x`\mathbin`, \x`\mathrel`, \x`\mathopen`, -\x`\mathclose`, \x`\mathpunct` and \x`\mathinner`. They can precede a nucleus of -the atom and they set the class of the atom. -For example, `x \mathrel+ y` behaves like `x = y` from a spacing point of view but + -is printed. Another example: `\mathop{\rm lim} z` creates the atom `lim` in -roman font of class Op. So, the thin space is inserted between lim and $z$. - -There are more special kinds of math atoms: fractions, math accents, -radicals. They are constructed in a special way (see next sections) but they behave -like Ord atom in the horizontal spacing algorithm. - -\secc[styles] Math styles - -When a formula (or a sub-formula) is processed by \TeX/ then one from four -\ii math/style,display/style,text/style,script/style,scriptscript/style -styles is active: display style ($D$), text style ($T$), script style ($S$) or -scriptscript style ($SS$). - -\ii T/style,D/style,S/style,SS/style The $T$ style is started in in-line math mode `$...$` and the $D$ -style is started in display math mode `$$...$$`. The first level of exponents or -subscripts is processed in $S$ style and the second and more levels of -exponents or indexes are processed in $SS$ style. -There are special rules for math styles when fractions are constructed, see -section~\ref[frac]. - -The $D$ and $T$ styles use basic \ii font/size font size, $S$ uses smaller font size (typically -70~\%) and $SS$ style uses more smaller font size (typically 50~\%). Next -levels of \"more smaller fonts" are not used due to classical typographic rules. - -The \ii nucleus nucleus of \iid Op atoms (big operators, $\sum$, $\int$, etc.) have typically bigger versions -of the character shape for $D$ style than for $T$ style. -So, there are four sizes for such math -objects: one size for each math style. All other math objects (with non Op -class) are printed only in three sizes: The sizes for $T$ and $D$ styles are equal. - -The \iid Op atom puts its \iid exponent and \iid subscript above and below the nucleus in $D$ -style but right to the nucleus in other styles: -$$ - `\sum``_{i=1}^\infty` \quad \hbox{gives}\quad \sum_{i=1}^\infty \hbox{ in $D$ style and} - \quad \textstyle \sum_{i=1}^\infty \hbox{ in $T$ style}. -$$ -This default behavior of the Op atom -can be modified by placing \x`\limits` or \x`\nolimits` or -\x`\displaylimits` \TeX/ primitive just after its nucleus before the constructors -of exponent and/or index. The `\nolimits` puts exponent and subscript right -to the nucleus (regardless of the current style) and `\limits` puts these -objects above and below the nucleus (regardless of the current style). There -can be more such primitives in a queue (due to a macro expansion, for -instance). Then the last primitive in the queue wins. -If the last primitive is \x`\displaylimits` then -the default behavior is processed regardless there are \x`\limits` or \x`\nolimits` -before it. -$$ - `\sum\nolimits``_{i=1}^\infty` \quad \hbox{gives}\quad \sum\nolimits_{i=1}^\infty - \hbox{ in $D$ style and}\quad \textstyle\sum\nolimits_{i=1}^\infty - \hbox{ in $T$ style}. -$$ -Atoms of all other classes have their exponents and/or subscripts only right -to their nucleus without any exception. - -The primitives \x`\displaystyle`, \x`\textstyle`, \x`\scriptstyle` and -\x`\scriptscriptstyle` set the given style regardless the default rules. For -example, you can create a formula in in-line math mode and in $D$ style by -`$\displaystyle <fomula>$` or a formula in display mode and $T$ style can be printed -by `$$\textstyle <fomrula>$$`. - -If a subformula is placed below something (below a line from root symbol, -below a fraction line), then the processed style $D, T, S$ or $SS$ is -\ii cramped/style {\em cramped}. -The exponents are positioned slightly lower than in -\ii non-cramped/style non-cramped style. The selectors `\displaystyle`\,\dots -`\scriptscriptstyle` mentioned above select non-cramped style. The -non-cramped style is selected when math mode starts too. -\new \OpTeX/ -You can select a cramped style by the macro \x`\cramped` at the start of the -math formula or after the math-style selectors: `\scriptstyle\cramped` for -example. - -Several macros need to know what math style is currently processed (for -example they need to draw something in an appropriate size). But it -not possible simply due to the syntax of fractions (section~\ref[frac]). -This syntax requires to process all math lists in two steps: the first step -expands all macros and creates structured data of processed math list. The -second step reads the output of the first step, switches between math -styles and creates definitive output. So, macros (working in the first step) -cannot know the current math -style because it is set only in the second step. \TeX/ supports the primitive -\x`\matchchioce``{<D>}{<T>}{<S>}{<SS>}` which prepares four math lists in the -first step and only one of these four lists are used in the second step. We -can put different macros into each of the four parameters of `\mathchoice`. -Plain \TeX/ supports the macro \x`\mathpalette` which gives a more comfortable -interface of \x`\mathchoice` to the macro programmer. -The cramped/non-cramped variants of the current style are kept when `\mathchioce` -is used. - -\new \OpTeX/ -We describe another interface for creating macros depending on the current -style. You can use \x`\mathstyles``{<math list>}`. It -behaves like `{<math list>}`, moreover, you can use the following commands inside such -<math list>: -\begitems -* The macro \x`\currstyle`. It expands to - `\displaystyle`, `\textstyle`, - `\scriptstyle` or `\scriptscriptstyle` depending on the current math style - when the `\mathstyles` was opened. -* The \x`\dobystyle``{<D>}{<T>}{<S>}{<SS>}` is expandable macro. It expands its - parameter `<D>`, `<T>`, `<S>` or `<SS>` depending on the current math style - when `\mathstyles` was opened. -* The value of the \x`\stylenum` register is 0, 1, 2 or 3 - depending on the current math style when `\mathstyles` was opened. -\enditems -% -Example of usage of \x`\mathstyles`: -\def\mysymbol{\mathbin\mathstyles - {\kern1pt\vrule height\mysymbolA width\mysymbolA\kern1pt}} -\def\mysymbolA{\dobystyle{5pt}{5pt}{3.5pt}{2.5pt}} -\begtt -\def\mysymbol{\mathbin\mathstyles - {\kern1pt\vrule height\mysymbolA width\mysymbolA\kern1pt}} -\def\mysymbolA{\dobystyle{5pt}{5pt}{3.5pt}{2.5pt}} -Test: $a\mysymbol b_{c \mysymbol d}$ or $a\mysymbol b\over c$. -\endtt -This example gives Test: $a\mysymbol b_{c \mysymbol d}$ or $a\mysymbol b\over c$. - -The \x`\mathstyles` macro mentioned above uses \TeX/ primitive \x`\mathchoice`, so it -creates four math lists and only one is used. It may take more -computer time in special cases. -\new Lua\TeX/ -Lua\TeX/ supports the \x`\mathstyle` primitive -(no \"`s`" at the end of this control sequence) which -expands to values 0 to 7 depending on the current style: -$D, D', T, T', S, S', SS, SS'$ -(where $X'$ means cramped variant of the style). This primitive does -not use `\mathchoice` but it simply ignores the fraction syntax, so -`$a\mysymbol b\over c$` cannot work if `\mysymbol` is defined using the `\mathstyle` -primitive. See section 7.3.1 of Lua\TeX/ documentation for more information. - - -\secc[frac] Fractions - -The \iid fraction can be constructed by `{<numerator>`\x`\over``<denominator>}`. If the -fraction is only a single object in the whole math mode (between dollars), -you need not use the outer braces, so you can write `$1\over2$` to get $1\over2$. - -The \ii numerator,denominator <numerator> and <denominator> are printed in \"smaller" math style than -current math style. More exactly the following schema is used. -$D$: $T\over T$., $T$: $S\over S$, $S$: $SS\over SS$, $SS$: $SS\over SS$. -For example -$$ - `{a+b \over c}` \quad \hbox{is printed as } - {a+b\over c} \hbox{ in $D$ style and as } - \textstyle {a+b\over c} \hbox{ in $T$ style}. -$$ - -The \LaTeX/ macro \x`\frac``{<numerator>}{<denominator>}` is not supported in -Plain \TeX/ nor in \OpTeX/ but you can define such macro if you want. - -The syntax with \x`\over` is more preferred because it is more human-readable -notation. You can write the fraction in the same manner as you can read it. -You can compare: `$1\over2$` (one over two) with `$\frac12$` (frac twelve). - -Besides the `\over` primitive, there are analogical \TeX/ primitives which -create \"generalized" fractions. The result is similar to `{<above>\over <below>}` -but there is something extra: - -\begitems -* `{<above>`\x`\atop``<below>}` does `{<above>\over<below>}` but - without the fractional rule. -* `{<above>`\x`\above``<dimen><below>}` creates fractional rule with <dimen> thickness. -* `{<above>`\x`\overwithdelims``<delim-l><delim-r><below>}` adds the <delim-l> left to - the fraction and the <delim-r> right to the fraction. -* `{<above>`\x`\atopwithdelims``<delim-l><delim-r><below>}` is analogical to - `\overwithdelims` but without fractional rule. -* `{<above>`\x`\abovewithdelims``<delim-l><delim-r><dimen><below>}` behaves as - `\overwithdelims` but the fractional rule has <dimen> thickness. -\enditems -% -The `\...withdelims` variants read <delim-l> and <delim-r>, they must be -declared as {\em math delimiter} in \TeX. They are vertically scalable -math objects, typically brackets. See section~\ref[delims] for more -information about math delimiters. Example: -$$ - `{n \atopwithdelims() k}`\quad \hbox{ creates } - {n \choose k} \hbox{ in $D$ style and } - \textstyle {n \choose k} \hbox{ in $T$ style}. -$$ -The \x`\choose` macro is defined by `\def\choose{\atopwithdelims()}`, so the -user can write `{n\choose k}` in order to get binomial coefficients. - - -\secc[delims] Vertically scalable objects: math delimiters - -The vertically scalable objects are called \ii delimiters {\em delimiters}. For example, -all types of brackets are declared as delimiters. -This means that you can use a bracket in arbitrary -vertical size.\fnote{ -This is not exactly true, because traditional typography says that they -cannot be scaled continuously but by visible steps. This means that there is -a sequence of increasing brackets in the font, the reader must see a difference -between every two sizes of brackets.} - -The following objects are declared as delimiters (i.e.\ vertically scalable): - -\bigskip -{\tt \adef!{\bslash} -\table{l 14c}{ - \rm source: & ( & ) & [ & ] & \code{\\\{} & \code{\\\}} & / - & !backslash & !langle & !rangle - & | & \code{\\|} & \cr - \rm output: &$($&$)$&$[$&$]$& $\{$ & $\}$ & $/$ - & $\backslash$ & $\langle$ & $\rangle$ - & $|$ & $\|$ -} -\medskip -\table{l 14c}{ - \rm source: & !lfloor & !rfloor & !lceil & !rceil \cr - \rm output: & $\lfloor$ & $\rfloor$ & $\lceil$ & $\rceil$ -} -\medskip -\table{l 14c}{ - \rm source: & !uparrow & !Uparrow & !dowarrow & !Downarrow - & !updownarrow & !Updownarrow \cr - \rm output: & $\uparrow$ & $\Uparrow$ & $\downarrow$ & $\Downarrow$ - & $\updownarrow$ & $\Updownarrow$ -}} -\bigskip -\noindent \new Unicode -If you can produce the characters $\langle$, $\rangle$,\fnote - {Do not confuse $\string<, >$ and $\langle, \rangle$. The first pair are Rel atoms - with meaning \"less than" or \"greater than", but the second pair are special - types of brackets. They are not directly available at computer keyboards without - using a keyboard macro.} -$\lfloor$, $\rfloor$, ... $\updownarrow$, $\Updownarrow$ -directly in your text editor then you can use these Unicode characters in your source instead of control -sequences `\langle`, `\rangle`, `\lfloor`, `\rfloor` ... `\updownarrow`, `\Updownarrow`. -For many users (including me), there is more simple to type `\lfloor` than to find -how to create the $\lfloor$ character in my text editor. Note that there exist -text editors (Emacs, for example) -enabling you to type `\lfloor` and this control sequence is immediately -converted to the $\lfloor$ Unicode character. -Your source text looks pretty and you can use classical \TeX/ sequences. - -\new Unicode -There are more \ii delimiters delimiters, but it heavily depends on loaded Unicode Math -font. For example, this document is printed in `latinmodern-math` font and -there are six more delimiters `\lBrack`~$\lBrack$, `\rBrack`~$\rBrack$, -`\lAngle` $\lAngle$, `\rAngle` $\rAngle$, `\lgroup` $\lgroup$, `\rgroup` $\rgroup$. -See section~\ref[objects] for table of all Unicode symbols for math typesetting. - -Arbitrary tall formula can be surrounded by a pair of delimiters using -\x`\left` and \x`\right` \TeX/ primitives: `\left<delim> <formula> \right<delim>`. -The delimiters are scaled to the height and depth of the <formula> -and vertically centered to the {\em math axis}.\fnote -{Math axis is a horizontal line passing through the center of symbols $+$ - and $-$. All vertically scalable objects are vertically centered with - respect to this axis.} -Example: -$$ - `+ \left\{ \sum_{i=1}^\infty x_i \right)` \quad \hbox{ gives } - + \left\{ \sum_{i=1}^\infty x_i \right). -$$ -The pair `\left<delim> <formula> \right<delim>` creates the formula in a -\TeX/ group. Such group can be nested with another groups. -Each `\left` must have its `\right` counterpart at the same group level. -If you don't want to create visible delimiter, use dot instead <delim>. -Example: -$$ - `\left. \int``_0^t e^{x^2}\,dx\, \right|_{t=42}` \quad \hbox{ gives } - \left. \int_0^t e^{x^2} \,dx\, \right|_{t=42} -$$ - -\new e\TeX/ -You can use \x`\middle``<delim>` inside the <formula> which is surrounded by -`\left...\right`. Then the given <delim> is scaled to the same size like -their `\left` and `\right` counterparts. - -When a delimiter is used without `\left` nor `\right` prefix, then it is the -Open, Close, Ord or Bin atom by its natural meaning: -$(, [, \{, \ldots, \lfloor, \lceil$ are Open atoms, -$], ], \}, \ldots, \rfloor, \rceil$ are Close atoms, -$/, \backslash, |, \|$ are Ord atoms and -$\uparrow, \Uparrow, \ldots, \Updownarrow$ are Bin atoms. You can overwrite -this default setting, for example `\mathclose(`. If delimiters are used with -`\left` and `\right` prefixes then `\left<delim>` behaves like Open atom, -`\right<delim>` behaves like Close atom and the math list -`\left<delim><formula>\right<delim>` is encapsulated as a single Inner atom. -The `\middle<delim>` behaves like Open atom at its left side and like Close -atom at its right side. - -The sequence of increasing delimiters can be printed by the following -macros: -$$ - `(` \to (,\quad \x`\big``(` \to \big(,\quad \x`\Big``(` \to \Big(,\quad - \x`\bigg``(` \to \bigg(, \quad \x`\Bigg``(` \to \Bigg(. -$$ -The `\Bigg<delim>` is not the maximal size of the bracket. Try -`\left(\vbox to5cm{}\right.`, for example. You can see that the font -\"cheats" from certain sizes, because there are not all infinity number of -sizes of brackets drawn in the font, of course. - -The `\big<delim>` creates Ord atom. We need to create Open atom -for opening bracket and Close atom for closing bracket more often. -Then we can use macros -\x`\bigl``<delim>`, -\x`\Bigl``<delim>`, -\x`\biggl``<delim>`, -\x`\Biggl``<delim>` for creating Open atoms and -\x`\bigr``<delim>`, -\x`\Bigr``<delim>`, -\x`\biggr``<delim>`, -\x`\Biggr``<delim>` for creating Close atoms. Unfortunately, the source is not -too attractive when more sizes of brackets are used, but typographic -traditions say that we have to distinguish brackets by the size in math -mode if they are in equal types: -$$ - `\Bigl( f\bigl( 2(x+y) + z\bigr) \Bigr)'` \quad \hbox{gives } - \Bigl(f\bigl(2(x+y)+z\bigr)\Bigr)'. -$$ - -\secc Horizontally scalable objects: math accents - -Arbitrary wide formula can be covered by \ii math/accent,accent {\em scalable math accent}. -Example: -$$ - \x`\overrightarrow`` {a+b+c+d+e+f}` \quad \hbox{gives } \overrightarrow {a+b+c+d+e+f}. -$$ -The usage is: control sequence of selected math accent followed by `{<math list>}`. - -Standard scalable math accents are: -\x`\overline` $\overline{abc}$, -\x`\overbrace` $\overbrace{abc}$, -\x`\overrightarrow` $\overrightarrow{abc}$, -\x`\overleftarrow`~$\overleftarrow{abc}$, -\x`\underline` $\underline{abc}$, -\x`\underbrace` $\underbrace{abc}$. - -An Op atom is created. The exponents and subscripts are centered above -and below the nucleus of this atom (regardless of the current style). Example: -$$ - `\overbrace {b\cdot b\cdot b \cdots b}^{k\times}` \quad \hbox{gives } - \overbrace {b\cdot b\cdot b \cdots b}^{k\times} -$$ -There are scalable accents with a limited maximum width: -\x`\widehat` $\widehat{abc}$ and \x`\widetilde` $\widetilde{abc}$. If the -formula is wider than the font can cover then the widest variant from the -font is used and it is horizontally centered. - -\new Unicode -There are more scalable accents in Unicode math fonts: -\x`\overparen` $\overparen{abc}$, \x`\underparen` $\underparen{abc}$, -\x`\overbracket` $\overbracket{abc}$, \x`\underbracket` $\underbracket{abc}$, -\x`\overleftrightarrow` $\overleftrightarrow{abc}$, -\x`\overleftharpoon` $\overleftharpoon{abc}$, -\x`\overrightharpoon` $\overrightharpoon{abc}$, - - -\secc Fixed math accents - -Fixed \ii math/accent,accent math accents can be applied to single math object or to the `{<math list>}`. -The accent is centered (with respect of slanting axis) and the result is a -nucleus of Ord -atom. For example `\dot x` gives $\dot x$. The list of fixed math accents -follows: \x`\acute`` x` $\acute x$, \x`\bar`` x` $\bar x$, -\x`\breve`` x` $\breve x$, \x`\check`` x` $\check x$, -\x`\dot`` x` $\dot x$, \x`\ddot`` x` $\ddot x$, -\x`\grave`` x` $\grave x$, \x`\hat`` x` $\hat x$, -\x`\vec`` x` $\vec x$, \x`\tilde`` x` $\tilde x$. - -\new Unicode -The additional fixed accents depends on used Unicode math font. The -`latinmodern-math` supports: -\x`\ovhook`` x` $\ovhook x$, \x`\ocirc`` x` $\ocirc x$, -\x`\leftharpoonaccent`` x` $\leftharpoonaccent x$, \x`\rightharpoonaccent`` x` $\rightharpoonaccent x$, -\x`\dddot`` x` $\dddot x$, \x`\ddddot`` x` $\ddddot x$, -\x`\widebridgeabove`` x` $\widebridgeabove x$, \x`\asteraccent`` x` $\asteraccent x$. - -There exist one special math accent `'` (single quote, ASCII 39) -which can be appended after a symbol like this: `f'` -and it creates $f'$ (typical meaning is the -derivation of the given function). You can put more such accents, for -example `g'''` gives $g'''$. - -\secc Roots - -There is a macro \x`\sqrt``{<math list>}` to create \ii square/root square root. For example: -$$ - `\sqrt{\sqrt{\sqrt{x+1}+1}+1}` \quad \hbox{gives } - \sqrt{\sqrt{\sqrt{x+1}+1}+1} -$$ -The \ii root $n$-th root is created by the macro \x`\root`` <n>\of{<math list>}`. For -example `\root k+1\of x` gives $\root k+1\of x$. - -\secc Math alphabets - -Letters \ii math/alphabet $a\dots z$, $A\dots Z$ and $\alpha$\dots$\omega$ are printed in italic -in math mode. This follows the traditional typographic rule. -All other math symbols, digits, and uppercase Greek letters must be -upright.\fnote -{French typographic convention says that uppercase Greek letters have to be - in italic too. Use `\_itGreek` declaration in this case.} -These rules are independent of the current variant of surrounding text font. - -If we want to use the letters or digits -in another than this default shape, then we can use -\ii math/alphabet/selector {\em math alphabet selectors}: -\x`\mit`, \x`\rm`, \x`\it`, \x`\bf`, \x`\cal`. -\new \OpTeX/ -\OpTeX/ supports more such selectors \x`\script`, \x`\frak`, \x`\bbchar`, \x`\bi`, see -section 1.3.3 in the \OpTeX/ documentation. The math selectors have local -validity in the group. - -The control sequences \x`\rm`, \x`\it`, \x`\bf`, and \x`\bi` act as variant selectors -of fonts in non-math mode (text mode) and they act -as math alphabet selectors in math mode. This \"overlaying" concept -is given by Plain \TeX/. Example: math operators lim, sin, cos, -log, etc.\ must be printed unslanted. We are using `\lim`, `\sin`, `\cos`, -`\log` etc.\ in math mode in order to comply with this typographic convention. For -example `\sin` is defined as: -\begtt -\def\sin {\mathop{\rm sin}\nolimits} -\endtt -The `\rm` is used here as math alphabet selector, no variant selector of -text fonts. - -The list of all predefined `\rm`-like math operators follows: \x`\arccos`, -\x`\arcsin`, \x`\arctan`, \x`\arg`, \x`\cos`, \x`\cosh`, \x`\cot`, \x`\coth`, \x`\deg`. -\x`\det`, \x`\dim`, \x`\exp`, \x`\gcd`, \x`\hom`, \x`\inf`, \x`\ker`, \x`\lg`, \x`\lim`, -\x`\liminf`, \x`\limsup`, \x`\ln`, \x`\log`, \x`\max`, \x`\min`, \x`\Pr`, \x`\scs`, \x`\sin`, -\x`\sinh`, \x`\sup`, \x`\tan`, \x`\tanh`, You can define another such operator -analogically. - -\new Unicode -Unicode font can include the following math alphabets: -\begtt \typosize[9/11] -\_rmvariables % upright letters A-Z, a-z -\_bfvariables % bold letters A-Z, a-z -\_itvariables % italic letters A-Z, a-z -\_bivariables % bold italic letters A-Z, a-z -\_calvariables % calligraphic letters A-Z, a-z -\_bcalvariables % calligraphic letters A-Z, a-z -\_frakvariables % fraktur A-Z, a-z -\_bfrakvariables % bold fraktur A-Z, a-z -\_sansvaraibales % sans serif letters A-Z, a-z -\_bsansvaraibales % bold sans serif letters A-Z, a-z -\_isansvaraibales % slanted sans serif letters A-Z, a-z -\_bisansvaraibales % bold slanted sans serif letters A-Z, a-z -\_ttvariables % monospace, typewriter letters A-Z, a-z -\_bbvariables % double struck A-Z, a-z -\_rmdigits % upright digits 0..9 -\_bfdigits % bold digits 0..9 -\_sansdigits % sans serif digits 0..9 -\_bsansdigits % bold sans serif digits 0..9 -\_ttdigits % monospace typewriter digits 0..9 -\_bbdigits % double-struck digits 0..9 -\_rmgreek % upright Greek letters \alpha-\omega -\_itgreek % slanted Greek letters \alpha-\omega -\_bfgreek % bold Greek letters \alpha-\omega -\_bigreek % bold italic Greek letters \alpha-\omega -\_bsansgreek % bold sans serif Greek letters \alpha-\omega -\_bisansgreek % bold slanted snas serif Greek letters \alpha-\omega -\_itGreek % slanted Greek letters \Alpha-\Omega -\_bfGreek % bold Greek letters \Alpha-\Omega -\_biGreek % bold italic Greek letters \Alpha-\Omega -\_bsansGreek % bold sans serif Greek letters \Alpha-\Omega -\_bisansGreek % bold slanted snas serif Greek letters \Alpha-\Omega -\endtt -% -Not all Unicode math fonts include all math alphabets listed here. Typically, -the lowercase letters of calligraphic shape and all letters of -bold calligraphic shape are missing. - -\new \OpTeX/ -\OpTeX/ defines internal math alphabet selectors as mentioned in the -previous listing of math alphabets and sets as default: -\begtt \typosize[10/12] -\_itvariables \_rmdigits \_itgreek \_rmGreek -\endtt -% -Moreover, it defines the alphabet selectors at user level (see section 1.3.3 -of the \OpTeX/ manual). For example -\begtt \typosize[10/12] -\def\rm {\_tryload\_tenrm \_inmath{\_rmavariables \_rmdigits}} -\endtt -% -The first part -\new \OpTeX/ -`\_tryload\_tenrm` is applicable for text fonts and the -`\_inmath` part is processed only in math mode and sets the math alphabets. -You can see the file `unimath-codes.opm` where all user-level selectors are -defined. You can redefine them. For example, \OpTeX/ defines `\bf` as a math -alphabet selector that selects sans serif bold in math. This is the common -notation for vectors, tensors, and matrices. If you dislike this, then you can define: -\begtt \typosize[10/12] -\def\bf {\_tryloadbf\_tenbf \_inmath{\_bfvariables\_bfdigits\_bfgreek\_bfGreek}} -\endtt - - -\secc[objects] List of single math objects - -\new Unicode -All \ii single/math/object single math objects are listed in the `unimath-table.opm` or -`unicode-math-table.tex` file. You can -look into this file. The codes, \TeX/ sequences, classes, and comments -for all possible math codes are here. Maybe, your Unicode math font which is loaded -does not support all these codes. -\new \OpTeX/ -You can try all codes of the currently loaded font by -\begtt -\input print-unimath.opm -\endtt -The `unimath-table` is printed with characters available in the loaded font. -\new \OpTeX/ -If the character is unsupported by the font then the slot is empty and only -\TeX/ sequence and the class of the code is printed in the table. -For example, this document loads `latimodern-math.otf` font. -And the result from `\input print-unimath.opm` looks like the following ten -pages. - -Unsupported characters can be replaced by characters from other Unicode math -font, see -\ulink[http://petr.olsak.net/optex/optex-tricks.html\#addumathfont]{OpTeX trick 0030} -or section~\ref[newfam]. - - -\label[listA]\wlabel{} - -\bigskip -\input print-unimath.opm -\bigskip - -\label[listB]\wlabel{} - -It isn't very comfortable to find something in the previous table -if you know the shape. You can try the online web tool \ii Detexify -\ulink[https://detexify.kirelabs.org/classify.html]{Detexify}. -You can draw the symbol here and the suggestion of \TeX/ sequence is -printed. - -\def\g#1{{\tt\string#1}~$#1$} - -The generic \TeX/ sequences for the Greek letters \ii Greek/letters can be used: -\g\alpha, \g\beta, \g\gamma, \g\delta, \g\varepsilon, \g\zeta, \g\eta, -\g\theta, \g\iota, \g\kappa, \g\lambda, \g\mu, \g\nu, \g\xi, -\g\omicron, \g\pi, \g\rho, \g\varsigma, \g\sigma, \g\tau, \g\upsilon, -\g\varphi, \g\chi, \g\psi, \g\omega, \g\vardelta, \g\epsilon, \g\vartheta, -\g\varkappa, \g\phi, \g\varrho, \g\varpi\ -and -\g\Alpha, \g\Beta, \g\Gamma, \g\Delta, \g\Epsilon, \g\Zeta, \g\Eta, \g\Theta, -\g\Iota, \g\Kappa, \g\Lambda, \g\Mu, \g\Nu, \g\Xi, \g\Omicron, \g\Pi, \g\Rho, -\g\Sigma, \g\Tau, \g\Upsilon, \g\Phi, \g\Chi, \g\Psi, \g\Omega. - -\new \OpTeX/ -The variant of Greek letters in the output -(upright, italic, bold, bold sans serif, etc.) -written by the sequences `\alpha`, `\beta` etc. depends on the math alphabet -selected by `\_itgreek`, `\_rmgreek`, etc. selectors. The user-level -selectors `\bf` and `\bi` set `\_bsansgreek` and `\_bisansgreek`, so -`{\bi\delta}` produces $\bi\delta$. - -\new Unicode -All characters available in the math font can be accessed by \TeX/ control -sequence or by directly using the Unicode character in the document source. -Example: -\begtt \adef/{} -$$ - \sum/_{k=0}^\infty e^{(\alpha+i\beta/_k)} = - e^\alpha \sum/_{k=0}^\infty e^{i\beta/_k} = - e^\alpha \sum/_{k=0}^\infty (\cos\beta/_k + i\sin\beta/_k). -$$ -\endtt -or -\begtt \ttspec -$$ - ∑_{k=0}^∞ e^{(α + iβ_k)} = e^α ∑_{k=0}^∞ e^{iβ_k} - = e^α ∑_{k=0}^∞ (\cos β_k + i\sin β_k). -$$ -\endtt -both gives the same result: -$$ - ∑_{k=0}^∞ e^{(α + iβ_k)} = e^α ∑_{k=0}^∞ e^{iβ_k} - = e^α ∑_{k=0}^∞ (\cos β_k + i\sin β_k). -$$ -\medskip - - -\sec Other specialities - -\secc The `\not` prefix - -You can apply \x`\not` before a following math object. -The slash $/$ is overprinted such math object, for example -`$a \not= b$` gives $a \not= b$. - -\new \OpTeX/ -If there exists a direct Unicode character for the negation of a relation symbol -(for example `\ne` creates $\ne$ directly as a character U+2260) -then `\not<char>` expands to appropriate Unicode character. -For example `\not=` expands to `\ne` or `\not\in` expands to `\notin`. -If such character does not exist then -the centered $/$ is overprinted over the next character. - - -\secc The `\buildrel` macro: text over the relation - -The macro \x`\buildrel`` <text>\over <relation>` creates a new atom Rel with the -<relation> and with the smaller <text> above this <relation>. Example: -`$M \buildrel\rm def\over= X\cup Y$` gives $M\buildrel\rm def\over= X\cup Y$. - - -\secc Spaces - -Spaces between atoms are created automatically as were mentioned in -section~\ref[class]. But sometimes you have to help \TeX/ to create -appropriate space. You can use following macros: - -\begitems -* `\,` is \ii thin/space {\em thin space} used around Op atoms, after comma, etc.: \ss\,, -* `\!` is \ii negative/thin/space negative thin space, -* `\>` is \ii medium/space {\em medium space} used around Bin atoms: \ss\>, -* `\;` is \ii thick/space {\em thick space} used around Rel atoms: \ss\;, -* \x`\quad` is \ii em/space {\em em space}: \ss\quad, -* \x`\qquad` is \ii double/em/space {\em double em space}: \ss\qquad. -\enditems -% -Of course, you can use \ii direct/space {\em direct space} {\visiblesp`\ `} which is \TeX/ primitive -and gives interword space: \ss\ \ -or you can use \x`\hskip`` <value>` to put arbitrary space. - -The space size of `\,`, `\!` resp. `\>`, resp. `\;` is given by -`\thinmuskip`, resp. `\medmuskip`, resp. `\thickmuskip` values. You can see -in the `plain.tex` file that these default values differ very little in their basic -size but there is no stretchability/shrinkability in the `\,` space, there is small -stretchability in the `\>` space, and more stretchability in the `\;` space. - -The registers \x`\thinmuskip`, \x`\medmuskip`, and \x`\thickmuskip` store so-called -\ii mu/values {\em mu values} given by math unit `mu`. It is 1/18 em and this unit depends -on the current font size used in the math formula ($S$ or $SS$ styles use -smaller font size, the `mu` unit is smaller here). You can use \x`\muskip` -instead `\hskip` or \x`\mukern` instead `\kern` if you want to use this -special mu unit. It is allowed only in math mode. - -The \x`\quad` and \x`\qquad` spaces have fixed width and they can be used in text -mode too. (\OpTeX/ allows to use `\,` in text mode too). -Use `\quad` or `\qquad` if you want to separate more formulas created in -single math mode. Examples of typical usage of spaces: - -\begtt \adef/{} \typosize[10/12] -$$ \alpha\,(x+y), \qquad \int/_a^b \!\! f(x)\,{\rm d}x, \qquad \Gamma/_{\!i}. $$ -\endtt -$$ \alpha\,(x+y), \qquad \int_a^b \!\! f(x)\,{\rm d}x, \qquad \Gamma_{\!i}. $$ - - -\secc Texts in math mode - -If you write `$Hello world!$` (i.e.\ Hello world in math mode), then you get -$Hello world!$. It is interpreted as the product of variables $H$, and $e$, and -$l^2$, and $o$, etc., followed by the symbol ! used for factorial. -The non-ASCII letters (with accents) don't work at all because they are -never used as symbols for variables. Spaces are ignored. - -If you want to write a short text in the math mode, then you can use -`\hbox{<text>}`. The \x`\hbox` primitive initializes text mode regardless of -the \"outer mode". Example: - -\begtt \adef/{} \typosize[10/12] -$$ \sum/_{n=0}^\infty (-1)^n a_n \hbox{ converges, if $a_n\searrow 0$.} $$ -\endtt -$$ \sum_{n=0}^\infty (-1)^n a_n \hbox{ converges, if $a_n\searrow 0$.} $$ -% -Note the space before the word \"converges". The space before `\hbox` is -irrelevant. Second notice: the example shows the text mode inside math mode -and the in-line math mode inside this text mode. The same result can be -produced by: - -\begtt \adef/{} \typosize[10/12] -$$ \sum/_{n=0}^\infty (-1)^n a_n \hbox{ converges, if } a_n\searrow 0. $$ -\endtt -% -The difference can be visible if the formula $a_n\searrow 0$ includes a -fraction, for example ${1\over2}a_n\searrow 0$. The first example prints the -fraction in the text style and the second example prints it in the display style. - -The disadvantage of `\hbox` is that it starts in the text mode independently -of the current style, but we want to use smaller font in $S$ or $SS$ styles. -\new \OpTeX/ -You can use \x`\mathbox``{<text>}` in such situations. This macro behaves like -`\hbox` but the text is appropriately smaller in $S$ and $SS$ styles. -Example: -$$ - `{\mathbox{cena}\over\mathbox{výkon}}` \quad \hbox{gives } - {\mathbox{cena}\over\mathbox{výkon}} \hbox{ in $D$ style and } - \textstyle {\mathbox{cena}\over\mathbox{výkon}} \hbox{ in $T$ style.} -$$ -Note that $\mathbox{cena}\over\mathbox{výkon}$ means $\rm price\over performance$ -and you can write `$\rm price\over performance$` when you are using only -words without spaces and accented letters. But phrases with spaces or accented letters -should be printed in text mode using `\hbox` or `\mathbox`. - -\secc `\vcenter` - -The \x`\vcenter` primitive behaves like `\vbox`, but it can be used only in -math mode and its result is vertically centered to the math axis. -For example, matrices, are created by tables in `\vcenter`. - -All big objects in math formula are centered on the math axis and the baseline is -ignored. In the following example, we create a new big math operator by -`\vcenter`: -\begtt -$$ - \def\myop#1{\mathop{\vcenter{\frame{\vbox to2em{\vss\hbox{ $#1$ }\vss}}}}} - F(x) = \myop{x(i)}_{i=1}^\infty -$$ -\endtt -\vskip-2em -$$ - \def\myop#1{\mathop{\vcenter{\frame{\vbox to2em{\vss\hbox{ $#1$ }\vss}}}}} - F(x) = \myop{x(i)}_{i=1}^\infty -$$ - - -\secc Three dots - -You can write `$1,2,\dots,n$` to get $1,2,\dots,n$. The \x`\dots` macro puts -thin space between dots and after the last dot, so the five object: comma, -dots, comma are exactly equidistant. - -Typographic conventions say that you have to use the repeating symbol -before and after three dots (comma in the previous example) and the three dots -should be at baseline if the repeating symbol is at baseline. Or they should be -at the math axis if the repeating symbol is at the math axis. We have to use \x`\cdots` instead -`\dots` in the second case. Example: -$$ - `a_1, a_2, \dots, a_n, \quad a_1 + a_2 + \cdots + a_n` \qquad - a_1, a_2, \dots, a_n, \quad a_1 + a_2 + \cdots + a_n -$$ -\vskip-.7em -There are \x`\vdots` $\vdots$, \x`\ddots` $\ddots$ and \x`\adots` $\adots$ which -can be used in matrices. - -\new Unicode -Three dots like the output of the `\dots` macro are present as a single -character in fonts too. This character is called ellipsis. Font designers -typically suggest this character with smaller spaces between dots than we -need in math mode. So the rule about equidistant \"comma, three dots, comma" -is not met when this character is used. You can try `$1,2,\unicodeellipsis, n$` -and `$1+2+\unicodecdots + n$`. You get $1,2,\unicodeellipsis, n$ and -$1+2+\unicodecdots + n$. If you feel that this is better, then you can set: -`\let\dots=\unicodeellipsis \let\cdots=\unicodecdots`. - -The Unicode fonts includes compact variants `\unicodevdots` $\unicodevdots$, -`\unicodeddots` $\unicodeddots$ and `\unicodeadots` $\unicodeadots$ too. - - -\secc Phantoms and `\smash` - -The \x`\phantom``{<math list>}` macro creates an invisible subformula equal to -the formula generated by <math list>. It has its size, so it can -interfere with surrounding visible subformulas. This macro is very useful for -aligning with special requirements. Examples are shown in -sections~\ref[matrix] and~\ref[elines]. - -The \x`\vphantom``{<math list>}` has only its vertical size (i.e.\ its height -and depth), the width is zero. The \x`\hphantom``{<math list>}` has only its -width. - -The \x`\smash``{<math list>}` is the opposite of `\vphantom`. It creates visible -subformula but it has only its width. Its height and depth are zero. - -The result of these macros is the nucleus of an Ord atom. You can use `\mathop`, -`\mathbin`, etc. primitives to change this class. For example -`$a\mathrel{\phantom{=}}b$` creates the same formula as $a=b$ with the same -distance from $a$ to $b$ but without the equal sign: -$a\mathrel{\phantom{=}}b$. - -These macros work in the text mode too. Then their argument is -the <horizontal list>. - - -\sec Structured objects - -\secc[matrix] Matrices - -The macro \x`\matrix``{<data>}` creates a vertically centered table of items. -The <data> includes <items> separated by `&` and rows are separated by -`\cr`. The number of columns and rows are unlimited. Columns are printed centered -and separated by the `\quad` space. The vertically scalable -brackets around the table are not printed. You can use \x`\pmatrix``{<data>}` -instead `\matrix{<data>}`: the vertically scalable parentheses () are inserted -around the table. Examples: - -\begtt -$$ - {\bf A} = \pmatrix{a_{1,1} & a_{1,2} & \cdots & a_{1,n} \cr - a_{2,1} & a_{2,2} & \cdots & a_{2,n} \cr - \vdots & \vdots & \ddots & \vdots \cr - a_{m,1} & a_{m,2} & \cdots & a_{m,n} }, -$$ -\endtt -$$ - {\bf A} = \pmatrix{a_{1,1} & a_{1,2} & \cdots & a_{1,n} \cr - a_{2,1} & a_{2,2} & \cdots & a_{2,n} \cr - \vdots & \vdots & \ddots & \vdots \cr - a_{m,1} & a_{m,2} & \cdots & a_{m,n} }, -$$ -or: - -\begtt -\def\qmatrix[#1]{\left[\matrix{#1}\right]} -$$ - \qmatrix[a&b&c\cr d&e&f\cr g&h&i] \cdot \qmatrix[x_1\cr x_2\cr x_3] - = \qmatrix[b_1\cr b_2\cr b_3]. -$$ -\endtt -$$ - \def\qmatrix[#1]{\left[\matrix{#1}\right]} - \qmatrix[a&b&c\cr d&e&f\cr g&h&i] \cdot \qmatrix[x_1\cr x_2\cr x_3] - = \qmatrix[b_1\cr b_2\cr b_3]. -$$ - -If you need to align the columns by another way than to center, then you can -use the phantom. Compare: - -\begtt -$$ - \pmatrix{ 1 & -1 & 0 \cr - 0 & 2 & 13 \cr - -3 & 0 & 5 } \quad \hbox{or} \quad - \def\0{\phantom0} \def\+{\phantom+} - \pmatrix { \+1 & -1 & \00 \cr - \+0 & \+2 & 13 \cr - -3 & \+0 & \05 } -$$ -\endtt -$$ - \pmatrix{ 1 & -1 & 0 \cr - 0 & 2 & 13 \cr - -3 & 0 & 5 } \quad \hbox{or} \quad - \def\0{\phantom0} \def\+{\phantom+} - \pmatrix { \+1 & -1 & \00 \cr - \+0 & \+2 & 13 \cr - -3 & \+0 & \05 } -$$ - -\new\OpTeX/ -Another option to set the right aligned matrix is setting the \x`\lmfil`: -Its value is used on the left side in each `\matrix` item. The right side is -set directly to `\hfil`. -\begtt -$$ - \lmfil={\hfill} % left matrix filler = \hfill - \pmatrix{ 1 & -1 & 0 \cr 0 & 2 & 13 \cr -3 & 0 & 5 } -$$ -\endtt - -\new \OpTeX/ -If you want to draw a vertical line inside the matrix, you can use `\adef|` -as in the following example: -\begtt -$$ - \adef|{\kern-.2em&\strut\vrule&\kern-.2em} - \def\+{\phantom+} - \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \sim - \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} \sim - \pmatrix{1 & 2 & 3 | 0 \cr 0 & 1 & 2 | -1/3 \cr 0 & 0 & 0 | 1 } -$$ -\endtt -$$ - \adef|{\kern-.2em&\strut\vrule&\kern-.2em} - \def\+{\phantom+} - \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \sim - \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} \sim - \pmatrix{1 & 2 & 3 | 0 \cr 0 & 1 & 2 | -1/3 \cr 0 & 0 & 0 | 1 } -$$ - -If you want to put something before the opening bracket in the matrix, you can -use another `\matrix`. Example: - -\begtt -$$ - \adef|{\kern-.2em&\strut\vrule&\kern-.2em} - \def\+{\phantom+} - \def\r{{\bf r}} - \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \ \sim \ - \matrix{\cr 2.\r - 4\cdot 1.\r: \cr 3.\r -7\cdot 1.\r: } - \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} -$$ -\endtt -$$ - \adef|{\kern-.2em&\strut\vrule&\kern-.2em} - \def\+{\phantom+} - \def\r{{\bf r}} - \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \ \sim \ - \matrix{\cr 2.\r - 4\cdot 1.\r: \cr 3.\r -7\cdot 1.\r: } - \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} -$$ - -Plain \TeX/ defines the \x`\bordermatrix` macro which allows you to create a -top row above the brackets and left column before the opening bracket. -\TeX/book shows the following example: - -\begtt -$$ - M = \bordermatrix{ &C&I&C'\cr - C&1&0&0 \cr I&1-b&0 \cr C'&0&a&1-a } -$$ -\endtt -$$ - M = \bordermatrix{ &C&I&C'\cr - C&1&0&0 \cr I&1-b&0 \cr C'&0&a&1-a } -$$ - -The `\matrix` macro used in $D$ style creates all its items in $T$ style. -\new \OpTeX/ -If you are using the `\matrix` macro in $T$ style or $S$ style (but not in -fractions nor another matrices) then the resulting table is appropriately -smaller and all its items are processed in $S$ style. -If you are using `\matrix` in $SS$ style then the items are in $SS$ style too. -The following example shows one-column matrix in script style: -$$ - `\sum``_{\matrix{i\in M\cr j\in N\cr k\in P}} x_{i,j,k}` \ \hbox{ creates: } - \sum_{\matrix{i\in M\cr j\in N\cr k\in P}} x_{i,j,k} -$$ - - -\secc Cases - -The \x`\cases` macro can be used as in the following example: - -\begtt -$$ - f(x) = \cases{ 1 & for $x\le 0$, \cr - 100-x\over 100 & when $0 < x \le 100$, \cr - 0 & in other cases. } -$$ -\endtt -$$ - f(x) = \cases{ 1 & for $x\le 0$, \cr - 100-x\over 100 & when $0\string< x\le 100$, \cr - 0 & in other cases. } -$$ - -The `\cases` macro behaves like a special `\matrix` with two left-aligned -columns and with left vertically scaled brace $\{$. -The first column is processed in math mode and $T$ style, the second column -is processed in text mode. We have to use `$...$` in the second column if -there is math material. - - -\sec Lines in display mode - -\secc General principles - -The \ii display/math,display/math/mode -`$$<formula>$$` finalizes previous paragraph, prints centered <formula> on -single line with a vertical space above and below and opens next paragraph -with no indentation. - -From \TeX/'s point of view, the text above `$$<formula>$$` plus text -below is a single paragraph interrupted by display <formula>. If there is no -text above (i.e. the opening `$$` are in vertical mode), then the internal -`\noindent` is processed first and the empty line above <formula> is created. -Thus, it is definitely a bad idea to open display mode in vertical mode: never -put an empty line before `$$<formula>$$`. On the other hand, the empty line -just after `$$<formula>$$` says that the paragraph is finalized by the -<formula> and the next text (after the empty line) opens the next paragraph with -indentation. Summary: - -\begitems -* \"Text above `$$<formula>$$` text below": the <formula> interrupts the - paragraph with \"Text above" and \"text below". The \"text below" is - without indentation. -* \"Text above `$$<formula>$$` empty line Text below": the \"Text below" - opens new paragraph with indentation. -* \"Empty line `$$<formula>$$`" is bad practice. -\enditems - -In contrast with the paragraph breaking, there is no built-in algorithm for -breaking display <formula> to more lines. If the <formula> is too wide then -overfull `\hbox` occurs and human must decide about splitting the <formula> -to more lines. The macros `\displaylines` and `\eqalign` are intended to -such task, see sections~\ref[dlines] and~\ref[elines]. - -On the other hand, the in-line math <formula>, i.e.\ the `$<formula>$` in a -paragraph, can be broken after a Bin atom (with penalty `\binoppenalty`) or -after a Rel atom (with penalty `\relpenalty`). If you don't want to break -such a formula at a specific place then use `\nobreak`, for example -`$a+\nobreak b$`. If you want never to break such formulas then you can set -`\binoppenalty=10000`, `\relpenalty=10000`. (Default values are 700 and 500.) - - -\secc References to display lines - -The `$$<formula>`\x`\eqno``<mark>$$` \ii mark prints centered <formula> and the <mark> at -right margin. The `$$<formula>`\x`\leqno``<mark>$$` prints centered <formula> and -the <mark> at left margin. Examples: - -\begtt -$$ a^2 + b^2 = c^2 \eqno (1) $$ -\endtt -$$ - a^2 + b^2 = c^2 \eqno (1) -$$ -\begtt \aftergroup\nobreak -$$ a^2 + b^2 = c^2 \leqno \rm Py $$ -\endtt -$$\predisplaypenalty=10000 - a^2 + b^2 = c^2 \leqno \rm Py -$$ -The <mark> \ii mark is processed in math mode and $T$ style. If you want to put a -text here then you have to use `\rm <text>` or `\hbox{<text>}`. - -\new \OpTeX/ -The auto-generated <mark> can be created by `$$<formula>`\x`\eqmark``$$`. The -<label> can be used previously declared by \x`\label``[<label>]`. -Then it is associated to such -auto-generated <mark> and you can write a reference in the form -`see equation~\ref[<label>]`. You can write `\eqmark[<label>]` instead of -`\label[<label>]...\eqmark`. See the \OpTeX/ manual, section~1.4.3. - -\secc[dlines] The `\displaylines` macro - -This macro creates more horizontally centered formulas in one display mode. -The syntax is -\begtt \catcode`\<=13 -$$ \displaylines{ - <formula> \cr - <formula> \cr - ... \cr - <formula> -} $$ -\endtt -Usage of \x`\displaylines` is more -prefered than doing more display modes just behind each other. -Example: -\begtt -$$ \displaylines{ - (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr - = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. -} $$ -\endtt -$$ \displaylines{ - (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr - = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. -} $$ - -The output from `\displaylines` macro is breakable to more pages because -the lines are not encapsulated in one box. The macro uses a special feature of -`\halign` primitive. The disadvantage is that you cannot use `\eqno` nor -`\leqno` nor `\eqmark`. - -\new \OpTeX/ -\OpTeX/ provides alternative form: `\displaylines to<dimen> {<data>}`. -Then the centered formulas are encapsulated in a `\vcenter` box of width <dimen> and -usage of `\eqno` or `\leqno` or `\eqmark` is allowed. -The individual lines have the form `\hbox to<dimen>` and formulas are centered using -`\hss` from both sides. This means that you can set arbitrary <dimen> -without visual change of the formulas. Use smaller <dimen> value than -`\hsize` (or `\displaywidth`\fnote -{`\displaywith` = `\hsize` in most cases but it is -real display width when `\parshape` or `\hangindent` is used.}) -if you want to center formulas with `\eqno` appended. -The internal \TeX/ rule says: the formula with `\eqno` (or `\leqno`) is centered -if its width is less or equal `\displaywidth-4<mark-width>`. So -\begtt \catcode`\<=13 -$$ \displaylines to\hsize-8em {<formula>\cr<formula>}\eqno (1) $$ -\endtt -does global centering, because size of `(1)` is less than 2\,em. -You can do more experiments with this example, -for example `\diplaylines to\hsize{...}` -puts the `\eqno` mark to the next line in the display environment. Read -\TeX/book or \TeX/book naruby, where the precise explanation about such -positioning is. - -\new \OpTeX/ -You can use \"`\displaylines to<dimen>`" for more applications. For example, -you can put more -\"`\displaylines to<dimen>`" in single display mode, one next to second in order -to creating more centered columns with formulas; the width of such columns -are controlled by the <dimen> parameter. -Or, you can give an exception for several lines: - -\begtt \catcode`\<=13 -$$\displaylines to 10cm {<formula>\hfill \cr - <formula>\cr - <formula>\cr - \hfill <formula>} -$$ -\endtt -The example above gives similar result as the \LaTeX/ `multline` environment: -$$\displaylines to \hsize { - (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \hfill \cr - = 3x^9 + 3x^5 + 15x^3 + 4x^8 + 4x^4 + 20x^2 + 5x^7 + 5x^3 + 25x - + 6x^6 + 6x^2 + 30 = \cr - \hfill = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. } -$$ - - -\secc[elines] The `\eqalign` macro - -The \ii .eqalign \iis .eqalign {{\code{\\eqalign}}} usage is: -\begtt \catcode`\<=13 -$$ \eqalign { <left-side> & <right-side> \cr - <left-side> & <right-side> \cr - ... \cr - <left-side> & <right-side> -} $$ -\endtt -The `\vcenter` box is created with two columns, left column is right aligned -and right column is left aligned. Example: - -\vbox{ -\begtt -$$ \eqalign{ - x + 2y + 3z &= 600 \cr - 12x + y - 3z &= 7 \cr - 4x - y + 5z &= -5 \cr -} $$ -\endtt -\vskip-5.7\baselineskip -{\hsize=1.35\hsize -$$ \eqalign{ - x + 2y + 3z &= 600 \cr - 12x + y - 3z &= 7 \cr - 4x - y + 5z &= -5 \cr -} $$}} - -\bigskip\noindent -The tab \"`&`" should be used just before a relation, i.e. `&=` is right, `=&` -is wrong. All lines are aligned to the used tab. - -Maybe you want more precise alignment in the example above. You can use -`\phantom`: - -\par\nobreak\vbox{ -\begtt -$$ \def\1{\phantom1} \def\+{\phantom+} - \eqalign{ - x + 2y + 3z &= 600 \cr - 12x + \1y - 3z &= \+7 \cr - 4x - \1y + 5z &= -5 \cr -} $$ -\endtt -\vskip-5.7\baselineskip -{\hsize=1.35\hsize -$$ \def\1{\phantom1} \def\+{\phantom+} - \eqalign{ - x + 2y + 3z &= 600 \cr - 12x + \1y - 3z &= \+7 \cr - 4x - \1y + 5z &= -5 -} $$}} -\bigskip -Another typical usage of the `\eqalign` macro: - -\begtt \typosize[10/12] -$$ \eqalign{ - p(x)\,q(x) &= (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr - &= 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. -} $$ -\endtt -$$ \eqalign{ - p(x)\,q(x) &= (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr - &= 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. -} $$ - -In \OpTeX/, \new\OpTeX/ -the `\eqalign` macro is more flexible. You can set the -`\baselineskip` value by the \x`\eqlines` parameter and math style -by the \x`\eqstyle` parameter. -For example, you need to put the system of \"equations" as a subscript of a sum -operator: -\begtt \typosize[10/12] \adef/{} -$$ - \sum/_{\eqlines{\baselineskip=.7\baselineskip}\eqstyle{\scriptstyle}\eqalign{ - i &\in A \cr - \quad j &\in B\cup C \cr - m &\in C }} - i + j + m -$$ -\endtt -$$ - \sum_{\eqlines{\baselineskip=.7\baselineskip}\eqstyle{\scriptstyle}\eqalign{ - i &\in A \cr - \quad j &\in B\cup C \cr - m &\in C }} - i + j + m -$$ - -\indent \new\OpTeX/ -You can write more equation systems one next second: -\begtt -$$\eqalign{ - x + y + z &= 1 && a + b + c &= -1 \cr - u + v &= 20 && f + g &= -20 \cr - i &= j -}$$ -\endtt -You can use the third column for centered equations -without aligning point. For example: -\begtt \catcode`\<=13 -$$ \left( \eqspace=0pt \eqalign{&& <first equation>\cr - && <second equation>} \right) $$ -\endtt -The \x`\eqspace` is additional space used in the third column to separate -equation systems one next second. - -\new \OpTeX/ -\OpTeX/ extensions summary: -\begitems -* `\eqlines` and `\eqstyle` set baselineskip and math style of the formulas. -* `\eqalign` allows more than two columns: - The first column is right-aligned (no space). The second is left-aligned (no space). - The third column (if used) - is centered with `\eqspace/2` at the left and right boundary of the column. - The fourth is the same as the first. The fifth is the same as second etc. The number - of columns that can be used in `\eqalign` is unlimited. -\enditems - -\secc The `\eqalign` macro with references - -You can give common mark to whole equation system by -`$$\eqalign{<data>}\eqno <mark>$$`. If you want to give marks to individual -lines of the equation system, then you can use another macro: -\x`\eqalignno`. The usage is similar as `\eqalign` but the -third column (if used) is intended to the equation mark. Example: - -\begtt -$$ \eqalignno{ - x + 2y + 3z &= 600 & \rm(A) \cr - 12x + y - 3z &= 7 & \rm(B) \cr - 4x - y + 5z &= -5 & \rm(C) \cr -} $$ -\endtt -\vskip-\baselineskip -$$ \eqalignno{ - x + 2y + 3z &= 600 & \rm(A) \cr - 12x + y - 3z &= 7 & \rm(B) \cr - 4x - y + 5z &= -5 & \rm(C) \cr -} $$ - -The `\leqalignno` macro is similar to `\eqalignno` but the marks are at the left -margin. The \OpTeX/ extensions of `\eqalign` are not available in -`\eqalignno` nor `\leqalignno` macros. - -\new \OpTeX/ -You can use auto-generated marks by `\eqmark` macro: -`$$\eqalign{<data>}\eqmark$$` or: -\begtt -$$ \eqalignno{ - x + 2y + 3z &= 600 & \eqmark[A] \cr - 12x + y - 3z &= 7 & \eqmark[B] \cr - 4x - y + 5z &= -5 & \eqmark[C] \cr -} $$ -\endtt - - -\sec Concept of loading math fonts - -\secc[fams] Math families - -\TeX/ can use more than one math font in math mode. This was a -necessity in the old days when only 128-characters fonts existed. -Each math font used in math mode has its \ii math/family {\em math family} represented by a number. -Math family is a collection of three (almost) equal fonts in three sizes: -first for `\textstyle` and `\displaystyle`, second for `\scriptstyle` -and third for `\scriptscriptstyle`. - -\new Unicode -When Unicode math font is loaded then it includes all three optical sizes and -all characters needed for typesetting math formula. -Theoretically, we can use only one math family with this single font. But more math families -(i.e.\ more fonts in math mode) is still possible. You can combine -characters from more fonts (Unicode fonts and old TFM fonts together) in one math formula. - -\new \OpTeX/ -\OpTeX/ loads the main Unicode math font into math family 1. The math -families 2 and 3 are reserved for specific \TeX/nical reasons, family 4 is -used for `\script` font and families 5, 6, 7, etc. can be used by user for -loading more fonts. The default macro for loading math fonts looks like: - -\begtt \typosize[10/12] -\_def\_normalunimath{% - \_loadumathfamily 1 {\_unimathfont}{} % Main Unicode math font - \_loadmathfamily 4 rsfs % \script (old TFM font) - \_setunimathdimens % set dimen parameters used in math formulas internally -}% -\let\_normalmath=\_normalunimath % this is done when Unicode math is initialized -\endtt -% -Whenever \OpTeX/ needs to resize math fonts (for example in footnotes or -titles), it calls the `\_normalmath` macro to reload all math -families to the desired size. If you want to add the next font, you can add -`\_loadunimathfamily <family> {<Unicode-font>}{<features>}` or -`\_loadmathfamily <family> <TFM-font>` into the `\_normalmath` macro. -The example in section~\ref[newfam] shows how to do it. - -\secc Two variants of math fonts: normal and bold - -All math formulas in the whole document need only one Unicode font (or only one collection -of math fonts as mentioned in section~\ref[fams]). But this -is not really true if titles are in bold font. If a math formula is present in -such a bold title then all characters of this formula must be bolder. -For example \"normal" variables must be in bold italic in titles, symbols -like `+` `=` must be bold and \"normal bold" letters -(e.g., indicating vectors in math formula) must be extra bold in titles. -It means that all fonts from the collection of math fonts must be bolder. -We need a second collection of math fonts with bolder -shape. Unfortunately, it is not always available. - -\new \OpTeX/ -If you have bold variant of used Unicode math font, then you can use -\ii .loadmath \iis .loadmath {{\code{\\loadmath}}} \x`\loadboldmath` command, for example: -\begtt -\loadmath {[xitsmath-regular]} -\loadboldmath {[xitsmath-bold]} \to {[xitsmath-regular]} -\endtt -% -\OpTeX/ uses `\_normalmath` macro for loading collection of math fonts in -\"normal" cases and `\_boldmath` macro for bold titles. The font declared by -\x`\loadboldmath` is used in second case. But if the bold variant of the font is -not available (this is unfortunately more typical), then \OpTeX/ uses faked -bold of main Unicode math font (the `embolden` internal font feature is -used). So, the default `\_boldmath` macro defined by \OpTeX/ looks like: - -\begtt \typosize[10/12] -\_def\_boldunimath{% - \_ifx\_unimathboldfont \_undefined - \_loadumathfamily 1 {\_unimathfont}{embolden=1.7;} % Main faked bold - \_else - \_loadumathfamily 1 {\_unimathboldfont}{} % Main real bold font - \_fi - \_loadmathfamily 4 rsfs % rsfs in not in bold, unfortunately - \_setunimathdimens -}% -\let\_boldmath=\_boldunimath % this is done when Unicode math is initialized -\endtt - -\secc[newfam] Example of using additional math font - -The font `bbold10.tfm` includes double stroked characters, for example, -double stroked plus, double stroked Greek letters and digits. -Try to run `pdftex testfont`, then answer the question about the name of the -font: `bbold10` and then type command `\table\end`. The `testfont.pdf` is -printed with the table of characters of this font. -Most of these characters cannot be found in Unicode math fonts. - -\new \OpTeX/ -We show an example of how to add this font to the collection of used math fonts. -We can re-define the `\_normalmath` macro by: -\begtt \typosize[10/12] -\addto\_normalmath {\_loadmathfamily 5 bbold } - -\_regtfm bbold 0 bbold5 5.5 bbold6 6.5 bbold7 7.5 bbold8 8.5 bbold9 - 9.5 bbold10 11.1 bbold12 15 bbold17 * % using all bbold*.tfm -\_normalmath % reload the math fonts collection -\endtt -% -The string \"`bbold`" is declared by `\_regtfm` as a collection of all -`bbold*.tfm` fonts, the optical sizes are supported. - -\addto\_normalmath {\_loadmathfamily 5 bbold } -\_regtfm bbold 0 bbold5 5.5 bbold6 6.5 bbold7 7.5 bbold8 8.5 bbold9 - 9.5 bbold10 11.1 bbold12 15 bbold17 * % using all bbold*.tfm -\_normalmath -\Umathchardef \bbplus 2 5 "2B -\Umathchardef \bble 3 5 "3C -\Umathchardef \bbge 3 5 "3E - -Finally, we must to declare new \TeX/ sequences for accessing the characters -from the new font, for example: - -\begtt \typosize[10/12] -\Umathchardef \bbplus 2 5 "2B -\Umathchardef \bble 3 5 "3C -\Umathchardef \bbge 3 5 "3E -\endtt -% -The \x`\Umathchardef` \TeX/ primitive declares new \TeX/ sequence used in math -typesetting. The first parameter is a class number (2 means Bin, 3 means Rel, -see the table in the section~\ref[class]). The second parameter is a math -family number. It is 5, see the redefinition of the `\_normalmath` macro above. -The third parameter is a slot in the font. Now you can try to use these characters: -$$ - `a \bbplus b \bbge c` \quad \hbox{gives} \quad a \bbplus b \bbge c. -$$ -% -Maybe, you want to declare a special math selector which can be used as -`$\bball a+b>c$` in order to get $\bbchar a \bbplus b \bbge c$. -Then you can define: - -\begtt \typosize[10/12] -\def\bball {\bbchar \Umathcodenum `+ \bbplus - \Umathcodenum `> \bbge - \Umathcodenum `< \bble } -\endtt - -If you want to add all double stroked Greek letters into `\bball` -selector, then you can do something like this: - -\begtt \typosize[10/12] -\def\setbbgreek #1 {\tmpnum=#1\xargs\setbbgreekA} -\def\setbbgreekA #1{\Umathcode \_ea`#1 0 5 \tmpnum \advance\tmpnum by1 } - -\addto\bball {% - \setbbgreek "0B \alpha \beta \gamma \delta \epsilon \zeta \eta - \theta \iota \kappa \lambda \mu \nu \xi \pi \rho \sigma - \tau \upsilon \phi \chi ; - \setbbgreek "7F \omega ; - \setbbgreek "00 \Gamma \Delta \Theta \Lambda \Xi \Pi \Sigma \Upsilon - \Phi \Psi \Omega ; } -\endtt -% -The \x`\Umathcode`` <input-code> <class> <family> <font-slot>` primitive is used -here. The control sequences `\alpha`, `\beta`, `\gamma` etc. are macros which expand -to the Unicode character of appropriate (non-math) Greek letter. We set the -Umathcode to such character, for example -\code{\\Umathcode `}$\_rmgreek\alpha$` 0 5 "0B` is processed. - -The bold variant of the font `bbold*.tfm` is not available, unfortunately. -We have to settle for normal version of the font in the `\_boldmath` macro: - -\begtt \typosize[10/12] - \addto \_boldmath {\_loadmathfamily 5 bbold } -\endtt - -Another approach of using more Unicode math fonts in a single formula is -shown in -\ulink[http://petr.olsak.net/optex/optex-tricks.html\#addumathfont]{OpTeX trick 0030}. - -\sec Index - -Control sequences listed at pages \pgref[listA]--\pgref[listB] are not -mentioned here again. - -\begmulti 3 -\makeindex -\endmulti - -\bye diff --git a/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex b/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex deleted file mode 100644 index 4ae25a9c7ec..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex +++ /dev/null @@ -1,290 +0,0 @@ -%% This is part of the OpTeX project, see http://petr.olsak.net/optex - -% This file is read from optex-doc.tex -% Use: optex optex-doc -% (three times) to create whole documentation including all references and the index. - -\load [doc.opm] - -\thisoutline {TECHNICAL DOCUMENTATION} - -\chap Technical documentation - -This documentation is written in the source files `*.opm` between -the `\_doc` and `\_cod` pairs or after the `\_endcode` command. -When the format is generated by -\begtt -luatex -ini optex.ini -\endtt -then the text of the documentation is ignored and the format `optex.fmt` is -generated. On the other hand, if you run -\begtt -optex optex-doc.tex -\endtt -then the same `*.opm` files are read when the second chapter of this -documentation is printed. - -A knowledge about \TeX/ is expected from the reader. -You can see a short document -\ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]{\TeX/ in a Nutshell} -or more detail -\ulink[https://eijkhout.net/texbytopic/texbytopic.html]{\TeX/ by topic}. - -Notices about hyperlinks. -If a control sequence is printed in red color in this documentation then -this denotes its \"main documentation point". Typically, the listing where -the control sequence is declared follows immediately. If a control sequence is -printed in the blue color in the listing or in the text -then it is an active link that points (usually) to the main documentation point. -The main documentation point can be an active link that points to a previous -text where the control sequence was -mentioned. Such occurrences are active links to the main documentation point. - -\sec[init] The main initialization file - -The `optex.ini` file is read as the main file when the format is generated. - -{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip} - \def\docfile{optex.ini} - -\verbinput (-4) optex.ini -% -Category codes are set first. Note that the `_` is set to category code -\"letter", it can be used as a part of control sequence names. -Other category codes are set as in the plain \TeX/. - -\verbinput (6-20) optex.ini -% -The \`\optexversion` and \`\fmtname` are defined. - -\verbinput (22-25) optex.ini -% -We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character -is set as `\newlinechar`. - -\verbinput (27-36) optex.ini -% -The basic macros for macro file syntax is defined, i.\,e.\ -`\_endcode`, `\_doc` and `\_cod`. -The `\_codedecl` will be re-defined later. - -\verbinput (38-42) optex.ini -% -Individual `*.opm` macro files are read. - -\verbinput (44-87) optex.ini -% -The file `optex.lua` is embedded into the format as byte-code. -It is documented in section~\ref[lua]. - -\verbinput (89-92) optex.ini - -The `\everyjob` register is initialized and the format is saved by -the `\dump` command. - -\verbinput (94-102) optex.ini - -} - -\printdoctail prefixed.opm -\secc The implementation of the namespaces -\printdoc prefixed.opm - -\sec pdf\TeX/ initialization -\printdoctail luatex-ini.opm -\printdoc luatex-ini.opm - -\sec Basic macros -We define first bundle of basic macros. -\printdoc basic-macros.opm - -\sec Allocators for \TeX/ registers -\printdoctail alloc.opm -\printdoc alloc.opm - -\sec If-macros, loops, is-macros -\printdoc if-macros.opm - -\sec Setting parameters -\printdoctail parameters.opm -\printdoc parameters.opm - -\sec More \OpTeX/ macros -The second bundle of \OpTeX/ macros is here. -\printdoc more-macros.opm - -\sec Using key=value format in parameters -\printdoctail keyval.opm -\printdoc keyval.opm - -\sec Plain \TeX/ macros -All macros from plain \TeX/ are rewritten here. -Differences are mentioned in the documentation below. -\printdoc plain-macros.opm - -\sec Preloaded fonts for text mode -\printdoctail fonts-preload.opm -\printdoc fonts-preload.opm - -\printdoctail fonts-resize.opm -\printdoc fonts-resize.opm - -\printdoctail fonts-select.opm -\secc Implementation of the Font Selection System -\printdoc fonts-select.opm - -\sec [math-preload] Preloaded fonts for math mode -\printdoctail math-preload.opm -\printdoc math-preload.opm - -\sec[math-macros] Math macros -\printdoc math-macros.opm - -\sec Unicode-math fonts -\printdoctail math-unicode.opm - -\sec[opmac-fonts] Scaling fonts in document (high-level macros) -These macros are documented in section~\ref[sizes] from the user point of view. -\printdoc fonts-opmac.opm - -\sec[output] Output routine -\printdoctail output.opm -\printdoc output.opm - -\sec Margins -The `\margins` macro is documented in the section~\ref[marg]. -\printdoc margins.opm - -\sec[colors] Colors -\printdoctail colors.opm -\printdoc colors.opm - -\sec[ref-file] The \code{.ref} file -\printdoctail ref-file.opm -\printdoc ref-file.opm - -\sec[references] References -\printdoctail references.opm -\printdoc references.opm - -\sec Hyperlinks -\printdoctail hyperlinks.opm -\printdoc hyperlinks.opm - -\sec[maketoc] Making table of contents -\printdoc maketoc.opm - -\sec PDF outlines -\secc Nesting PDF outlines -\printdoctail outlines.opm -\printdoc outlines.opm -\secc Strings in PDF outlines -\printdoctail pdfuni-string.opm -\printdoc pdfuni-string.opm - -\sec[sections] Chapters, sections, subsections -\printdoc sections.opm - -\sec[lists] Lists, items -\printdoc lists.opm - -\sec Verbatim, listings -\secc[verb] Inline and \"display" verbatim -\printdoc verbatim.opm -\secc[hisyntax] Listings with syntax highlighting -\printdoctail hi-syntax.opm -\printdoc hi-syntax.opm - -\sec Graphics -\printdoctail graphics.opm -\printdoc graphics.opm - -\sec[table] The \code{\\table} macro, tables and rules -\printdoctail table.opm -\secc[table.impl] Implemetation of the \code{\\table} macro and friends -\printdoc table.opm - -\sec Balanced multi-columns -\printdoc multicolumns.opm - -\sec Citations, bibliography -\secc[bib] Macros for citations and bibliography preloaded in the format -\printdoc cite-bib.opm -\secc[usebib] The \code{\\usebib} command -\printdoctail usebib.opm -\secc The \code{usebib.opm} macro file loaded when \code{\\usebib} is used -\printdoc usebib.opm - -\secc[isobib] Usage of the \code{bib-iso690} style -{\everyintt={\catcode`\<=13 \visiblesp} -\printdoctail bib-iso690.opm } - -\secc Implementation of the \code{bib-iso690} style -\printdoc bib-iso690.opm - -\sec[makeindex] Sorting and making Index -\printdoc makeindex.opm - -\sec[fnotes] Footnotes and marginal notes -\printdoc fnotes.opm - -\sec Styles - \OpTeX/ provides three styles: `\report`, `\letter` and `\slides`. - Their behavior is documented in user part of the manual in the section - \ref[styles] and `\slides` style (for presentations) is documented in - `op-slides.pdf` which is an example of the presentation. -\secc \code{\\report} and \code{\\letter} styles -\printdoc styles.opm -\secc[slides] \code{\\slides} style for presentations -\printdoc slides.opm - -\sec Logos -\printdoc logos.opm - -\sec Multilingual support -\secc Lowercase, uppercase codes -\printdoctail uni-lcuc.opm -\secc Hyphenations -\printdoc hyphen-lan.opm -\printdoctail hyphen-lan.opm -\secc[langphrases] Multilingual phrases and quotation marks -\printdoc languages.opm - -\sec Other macros -Miscellaneous macros are here. -\printdoc others.opm - -\sec[lua] Lua code embedded to the format - -The file `optex.lua` is loaded into the format in `optex.ini` as byte-code -and initialized by `\everyjob`, see section~\ref[init]. - -The file implements part of the functionality from `luatexbase` namespace, -nowadays defined by \LaTeX/ kernel. `luatexbase` deals with modules, -allocators, and callback management. Callback management is a nice extension -and is actually used in \OpTeX/. Other functions are defined more or less just -to suit luaotfload's use. - -\newtoks \_hisyntaxlua -\_hisyntaxlua={% - \_hicolor C \Green - \_replfromto {--}{^^J} {\z C{--#1}^^J}% -} - -{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip} - \commentchars-- \def\docfile{optex.lua} \ttline=-1 - \_def\_printcomments{\_medskip - {\_catcodetable0 \_typosize[10/12]\_everypar={}\_scantextokens\_ea{\_vcomments}\par}% - \_bigskip - } - -\verbinput \hisyntax{lua} (4-) optex.lua -} - - -\sec Printing documentation -\printdoctail doc.opm -\printdoc doc.opm - -\enddocument - diff --git a/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex b/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex deleted file mode 100644 index a70cedcf4d8..00000000000 --- a/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex +++ /dev/null @@ -1,2019 +0,0 @@ -%% This is part of the OpTeX project, see http://petr.olsak.net/optex - -% This file is read from optex-doc.tex -% Use: optex optex-doc (three times) to create whole documentation. - -\let\new=\relax - -\sec Starting with \OpTeX/ -%%%%%%%%%%%%%%%%%%%%%%%%% - -\new -\OpTeX/ is compiled as a format for \LuaTeX/. Maybe there is a command -`optex` in your \TeX/ distribution. Then you can write into the command line - -\begtt -optex document -\endtt -% -You can try to process `optex op-demo` or `optex optex-doc`. - -If there is no `optex` command, see more information about installation -\OpTeX/ at \url{http://petr.olsak.net/optex}. - -A minimal document should be - -\begtt -\fontfam[LMfonts] -Hello World! \bye -\endtt - -The first line \~`\fontfam[LMfonts]` tells that Unicode Latin Modern -fonts (derived from Computer Modern) are used. If you omit this line then -preloaded Latin Modern fonts are used but preloaded fonts cannot be in -Unicode\fnote -{This is a technical limitation of \LuaTeX/ for fonts downloaded in formats: -only 8bit fonts can be preloaded.}. -So the sentence `Hello World` will be OK without the first line, but you -cannot print such sentence in other languages (for example `Ahoj světe!`) -where Unicode fonts are needed -because the characters like `ě` are not mapped correctly in preloaded -fonts. - -A somewhat larger example with common settings should be: - -\begtt \catcode`!=0 -\fontfam[Termes] % selecting Unicode font family Termes (section !ref[fontfam]) -\typosize[11/13] % setting default font size and baselineskip (sec. !ref[sizes]) -\margins/1 a4 (1,1,1,1)in % setting A4 paper, 1 in margins (section !ref[marg]) -\cslang % Czech hyphenation patterns (section !ref[lang]) - -Tady je zkušební textík v českém jazyce. -\bye -\endtt -% -You can look at `op-demo.tex` file for a more complex, but still simple example. - -\sec Page layout -%%%%%%%%%%%%%%%% - -\secc[marg] Setting the margins -%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -The \^`\margins` command declares margins of the document. This command have -the following parameters: - -\begtt \catcode`\<=13 -\margins/<pg> <fmt> (<left>,<right>,<top>,<bot>)<unit> - example: -\margins/1 a4 (2.5,2.5,2,2)cm -\endtt - -Parameters are: - -\begitems -* <pg> \dots\ `1` or `2` specifies one-page or two-pages design. -* <fmt> \dots\ paper format (a4, a4l, a5, letter, etc. or user defined). -* <left>, <right>, <top>, <bot> \dots\ gives the amount of left, right, - top and bottom margins. -* <unit> \dots\ unit used for values <left>, <right>, <top>, <bot>. -\enditems - -Each of the parameters <left>, <right>, <top>, <bot> can be empty. -If both <left> and <right> are nonempty then `\hsize` is set. Else `\hsize` -is unchanged. If both <left> and <right> are empty then typesetting area is -centered in the paper format. The analogical rule works when <top> or <bot> -parameter is empty (`\vsize` instead `\hsize` is used). Examples: - -\begtt -\margins/1 a4 (,,,)mm % \hsize, \vsize untouched, - % typesetting area centered -\margins/1 a4 (,2,,)cm % right margin set to 2cm - % \hsize, \vsize untouched, vertically centered -\endtt - -If `<pg>=1` then all pages have the same margins. If `<pg>=2` then the -declared margins are true for odd pages. The margins at the even pages are -automatically mirrored in such case, it means that <left> is replaced by -<right> and vice versa. - -\OpTeX/ declares following paper formats: a4, a4l (landscape~a4), -a5, a5l, a3, a3l, b5, letter and user can declare another own format by \~`\sdef`: - -\begtt -\sdef{_pgs:b5l}{(250,176)mm} -\sdef{_pgs:letterl}{(11,8.5)in} -\endtt - -The `<fmt>` can be also in the form `(<width>,<height>)<unit>` where `<unit>` is -optional. If it is missing then `<unit>` after margins specification is -used. For example: - -\begtt -\margins/1 (100,200) (7,7,7,7)mm -\endtt -% -declares the paper 100$\times$200\,mm with all four margins 7\,mm. The spaces -before and after <fmt> parameter are necessary. - -The command \^`\magscale[<factor>]` scales the whole typesetting area. -\new The fixed point of such scaling is the upper left corner of the paper sheet. -Typesetting (breakpoints etc.) is unchanged. All units are relative after -such scaling. Only paper format's dimensions stay unscaled. Example: - -\begtt -\margins/2 a5 (22,17,19,21)mm -\magscale[1414] \margins/1 a4 (,,,)mm -\endtt -% -The first line sets the `\hsize` and `\vsize` and margins for final -printing at a5 format. The setting on the second line centers the scaled -typesetting area to the true a4 paper while breaking points for paragraphs -and pages are unchanged. It may be usable for -review printing. After the review is done, the second line can be commented out. - -\secc Concept of the default page -%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\OpTeX/ uses \"output routine" for page design. -It is very similar to the Plain \TeX/ output routine. -There is \^`\headline` followed by \"page body" followed by -\^`\footline`. The \^`\headline` is empty by default and it can be used -for running headers repeated on each page. The \^`\footline` prints -centered page number by default. You can set the \^`\footline` to empty -using \^`\nopagenumbers` macro. - -The margins declared by \^`\margins` macro (documented in the previous -section~\ref[marg]) is concerned to the page body, -i.e.\ the \^`\headline` and \^`\footline` are placed to the top and bottom -margins. - -The distance between the \^`\headline` and the top of the page body is given by -the \^`\headlinedist` register. The distance between bottom of the page body and -the \^`\footline` is given by \^`\footlinedist`. The default values are: - -\begtt -\headline = {} -\footline = {\_hss\_rmfixed \_folio \_hss} % \folio expands to page number -\headlinedist = 14pt % from baseline of \headline to top of page body -\footlinedist = 24pt % from last line in pagebody to baseline of footline -\endtt - -The page body should be divided into top insertions (floating tables and -figures) followed by a real text and followed by footnotes. -Typically, the only real text is here. - -The \^`\pgbackground` tokens list is empty by default but it can be used for -creating a background of each page (colors, picture, watermark for example). -The macro \^`\draft` uses this register and puts big text DRAFT as a watermark -to each page. You can try it. - -More about the page layout is documented in sections~\ref[oparams] and~\ref[output]. - -\secc Footnotes and marginal notes -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -The Plain \TeX/'s macro \^`\footnote` can be used as usual. But a new macro -\^`\fnote{<text>}` is defined. The footnote mark is added automatically and it -is numbered -\new -on each chapter from one\fnote -{You can declare \^`\fnotenumglobal` if you want footnotes numbered in whole -document from one or \^`\fnotenumpages` if you want footnotes numbered at each -page from one. Default setting is \^`\fnotenumchapters`}. -The <text> is scaled to 80 \%. -User can redefine footnote mark or scaling, as shown in the section~\ref[fnotes]. - -The \^`\fnote` macro is fully applicable only in \"normal outer" paragraph. -It doesn't work inside boxes (tables, for example). If you are solving such -a case then you can use the command \^`\fnotemark``<numeric-label>` inside the box: only the -footnote mark is generated here. When the box is finished you can use -\^`\fnotetext{<text>}`. This macro puts the <text> to the footnote. -The <numeric-label> has to be `1` if only one such command is in the box. -Second \^`\fnotemark` inside the same box has to have the parameter `2` etc. -The same number of \^`\fnotetext`s have to be written -after the box as the number of \^`\fnotemark`s inserted inside the box. -Example: - -\begtt -Text in a paragraph\fnote{First notice}... % a "normal" footnote -\table{...}{...\fnotemark1...\fnotemark2...} % two footnotes in a box -\fnotetext{Second notice} -\fnotetext{Third notice} -... -\table{...}{...\fnotemark1...} % one footnote in a box -\fnotetext{Fourth notice} -\endtt - -The marginal note can be printed by the \^`\mnote{<text>}` macro. The <text> -is placed to the right margin on the odd pages and it is placed to the left -margin on the even pages. This is done after second \TeX{} run because the -relevant information is stored in an external file and read from it again. -If you need to place the notes only to the fixed margin write -\^`\fixmnotes\right` or \^`\fixmnotes\left`. - -The <text> is formatted as a little paragraph with the maximal width -\^`\mnotesize` ragged left on the left margins or ragged right on the right -margins. The first line of this little paragraph has its vertical position -given by the position of \^`\mnote` in the text. The exceptions are possible -by using the `up` keyword: \~`\mnote`` up<dimen>{<text>}`. -You can set such <dimen> to each \^`\mnote` manually in final printing -in order to margin notes do not overlap. The positive value of <dimen> -shifts the note up and negative value shifts it down. For example -\^`\mnote`` up 2\baselineskip{<text>}` shifts this marginal note two lines up. - -\sec Fonts -%%%%%%%%%% - -\secc[fontfam] Font families -%%%%%%%%%%%%%%%%%%%%%%% - -You can select the font family by \^`\fontfam[<Family-name>]`. -The argument <Family-name> is case insensitive and spaces are ignored in it. For -example, \^`\fontfam[LM Fonts]` is equal to \^`\fontfam[LMfonts]` and it is equal -to \^`\fontfam[lmfonts]`. Several aliases are prepared, thus -\^`\fontfam[Latin Modern]` can be used for loading Latin Modern family too. - -If you write \^`\fontfam[?]` then all font families registered in \OpTeX/ -are listed on the terminal and in the log file. -If you write \^`\fontfam[catalog]` then a catalog of all fonts registered in -\OpTeX/ and available in your \TeX/ system is printed. The instructions -on how to register your own font family are appended in the catalog. - -If the family is loaded then {\em font modifiers} applicable in such font family -are listed on the terminal: (`\caps`, `\cond` for example). -And there are four basic {\em variant selectors} (\^`\rm`, \^`\bf`, \^`\it`, \^`\bi`). -The usage of variant selectors is the same as in Plain \TeX: -`{\it italics text}`, `{\bf bold text}` etc. - -The font modifiers (`\caps`, `\cond` for example) can -be used before a variant selector and they -can be (independently) combined: `\caps\it` or `\cond\caps\bf`. The -modifiers keep their internal setting until the group ends or until another -modifier that negates the previous feature is used. So -`{\caps \rm First text \it Second text}` -gives {\caps \rm First text \it Second text}. - -The font modifier without following variant selector does not change the font -actually, it only prepares data used by next variant selectors. -There is one special variant selector \^`\currvar` which does not change the -selected variant but reloads the font due to (maybe newly -specified) font modifier(s). - -The context between variants \^`\rm` $\leftrightarrow$ \^`\it` and -\^`\bf` $\leftrightarrow$ \^`\bi` is kept by the \^`\em` -macro (emphasize text). -It switches from current \^`\rm` to \^`\it`, from current \^`\it` to \^`\rm`, from -current \^`\bf` to \^`\bi` and from current \^`\bi` to \^`\bf`. -The italics correction `\/` is inserted automatically, if needed. Example: - -\begtt -This is {\em important} text. % = This is {\it important\/} text. -\it This is {\em important} text. % = This is\/ {\rm important} text. -\bf This is {\em important} text. % = This is {\bi important\/} text. -\bi This is {\em important} text. % = This is\/ {\bf important} text. -\endtt - -\new -More about the \OpTeX/ Font Selection System is written in the technical -documentation in the section~\ref[fontsystem]. -You can mix more font families in your document, you can -declare your own variant selectors or modifiers, etc. - -\secc[sizes] Font sizes -%%%%%%%%%%%%%%%%%%%%% - -The command \^`\typosize[<fontsize>/<baselineskip>]` sets the font size of text and -math fonts and baselineskip. If one of these two parameters is empty, the -corresponding feature stays unchanged. Don't write the unit of these -parameters. The unit is internally set to \^`\ptunit` which is 1pt by default. -You can change the unit by the command \^`\ptunit=<something-else>`, -for instance \^`\ptunit=1mm` enlarges all font sizes declared by \^`\typosize`. -Examples: - -\begtt -\typosize[10/12] % default of Plain TeX -\typosize[11/12.5] % font 11pt, baseline 12.5pt -\typosize[8/] % font 8pt, baseline unchanged -\endtt - -The commands for font size setting described in this section -have local validity. If you put them into a group, -the settings are lost when the group is finished. If you set -something relevant with paragraph shape (baselineskip given by -\^`\typosize` for example) then you must first finalize the -paragraph before closing the group: -`{\typosize[12/14] ...<text of paragraph>... \par}`. - -The command \^`\typoscale[<font-factor>/<baselineskip-factor>]` -sets the text and math fonts -size and baselineskip as a multiple of the current fonts size and -baselineskip. The factor is written in \"scaled"-like way, it means that 1000 -means factor one. The empty parameter is equal to the parameter 1000, -i.e. the value stays unchanged. Examples: - -\begtt -\typoscale[800/800] % fonts and baselineskip re-size to 80 % -\typoscale[\magstep2/] % fonts bigger 1,44times (\magstep2 expands to 1440) -\endtt - -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 -saved in registers \^`\mainfosize` and \^`\mainbaselineskip`. - -\new -The \^`\typoscale` command does scaling with respect to current values by default. -If you want to do it with respect to the main values, type \^`\scalemain` immediately -before \^`\typoscale` command. - -\begtt -\typosize[12/14.4] % first usage in document, sets main values internally -\typosize[15/18] % bigger font -\scalemain \typoscale[800/800] % reduces from main values, no from current. -\endtt - -The \^`\typosize` and \^`\typoscale` macros initialize the font family by `\rm`. -You can re-size only the current font by the command -\^`\thefontsize[<font-size>]` or the font can be rescaled by -\^`\thefontscale[<factor>]`. These macros don't change math fonts sizes nor -baselineskip. - -\new -There is \"low level" \^`\setfontsize{<size-spec>}` command which behaves like -a font modifier and sets given font size used by next variant selectors. -It doesn't change the font size immediately, but the following variant selector -does it. For example \^`\setfontsize{at15pt}`\^`\currvar` sets current variant to 15pt. - -If you are using a font family with \"optical sizes feature" (i.\,e.\ there -are more recommended sizes of the same font which are not scaled -linearly; a good example is Computer Modern aka Latin Modern fonts) -then the recommended size is selected by all mentioned commands automatically. - -More information about resizing of fonts is documented in the -section~\ref[setfontsize]. - -\secc Typesetting math -%%%%%%%%%%%%%%%%%%%%% - -See the additional document -\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf] -{Typesetting Math with \OpTeX/} for more details about this issue. - -\OpTeX/ preloads a collection of 7bit Computer Modern math fonts -and AMS fonts in its format for math typesetting. -You can use them in any size and in the \^`\boldmath` variant. -% -\new -Most declared text font families (see \^`\fontfam` in the section~\ref[fontfam]) -are configured with a recommended Unicode -math font. This font is automatically loaded unless you specify -\^`\noloadmath` before first \^`\fontfam` command. See log file for more -information about loading text font family and Unicode math fonts. If you -prefer another Unicode math font, specify it by \^`\loadmath{[<font-file>]}` -or \^`\loadmath{<font-name>}` before first \^`\fontfam` command. - -Hundreds math symbols and operators like in AMS\TeX/ are accessible. -For example `\alpha` $\alpha$, `\geq`~$\geq$, `\sum` $\sum$, -`\sphericalangle` $\sphericalangle$, `\bumpeq`, $\bumpeq$. See AMS\TeX/ -manual or -\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf] -{Typesetting Math with \OpTeX/} for complete list of math symbols. - -The following math alphabets are available: - -\begtt \catcode`\$=3 \catcode`/=0 \medmuskip=0mu \adef{ }{ } -\mit % mathematical variables $abc-xyz,ABC-XYZ$ -\it % text italics $/it abc-xyz,ABC-XYZ$ -\rm % text roman $/rm abc-xyz,ABC-XYZ$ -\cal % normal calligraphics $/cal ABC-XYZ$ -\script % script $/script ABC-XYZ$ -\frak % fracture $/frak abc-xyz,ABC-XYZ$ -\bbchar % double stroked letters $/bbchar ABC-XYZ$ -\bf % sans serif bold $/bf abc-xyz,ABC-XYZ$ -\bi % sans serif bold slanted $/bi abc-xyz,ABC-XYZ$ -\endtt - -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 -matrices. You can re-declare them, see section~\ref[unimath-codes] where -definitions of Unicode math variants of \^`\bf` and \^`\bi` selectors are documented. - -The math fonts can be scaled by \^`\typosize` and \^`\typoscale` macros. -Two math fonts collections are prepared: \^`\normalmath` for normal weight -and \^`\boldmath` for bold. The first one is set by default, the second one -is usable for math formulae in titles typeset in bold, for example. - -\new -You can use \^`\mathbox{<text>}` inside math mode. It behaves as `{\hbox{<text>}}` -(i.e. the <text> is printed in horizontal non-math mode) -but the size of the <text> is adapted to the context of math size (text or script or -scriptscript). - -\sec Typical elements of the document -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\secc[chap] Chapters and sections -%%%%%%%%%%%%%%%%%%%%%%%%%% - -The documents can be divided into chapters (\^`\chap`), -sections (\^`\sec`), subsections (\^`\secc`) and they can be titled -by \^`\tit` command. The parameters are separated by the end of current line (no -braces are used): - -\begtt \catcode`\<=13 -\tit Document title <end of line> -\chap Chapter title <end of line> -\sec Section title <end of line> -\secc Subsection title <end of line> -\endtt - -The chapters are automatically numbered by one number, sections by two numbers -(chapter.section), and subsections by three numbers. If there are no chapters -then sections have only one number and subsections two. - -The implicit design of the titles of chapter etc.\ is implemented in the -macros \^`\_printchap`, \^`\_printsec` and \^`\_printsecc`. A designer can simply change -these macros if he/she needs another behavior. - -The first paragraph after the title of chapter, section, and subsection is -not indented but you can type `\let`\^`\_firstnoindent=\relax` if you need all -paragraphs indented. - -If a title is so long then it breaks into more lines in the output. It is better to hint at the -breakpoints because \TeX/ does not interpret the meaning of the title. -Users can put the \^`\nl` (means newline) to the breakpoints. - -If you want to arrange a title to more lines in your source file then you can -use `^^J` at the end of each line (except the last one). -When `^^J` is used, then the reading of the title continues at the next line. -The \"normal" comment character `%` doesn't work in titles. -You can use \^`\nl`{\visiblesp` ^^J`} if you want to have corresponding lines in the source -and the output. - -The chapter, section, or subsection isn't numbered if the \^`\nonum` precedes. -And the chapter, section, or subsection isn't delivered to the table of -contents if \^`\notoc` precedes. You can combine both prefixes. - -\secc[cap] Another numbered objects -%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -Apart from chapters, sections, and subsections, there are another -automatically numbered objects: equations, captions for tables and -figures. The user can declare more numbered objects. - -If the user writes the \^`\eqmark` as the last element of the display mode then -this equation is numbered. The equation number is printed in brackets. This number -is reset in each section by default. - -If the \^`\eqalignno` is used, then user can put \^`\eqmark` to the last column -before `\cr`. For example: - -\begtt -\eqalignno{ - a^2+b^2 &= c^2 \cr - c &= \sqrt{a^2+b^2} & \eqmark \cr} -\endtt - -Another automatically numbered object is a caption which is tagged by \^`\caption/t` for -tables and \^`\caption/f` for figures. The caption text follows. -The \^`\cskip` can be used between \^`\caption` text and the real object (table -or figure). You can use two orders: `<caption>\cskip <object>` or -`<object>\cskip <caption>`. -The \^`\cskip` creates appropriate vertical space between them. Example: - -\begtt -\caption/t The dependency of the computer-dependency on the age. -\cskip -\noindent\hfil\table{rl}{ - age & value \crl\noalign{\smallskip} - 0--1 & unmeasured \cr - 1--6 & observable \cr - 6--12 & significant \cr - 12--20 & extremal \cr - 20--40 & normal \cr - 40--60 & various \cr - 60--$\infty$ & moderate} -\endtt - -This example produces: - -\medskip -\caption/t The dependency of the computer-dependency on the age. -\cskip -\noindent\hfil\table{rl}{ - age & value \crl\noalign{\smallskip} - 0--1 & unmeasured \cr - 1--6 & observable \cr - 6--12 & significant \cr - 12--20 & extremal \cr - 20--40 & normal \cr - 40--60 & various \cr - 60--$\infty$ & moderate} -\medskip - -You can see that the word \"Table" followed by a number is added by the macro -`\caption/t`. -The caption text is centered. If it occupies more lines then the -last line is centered. - -The macro \^`\caption/f` behaves like \^`\caption/t` but it is intended for -figure captions with independent numbering. -The word (Table, Figure) depends on the selected language (see -section~\ref[lang] about languages). - -If you wish to make the table or figure as a floating object, you need to use -Plain \TeX/ macros \^`\midinsert` or \^`\topinsert` terminated by \^`\endinsert`. -Example: - -\begtt -\topinsert % table and its caption printed at the top of the current page - <caption and table> -\endinsert -\endtt -% -The pair \^`\midinsert`...\^`\endinsert` prefers to put the enclosed object -to the current place. Only if this is unable due to page breaking, it -behaves like \^`\topinsert`...\^`\endinsert`. - -\new -There are five prepared counters `A`, `B`, `C`, `D` and `E`. -They are reset in each chapter and section\fnote -{This feature can be changed, see the section~\ref[sections] in the technical documentation.}. -They can be used in context of \^`\numberedpar` `<letter>{<text>}` -macro. For example: -\begtt -\def\theorem {\numberedpar A{Theorem}} -\def\corollary {\numberedpar A{Corollary}} -\def\definition {\numberedpar B{Definition}} -\def\example {\numberedpar C{Example}} -\endtt -% -Three independent numbers are used in this example. One for Theorems and Corollaries -second for Definitions and third for Examples. The user can write -`\theorem Let $M$ be...` and the new paragraph is started with the text: -{\bf Theorem 1.4.1.} Let $M$ be... -You can add an optional parameter in brackets. For example, -`\theorem [(L'Hôpital's rule)] Let $f$, $g$ be...` -is printed like {\bf Theorem 1.4.2 (L'Hôpital's rule).} Let $f$, $g$ be... - -\secc References -%%%%%%%%%%%%%%% - -Each automatically numbered object documented in -sections \ref[chap] and \ref[cap] can be referenced -\new -if optional parameter -`[<label>]` is appended to \^`\chap`, \^`\sec`, -\^`\secc`, \^`\caption/t`, \^`\caption/f` or \^`\eqmark`. The alternative syntax is -to use \^`\label[<label>]` before mentioned commands (not necessarily directly -before). The reference is realized by \^`\ref[<label>]` or \^`\pgref[<label>]`. -Example: - -\begtt -\sec[beatle] About Beatles - -\noindent\hfil\table{rl}{...} % the table -\cskip -\caption/t [comp-depend] The dependency of the comp-dependency on the age. - -\label[pythagoras] -$$ a^2 + b^2 = c^2 \eqmark $$ - -Now we can point to the section~\ref[beatle] on the page~\pgref[beatle] -or write something about the equation~\ref[pythagoras]. Finally there -is an interesting Table~\ref[comp-depend]. -\endtt - -If there are forward referenced objects then users have to run \TeX{} twice. -During each pass, the working `*.ref` file (with references data) is created -and this file is used (if it exists) at the beginning of the document. - -You can use the \^`\label[<label>]` before the `\theorem`, `\definition` etc.\ -(macros defined with `\numberedpar`) if you want to reference these numbered objects. -You can't use `\theorem[<label>]` because the optional parameter -is reserved to another purpose here. - -You can create a reference to whatever else by commands -\^`\label[<label>]`\^`\wlabel{<text>}`. The connection between <label> and -<text> is established. The \^`\ref[<label>]` will print <text>. - -By default, labels are not printed, of course. But if you are preparing a -draft version of your document then you can declare \^`\showlabels`. The labels -are printed at their destination places after such a declaration. - -\secc Hyperlinks, outlines -%%%%%%%%%%%%%%%%%%%%%%%%% - -If the command \^`\hyperlinks` `<color-in> <color-out>` is used at the beginning of -the document, then the following objects are hyperlinked in the PDF output: - -\begitems -* numbers and texts generated by \^`\ref` or \^`\pgref`, -* numbers of chapters, sections, subsections, and page numbers in the table of contents, -* numbers or marks generated by \~`\cite` command (bibliography references), -* texts printed by \~`\url` or \~`\ulink` commands. -\enditems - -The last object is an external link and it is colored by -<color-out>. Other links are internal and they are colored by -<color-in>. Example: - -\begtt -\hyperlinks \Blue \Green % internal links blue, URLs green. -\endtt - -You can use another marking of active links: by frames which are visible in -the PDF viewer but invisible when the document is printed. The way to do it -is to define the macros \^`\_pgborder`, \^`\_tocborder`, \^`\_citeborder`, -\^`\_refborder` and \^`\_urlborder` as the triple of RGB components of the used -color. Example: - -\begtt -\def\_tocborder {1 0 0} % links in table of contents: red frame -\def\_pgborder {0 1 0} % links to pages: green frame -\def\_citeborder {0 0 1} % links to references: blue frame -\endtt - -By default, these macros are not defined. It means that no frames are created. - -The hyperlinked footnotes can be activated by \^`\fnotelinks` `<color-fnt> <color-fnf>` -where footnote marks in the text have `<color-fnt>` and the same footnote marks -in footnotes have <color-fnf>. You can define relevant borders -\^`\_fntborder` and \^`\_fnfborder` analogically as \^`\_pgborder` (for example). - -There are \"low level" commands to create the links. You can specify the -destination of the internal link by \^`\dest[<type>:<label>]`. The -active text linked to the \^`\dest` can be created by -\^`\ilink[<type>:<label>]{<text>}`. The `<type>` parameter is one of -the `toc`, `pg`, `cite`, `ref`, or another special for your purpose. -These commands create internal links only when \^`\hyperlinks` is declared. - -The \^`\url` macro prints its parameter in \~`\tt` font and creates a potential -breakpoints in it (after slash or dot, for example). If the \^`\hyperlinks` -declaration is used then the parameter of \^`\url` is treated as an external URL link. -An example: `\url{http://www.olsak.net}` creates \url{http://www.olsak.net}. -The characters \code{\%}, `\`, `#`, `{`, and `}` have to be protected by -backslash in the \^`\url` argument, the other special characters `~`, -`^`, `&` can be written as single character\fnote -{More exactly, there are the same rules as for `\code` command, see -section~\ref[verbatim].}. -You can insert the `\|` command -in the `\url` argument as a potential breakpoint. - -If the linked text have to be different than the URL, you can use -\^`\ulink[<url>]{<text>}` macro. For example: -`\ulink[http://petr.olsak.net/optex]{\OpTeX/ page}` -outputs to the text -\ulink[http://petr.olsak.net/optex]{\OpTeX/ page}. -The characters \code{\%}, `\`, `#`, `{`, and `}` must by escaped in -the <url> parameter. - -The PDF format provides {\em outlines} which are notes placed in the special frame of -the PDF viewer. These notes can be managed as a structured and hyperlinked -table of contents of the document. The command \^`\outlines{<level>}` creates -such outlines from data used for the table of contents in the document. The -<level> parameter gives the level of opened sub-outlines -in the default view. The deeper levels can be opened by mouse click on the -triangle symbol after that. - -\new -If you are using a special unprotected macro in section titles then \^`\outlines` macro -may crash. You must declare a variant of the macro for outlines case which is -expandable. Use \~`\regmacro` in this case. See the section \ref[toc] for more information -about \~`\regmacro`. - -The command \^`\insertoutline{<text>}` inserts a next entry into PDF outlines at -the main level~0. These entries can be placed before the table of contents (created -by \^`\outlines`) or after it. Their hyperlink destination is in the place -where the \^`\insertoutline` macro is used. - -The command \^`\thisoutline{<text>}` uses <text> in the outline instead of default -title text for the first following `\chap`, `\sec`, or `\secc`. -Special case: \^`\thisoutline{\relax}` doesn't create any outline for the following -`\chap`, `\sec`, or `\secc`. - -\secc Lists -%%%%%%%%%% - -The list of items is surrounded by \^`\begitems` and \^`\enditems` commands. -The asterisk (`*`) is active within this environment and it starts one item. -The item style can be chosen by the \^`\style` parameter written after \^`\begitems`: - -\begtt -\style o % small bullet -\style O % big bullet (default) -\style - % hyphen char -\style n % numbered items 1., 2., 3., ... -\style N % numbered items 1), 2), 3), ... -\style i % numbered items (i), (ii), (iii), ... -\style I % numbered items I, II, III, IV, ... -\style a % items of type a), b), c), ... -\style A % items of type A), B), C), ... -\style x % small rectangle -\style X % big rectangle -\endtt - -For example: - -\begtt -\begitems -* First idea -* Second idea in subitems: - \begitems \style i - * First sub-idea - * Second sub-idea - * Last sub-idea - \enditems -* Finito -\enditems -\endtt -% -produces: - -\begitems -* First idea -* Second idea in subitems: - \begitems \style i - * First sub-idea - * Second sub-idea - * Last sub-idea - \enditems -* Finito -\enditems - -Another style can be defined by the command \~`\sdef{_item:<style>}{<text>}`. -Default item can be set by \^`\defaultitem={<text>}`. -The list environments can be nested. Each new level of items is indented by -next multiple of \^`\iindent` value which is set to `\parindent` by default. -The \^`\ilevel` register says what level of items is currently processed. -Each \^`\begitems` starts \^`\everylist` tokens register. You can set, for -example: -\begtt -\everylist={\ifcase\ilevel\or \style X \or \style x \else \style - \fi} -\endtt - -You can say \^`\begitems` \^`\novspaces` if you don't want vertical spaces above -and below the list. The nested item list is without vertical spaces -automatically. More information about the design of lists of items should be -found in the section~\ref[lists]. - -A \"selected block of text" can be surrounded by -\^`\begblock`\dots\^`\endblock`. The default design of blocks of text is -indented text in smaller font. The blocks of text can be nested. - -\secc Tables -%%%%%%%%%%% - -The macro \^`\table{<declaration>}{<data>}` provides similar <declaration> -of tables as in \LaTeX: you can use letters `l`, `r`, `c`, each letter declares -one column (aligned to left, right, center, respectively). -These letters can be combined by the `|` character (vertical line). Example - -\begtt -\table{||lc|r||}{ \crl - Month & commodity & price \crli \tskip2pt - January & notebook & \$ 700 \cr - February & skateboard & \$ 100 \cr - July & yacht & k\$ 170 \crl} -\endtt -% -generates the result: - -\vskip-\medskipamount -\noindent\hfil\table{||lc|r||}{ \crl - Month & commodity & price \crli \tskip2pt - January & notebook & \$ 700 \cr - February & skateboard & \$ 100 \cr - July & yacht & k\$ 170 \crl} -\medskip - -Apart from `l`, `r`, `c` declarators, you can use the `p{<size>}` declarator -which declares the column with paragraphs of given width. More precisely, -a long text in the table cell is printed as a multiline paragraph with given width. -By default, the paragraph is left-right justified. But there are -alternatives: - -\begitems -* `p{<size>`\^`\fL}` fit left, i.e.\ left justified, ragged right, -* `p{<size>`\^`\fR}` fit right, i.e.\ right justified, ragged left, -* `p{<size>`\^`\fC}` fit center, i.e.\ ragged left plus right, -* `p{<size>`\^`\fS}` fit special, short one-line pararaph centered, - long paragraph normal, -* `p{<size>`\^`\fX}` fit extra, left-right justified but last line centered. -\enditems - -You can use `(<text>)` in the <declaration>. Then this text is applied in -each line of the table. For example `r(\kern10pt)l` adds more 10\,pt space -between `r` and `l` rows. - -An arbitrary part of the <declaration> can be repeated by a <number> -prefixed. For example `3c` means `ccc` or `c 3{|c}` means -`c|c|c|c`. Note that spaces in the <declaration> are ignored and you -can use them in order to more legibility. - -The command `\cr` used in the <data> part of the table -is generally known from Plain \TeX. It marks the end of each row in the table. -Moreover \OpTeX/ defines following similar commands: - -\begitems -* \^`\crl` \dots\ the end of the row with a horizontal line after it. -* \^`\crll` \dots\ the end of the row with a double horizontal line after it. -* \^`\crli` \dots\ like \^`\crl` but the horizontal line doesn't intersect the - vertical double lines. -* \^`\crlli` \dots\ like \^`\crli` but horizontal line is doubled. -* \^`\crlp{<list>}` \dots\ like \^`\crli` but the lines are drawn only in the - columns mentioned in comma-separated `<list>` of their numbers. - The <list> can include `<from>-<to>` declarators, for example - \^`\crlp{1-3,5}` is equal to \^`\crlp{1,2,3,5}`. -\enditems - -The \^`\tskip``<dimen>` command works like the `\noalign{\vskip<dimen>}` -immediately after `\cr*` commands but it doesn't interrupt the vertical lines. - -\new -You can use the following parameters for the \^`\table` macro. Default values are listed -too. - -\begtt -\everytable={} % code used in \vbox before table processing -\thistable={} % code used in \vbox, it is removed after using it -\tabiteml={\enspace} % left material in each column -\tabitemr={\enspace} % right material in each column -\tabstrut={\strut} % strut which declares lines distance in the table -\tablinespace=2pt % additional vert. space before/after horizontal lines -\vvkern=1pt % space between lines in double vertical line -\hhkern=1pt % space between lines in double horizontal line -\tabskip=0pt % space between columns -\tabskipl=0pt \tabskipr=0pt % space before first and after last column -\endtt - -Example: if you do \^`\tabiteml={$\enspace}`\^`\tabitemr={\enspace$}` then -the \^`\table` acts like \LaTeX's array environment. - -If there is an item that spans to more than one column in the table then -the macro \^`\multispan{<number>}` (from Plain \TeX) can help you. Another -alternative is -the command \^`\mspan``<number>[<declaration>]{<text>}` -which spans <number> columns and formats the <text> by the -<declaration>. The <declaration> must include a declaration of only one column -with the same syntax as common \^`\table` <declaration>. -If your table includes vertical rules and you want to -create continuous vertical rules by \^`\mspan`, then use rule declarators `|` -after `c`, `l` or `r` letter in \^`\mspan` <declaration>. The -exception is only in the case when \^`\mspan` includes the first -column and the table have rules on the left side. The example of \^`\mspan` -usage is below. - -The \^`\frame{<text>}` makes a frame around <text>. You can put the whole \^`\table` -into \^`\frame` if you need double-ruled border of the table. Example: - -\begtt -\frame{\table{|c||l||r|}{ \crl - \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli - first & second & third \crlli - seven & eight & nine \crli}} -\endtt -% -creates the following result: - -\hfil\frame{\table{|c||l||r|}{\crl - \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli - first & second & third \crlli - seven & eight & nine \crli}} -\bigskip - -The \^`\vspan``<number>{<text>}` shifts the <text> down in order it looks -like to be in the center of the <number> lines (current line is first). -You can use this for creating tables like in the following example: - -\begtt \typosize[8.7/11] -\thistable{\tabstrut={\vrule height 20pt depth10pt width0pt} - \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt} -\table{|8{c|}}{\crlp{3-8} - \mspan2[c|]{} & \mspan3[c|]{Singular} & \mspan3[c|]{Plural} \crlp{3-8} - \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl - \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} & \mspan3[c|]{X} \crlp{2,6-8} - & Exclusive & \mspan3[c|]{} & \mspan3[c|]{X} \crl - \vspan2{II} & Informal & \mspan3[c|]{X} & \mspan3[c|]{X} \crlp{2-8} - & Formal & \mspan6[c|]{X} \crl - \vspan2{III} & Informal & \vspan2{O} & X & X & \mspan2[c|]{X} &\vspan2{O} \crlp{2,4-7} - & Formal & & \mspan4[c|]{X} & \crl -} -\endtt - -\puttext 8.9cm -4cm {\pdfsave\pdfscale{.5}{.5}\rlap{% -\thistable{\tabstrut={\vrule height 20pt depth10pt width0pt} - \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt} -\table{|8{c|}}{\crlp{3-8} - \mspan2[c|]{} &\mspan3[c|]{Singular} &\mspan3[c|]{Plural} \crlp{3-8} - \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl - \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} &\mspan3[c|] X \crlp{2,6-8} - & Exclusive & \mspan3[c|]{} &\mspan3[c|] X \crl - \vspan2{II} & Informal & \mspan3[c|] X &\mspan3[c|] X \crlp{2-8} - & Formal & \mspan6[c|] X \crl - \vspan2{III} & Informal & \vspan2{O} & X & X &\mspan2[c|] X & \vspan2{O} \crlp{2,4-7} - & Formal & &\mspan4[c|] X & \crl -}}\pdfrestore} - -\hangindent=-7.5cm \hangafter=0 -You can use \^`\vspan` with non-integer parameter too if you feel that the -result looks better, for example \^`\vspan2.1{text}`. - -\hangindent=-7.5cm \hangafter=0 -The rule width of tables and implicit width of all `\vrule`s and `\hrule`s -can be set by the command \^`\rulewidth=<dimen>`. The default value given -by \TeX/ is 0.4\,pt. - -\hangindent=-7.5cm \hangafter=-2 -The `c`, `l`, `r` and `p` are default \"declaration letters" but you can define -more such letters by `\def\_tabdeclare<letter>{<left>##<right>}`. -More about it is in technical documentation in section~\ref[table.impl]. -See the definition of the \^`\_tabdeclarec` macro, for example. - -The `:` columns boundary declarator is described in section~\ref[table.bound]. -The tables with given width can be declared by `to<size>` or `pxto<size>`. -More about it is in section~\ref[table.w]. -Many tips about tables can be seen on the site -\url{http://petr.olsak.net/optex/optex-tricks.html}. - -\label[verbatim]\secc Verbatim -%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -The display verbatim text have to be surrounded by the \^`\begtt` and -\^`\endtt` couple. -The in-line verbatim have to be tagged (before and after) -by a character which is declared by -\^`\verbchar``<char>`. For example \code{\\verbchar`} -declares the character \code{`} -for in-line verbatim markup. -And you can use \code{`\\relax`} for -verbatim `\relax` (for example). -\new -Another alternative of printing in-line -verbatim text is \~`\code{<text>}` (see below). - -If the numerical register \^`\ttline` is set to the non-negative value then -display verbatim will number the lines. The first line has the number -\^`\ttline+1` and when the verbatim ends then the \^`\ttline` value is equal to the -number of the last line printed. Next \^`\begtt...`\^`\endtt` environment will follow -the line numbering. \OpTeX/ sets \^`\ttline=-1` by default. - -The indentation of each line in display verbatim is controlled by -\^`\ttindent` register. This register is set to the `\parindent` by default. -Users can change the values of the `\parindent` and \^`\ttindent` independently. - -The \^`\begtt` command starts the internal group in which the catcodes are changed. -\new -Then the \^`\everytt` tokens register is run. It is empty by default and the user can -control fine behavior by it. For example, the catcodes can be re-declared here. If -you need to define an active character in the \^`\everytt`, use \~`\adef` as in the -following example: - -\begtt \adef@{\string\endtt} -\everytt={\adef!{?}\adef?{!}} -\begtt -Each occurrence of the exclamation mark will be changed to -the question mark and vice versa. Really? You can try it! -@ -\endtt -% -The \~`\adef` command sets its parameter as active {\it after\/} -the parameter of \^`\everytt` is read. So you don't have to worry about active -categories in this parameter. - -There is an alternative to \^`\everytt` named \^`\everyintt` which is used for -in-line verbatim surrounded by an \^`\verbchar` or processed by the \~`\code` -command. - -The \^`\everytt` is applied to all \^`\begtt...`\^`\endtt` environments (if it is not -declared in a group). There are tips for such global `\everytt` definitions here: - -\begtt \adef!{\char9251 } -\everytt={\typosize[9/11]} % setting font size for verbatim -\everytt={\ttline=0} % each listing will be numbered from one -\everytt={\visiblesp} % visualization!of!spaces -\endtt - -\new -If you want to apply a special code only for one \^`\begtt...`\^`\endtt` -environment then don't set any \^`\everytt` but put desired material at the -same line where \^`\begtt` is. For example: - -\begtt \adef@{\string\endtt} -\begtt \adef!{?}\adef?{!} -Each occurrence of ? will be changed to ! and vice versa. -@ -\endtt - -The in-line verbatim surrounded by a \^`\verbchar` doesn't work in -parameter of macros and macro definitions. (It works in titles declared by -\~`\chap`, \~`\sec` etc. and in \~`\fnote`s, because these macros are -specially defined in \OpTeX/). -\new -You can use more robust command \^`\code{<text>}` in problematic -situations, but you have to escape the following characters in the <text>: -`\`, `#`, `%`, braces (if the braces are unmatched in the <text>), -and space or `^` (if there are more than one subsequent spaces or `^` in -the <text>). Examples: - -\begtt -\code{\\text, \%\#} ... prints \text, %# -\code{@{..}*&^$ $} ... prints @{..}*&^$ $ without escaping, but you can - escape these characters too, if you want. -\code{a \ b} ... two spaces between a b, the second must be escaped -\code{xy\{z} ... xy{z ... unbalanced brace must be escaped -\code{^\^M} ... prints ^^M, the second ^ must be escaped -\endtt - -You can print verbatim listing from external files by the \^`\verbinput` command. -Examples: - -\begtt -\verbinput (12-42) program.c % listing from program.c, only lines 12-42 -\verbinput (-60) program.c % print from begin to the line 60 -\verbinput (61-) program.c % from line 61 to the end -\verbinput (-) program.c % whole file is printed -\verbinput (70+10) program.c % from line 70, only 10 lines printed -\verbinput (+10) program.c % from the last line read, print 10 lines -\verbinput (-5+7) program.c % from the last line read, skip 5, print 7 -\verbinput (+) program.c % from the last line read to the end -\endtt - -\new -You can insert additional commands for \^`\verbinput` before -the first opening bracket. They are processed in the local group. -For example, `\verbinput \hsize=20cm (-) program.c`. - -The \~`\ttline` influences the line numbering by the same way as in -\~`\begtt...`\~`\endtt` environment. If \~`\ttline=-1` then real line numbers are -printed (this is the default). If \code{\\ttline<-1} then no line -numbers are printed. - -The \^`\verbinput` can be controlled by \^`\everytt`, \^`\ttindent` just like -in \~`\begtt...`\~`\endtt`. - -The \~`\begtt`...\~`\endtt` pair or \~`\verbinput` can be used for listings of -codes. Automatic syntax highlighting is possible, for example -`\begtt` \^`\hisyntax{C}` activates colors for C programs. Or -`\verbinput` \^`\hisyntax{HTML} (-) file.html` can be used for HTML or XML codes. -\OpTeX/ implements C, Python, \TeX/, HTML and XML syntax highlighting. -More languages can be declared, see the section~\ref[hisyntax]. - -If the code is read by \^`\verbinput` and there are comment lines prefixed -by two characters then -you can set them by \~`\commentchars``<first><second>`. Such comments are -fully interpreted by \TeX/ (i.e. not verbatim). -Section~\ref[verb] (page \pgref[commentchars]) says more about this feature. - -\sec Autogenerated lists -%%%%%%%%%%%%%%%%%%%%%%%% - -\secc[toc] Table of contents -%%%%%%%%%%%%%%%%%%%%%% - -The \^`\maketoc` command prints the table of contents of all \~`\chap`, \~`\sec` -and \~`\secc` used in the document. These data are read from the external `*.ref` file, so -you have to run \TeX/ more than once (typically three times if the table of -contents is at the beginning of the document). - -Typically, we don't want to repeat the name of the section \"Table of contents" -in the table of contents again. The direct usage -of \~`\chap` or \~`\sec` isn't recommended here because the table of contents -is typically not referenced to itself. You can print the unnumbered and unreferenced -title of the section like this: - -\begtt -\nonum\notoc\sec Table of Contents -\endtt -If you need a customization of the design of the TOC, read the -section~\ref[maketoc]. - -\new -If you are using a special macro in section or chapter titles -and you need different behavior of such macro in other cases then use -\^`\regmacro{<case-toc>}{<case-mark>}{<case-outline>}`. -The parameters are applied locally in given cases. The \^`\regmacro` can be -used repeatedly: then its parameters are accumulated (for more macros). -If a parameter is empty then original definition is used in given case. -For example: - -\begtt -% default value of \mylogo macro used in text and in the titles: -\def\mylogo{\leavevmode\hbox{{\Red\it My}{\setfontsize{mag1.5}\rm Lo}Go}} -% another variants: -\regmacro {\def\mylogo{\hbox{\Red My\Black LoGo}}} % used in TOC - {\def\mylogo{\hbox{{\it My}\/LoGo}}} % used in running heads - {\def\mylogo{MyLoGo}} % used in PDF outlines -\endtt - -\secc Making the index -%%%%%%%%%%%%%%%%%%%%% - -The index can be included in the document by the \^`\makeindex` macro. No external -program is needed, the alphabetical sorting is done inside \TeX/ at macro -level. - -The \^`\ii` command (insert to index) declares the word separated by the space -as the index item. This declaration is represented as an invisible item on the -page connected to the next visible word. The page number of the page where -this item occurs is listed in the index entry. So you can type: - -\begtt -The \ii resistor resistor is a passive electrical component ... -\endtt - -You cannot double the word if you use the \^`\iid` instead of \^`\ii`: - -\begtt -The \iid resistor is a passive electrical component ... -or: -Now we'll deal with the \iid resistor . -\endtt - -Note that the dot or comma has to be separated by space when \^`\iid` is -used. This space (before dot or comma) is removed by the macro in -the current text. - -The multiple-words entries are commonly arranged in the index as follows: - -\medskip - -linear~dependency 11, 40--50 - ---- independency 12, 42--53 - ---- space 57, 76 - ---- subspace 58 - -\medskip - -To do this you have to declare the parts of the index entries by the `/` separator. -Example: - -\begtt -{\bf Definition.} -\ii linear/space,vector/space -{\em Linear space} (or {\em vector space}) is a nonempty set of... -\endtt - -The number of the parts of one index entry (separated by `/`) is unlimited. Note, that you can -spare your typing by the comma in the \~`\ii` parameter. The previous example -is equivalent to `\ii linear/space \ii vector/space`~. - -Maybe you need to propagate to the index the similar entry to the -linear/space in the form of space/linear. You can do this by the shorthand `,@` -at the end of the \~`\ii` parameter. Example: - -\begtt -\ii linear/space,vector/space,@ -is equivalent to: -\ii linear/space,vector/space \ii space/linear,space/vector -\endtt - -If you really need to insert the space into the index entry, write `~`. - -The \~`\ii` or \~`\iid` commands can be preceded by \^`\iitype` `<letter>`, then such -reference (or more references generated by one \~`\ii`) has the specified type. -The page numbers of such references should be formatted -specially in the index. \OpTeX/ implements only \^`\iitype` `b`, -\^`\iitype` `i` and \^`\iitype` `u`: -the page number in bold or in italics or underlined is printed -in the index when these types are used. The default index type is empty, which -prints page numbers in normal font. The \TeX/book index is a good example. - -The \^`\makeindex` creates the list of alphabetically sorted index entries -without the title of the section and without creating more columns. \OpTeX/ -provides other macros \^`\begmulti` and \^`\endmulti` for more columns: - -\begtt \catcode`\<=13 -\begmulti <number of columns> -<text> -\endmulti -\endtt -The columns will be balanced. The Index can be printed by the following -code: - -\begtt -\sec Index -\begmulti 3 \makeindex \endmulti -\endtt - -Only \"pure words" can be propagated to the index by the \~`\ii` command. It -means that there cannot be any macro, \TeX/ primitive, math selector, etc. -But there is another possibility to create such a complex index entry. Use -\"pure equivalent" in the \~`\ii` parameter and map this equivalent to a -real word that is printed in the index. Such mapping is done by -\^`\iis` command. Example: - -\begtt -The \ii chiquadrat $\chi$-quadrat method is ... -If the \ii relax `\relax` command is used then \TeX/ is relaxing. -... -\iis chiquadrat {$\chi$-quadrat} -\iis relax {\code{\\relax}} -\endtt -% -The \^`\iis` `<equivalent> {<text>}` creates one entry in the \"dictionary -of the exceptions". The sorting is done by the <equivalent> but the -<text> is printed in the index entry list. - -The sorting rules when \^`\makeindex` runs depends on the current language. -See section~\ref[lang] about languages selection. - -\secc Bib\TeX/ing -%%%%%%%%%%%%%%%% - -The command \^`\cite[<label>]` (or -\hbox{\^`\cite[<label-1>,<label-2>,...,<label-n>]`}) -creates the citation in the form [42] (or [15,~19,~26]). -If \^`\shortcitations` is declared at the beginning of the document then -continuous sequences of numbers are re-printed like this: -\hbox{[3--5,~7,~9--11]}. If -\^`\sortcitations` is declared then numbers generated by one \^`\cite` command -are sorted upward. - -If \^`\nonumcitations` is declared then the marks instead of numbers are generated -depending on the used bib-style. For example, the citations look like -[Now08] or [Nowak, 2008]. - -The \^`\rcite[<labels>]` creates the same list as \^`\cite[<labels>]` but without -the outer brackets. Example: `[\rcite[tbn], pg.~13]` creates [4,~pg.~13]. - -The \^`\ecite[<label>]{<text>}` prints the `<text>` only, but the entry labeled -<label> is decided as to be cited. If \~`\hyperlinks` is used then <text> -is linked to the references list. - -You can define alternative formating of \^`\cite` command. Example: - -\begtt \catcode`\<=13 -\def\cite[#1]{(\rcite[#1])} % \cite[<label>] creates (27) -\def\cite[#1]{$^{\rcite[#1]}$} % \cite[<label>] creates^{27} -\endtt - -The numbers printed by \^`\cite` correspond to the same numbers generated in -the list of references. There are two possibilities to generate this -references list: - -\begitems -* Manually using \~`\bib[<label>]` commands. -* By \~`\usebib/<type> (<style>) <bib-base>` command which reads `*.bib` - files directly. -\enditems - -\new -Note that another two possibilities documented in OPmac (using external -Bib\TeX/ program) isn't supported because Bib\TeX/ is an old program that does not -support Unicode. And Biber seems to be not compliant with Plain \TeX. - -\medskip\noindent -{\bf References created manually using \^`\bib[<label>]` command.} - -\begtt -\bib [tbn] P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 1997. -\bib [tst] P. Olšák. {\it Typografický systém \TeX.} - 269~s. Praha: CSTUG, 1995. -\endtt - -If you are using \~`\nonumcitations` then you need to declare the <marks> -used by \~`\cite` command. To do it you must use long form of the \^`\bib` -command in the format \^`\bib[<label>] = {<mark>}`. The spaces around -equal sign are mandatory. Example: - -\begtt -\bib [tbn] = {Olšák, 2001} - P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 2001. -\endtt - -\noindent -{\bf Direct reading of `.bib` files} is possible by \^`\usebib` macro. -This macro reads and uses macro package `librarian.tex` by Paul Isambert. -The usage is: - -\begtt \catcode`\<=13 -\usebib/c (<style>) <bib-base> % sorted by \cite-order (c=cite), -\usebib/s (<style>) <bib-base> % sorted by style (s=style). -% example: -\nocite[*] \usebib/s (simple) op-biblist % prints all from op-biblist.bib -\endtt - -The <bib-base> is one or more `*.bib` database source files (separated by -spaces and without extension) and the <style> is the part of the filename -`bib-<style>.opm` where the formatting of the references list is -defined. \OpTeX/ supports `simple` or `iso690` styles. The features of -the `iso690` style is documented in the section~\ref[isobib] in detail. -The \^`\usebib` command is more documented in section~\ref[usebib]. - -Not all records are printed from <bib-base> files: the command \^`\usebib` -selects only such bib-records which were used in \~`\cite` or \^`\nocite` -commands in your document. The \^`\nocite` behaves as \~`\cite` but prints -nothing. It tells only that the mentioned bib-record should be printed in the -reference list. If \^`\nocite[*]` is used then all records from <bib-base> -are printed. - -\sec Graphics -%%%%%%%%%%%%% - -\secc Colors -%%%%%%%%%%% - -\OpTeX/ provides a small number of color selectors: -{\Blue `\Blue`}, -{\Red `\Red`}, -{\Brown `\Brown`}, -{\Green `\Green`}, -{\Yellow `\Yellow`}, -{\Cyan `\Cyan`}, -{\Magenta `\Magenta`}, -{`\White`}, -{\Grey `\Grey`}, -{\LightGrey `\LightGrey`} and -`\Black`. User can define more -such selectors by setting four CMYK components -\new -or three RGB components. For example - -\begtt -\def \Orange {\setcmykcolor{0 0.5 1 0}} -\def \Purple {\setrgbcolor{1 0 1}} -\endtt - -\new -The command \^`\morecolors` reads more definitions of color selectors from -the \LaTeX/ file `x11nam.def`. -There are about 300 color names like -`\DeepPink`, `\Chocolate` etc. If there are numbered variants of the same -name, then the letters B, C, etc. are appended to the name in \OpTeX/. For example -`\Chocolate` is Chocolate1, `\ChocolateB` is Chocolate2 etc. - -\new -The color selectors work locally in groups by default but with limitations. See -the technical documentation, section~\ref[colors] for more information. - -The basic colors \^`\Blue`, \^`\Red`, \^`\Cyan`, \^`\Yellow` etc.\ are defined -with CMYK components using \^`\setcmykcolor`. -On the other hand, you can define a color with three -RGB components and \^`\morecolors` defines such RGB colors. -By default, the color model isn't converted but only stored to -PDF output for each used color. Thus, there may be a mix of color -models in the PDF output which is not a good idea. You can overcome this -problem by declaration \^`\onlyrgb` or \^`\onlycmyk`. Then only the selected color -model is used for PDF output and if a used color is declared by another color -model then it is converted. -The \^`\onlyrgb` creates colors more bright (usable for computer -presentations). On the other hand, CMYK makes colors more true\fnote -{Printed output is more equal to the monitor preview especially if you are -using ICC profile for your printer.} -for printing. - -\new -You can define your color by a linear combination of previously defined colors using -\^`\colordef`. For example: - -\begtt -\colordef \myCyan {.3\Green + .5\Blue} % 30 % green, 50 % blue, 20% white -\colordef \DarkBlue {\Blue + .4\Black} % Blue mixed with 40 % of black -\colordef \myGreen{\Cyan+\Yellow} % exact the same as \Green -\colordef \MyColor {.3\Orange+.5\Green+.2\Yellow} -\endtt -% -The linear combination is done in CMYK subtractive color space by default -(RGB colors used in \^`\colordef` argument are converted first). -If the resulting component is greater than 1 then it is truncated to 1. -If a convex linear combination (as in the last example above) is used then it -emulates color behavior on a painter's palette. -You can use \^`\rgbcolordef` instead of \^`\colordef` if you want to mix colors -in the additive RGB color space. - -\def\coloron#1#2#3{% - \setbox0=\hbox{{#2#3}}\leavevmode - \localcolor \rlap{#1\strut \vrule width\wd0}\box0 -} -The following example defines the macro for the -\coloron\Yellow\Brown{colored text on the colored background}. Usage: -`\coloron<background><foreground>{<text>}` - -The `\coloron` can be defined as follows: - -\begtt -\def\coloron#1#2#3{% - \setbox0=\hbox{{#2#3}}% - \leavevmode \rlap{#1\strut \vrule width\wd0}\box0 -} -\coloron\Yellow\Brown{The brown text on the yellow background} -\endtt - -\secc Images -%%%%%%%%%%% - -The \^`\inspic` `{<filename>.<extension>}` or -\^`\inspic` `<filename>.<extension><space>` -inserts the picture stored in -the graphics file with the name `<filename>.<extension>` to the document. -You can set the picture width by \^`\picw=<dimen>` -before \^`\inspic` command which declares the width of the picture. -The image files can be in the PNG, JPG, JBIG2 or PDF format. - -The \^`\picwidth` is an equivalent register to `\picw`. Moreover, there is an -\^`\picheight` register which denotes the height of the picture. If both -registers are set then the picture will be (probably) deformed. - -The image files are searched in \^`\picdir`. This token list is empty -by default, this means that the image files are searched in the -current directory. Example: \^`\picdir={img/}` supposes that image files are -in `img` subdirectory. Note: the directory name must end by `/` in -the \^`\picdir` declaration. - -Inkscape\fnote -{A powerful and free Wysiwyg editor for creating vector graphics.} -is able to save a picture to PDF and labels of the picture to another -file\fnote -{Chose \"Omit text in PDF and create LaTeX file" option.}. -This second file should be read by \TeX/to print labels -in the same font as document font. \OpTeX/ supports this feature by -\^`\inkinspic` `{<filename>.pdf}` command. It reads and displays -both: PDF image and labels generated by Inkscape. - -If you want to create vector graphics (diagrams, schema, geometry -skicing) then you can do it by Wysiwyg graphics editor (Inkscape, Geogebra for -example), export the result to PDF and include it by \^`\inspic`. -If you want to \"program" such pictures then Tikz package is recommended. -It works in Plain \TeX/ and \OpTeX. - -\secc PDF transformations -%%%%%%%%%%%%%%%%%%%%%%%% - -All typesetting elements are transformed by linear -transformation given by the current transformation matrix. The -`\pdfsetmatrix` `{<a> <b> <c> <d>}` command makes the internal multiplication -with the current matrix so linear transformations can be composed. -One linear transformation given by the `\pdfsetmatrix` above transforms -the vector $[0,1]$ to [<a>,\,<b>] and $[1,0]$ to [<c>,\,<d>]. -The stack-oriented commands `\pdfsave` and `\pdfrestore` gives a possibility of -storing and restoring the current transformation matrix and the position of the current point. -This position has to be the same from \TeX{}'s point of -view as from the transformation point of view when `\pdfrestore` is processed. -Due to this fact the `\pdfsave\rlap{<transformed text>}\pdfrestore` -or something similar is recommended. - -\OpTeX/ provides two special transformation macros -\^`\pdfscale` and \^`\pdfrotate`: - -\begtt \catcode`\<=13 -\pdfscale{<horizontal-factor>}{<vertical-factor>} -\pdfrotate{<angle-in-degrees>} -\endtt - -These macros simply call the properly `\pdfsetmatrix` command. - -It is known that the composition of transformations is not commutative. It -means that the order is important. You have to read the transformation -matrices from right to left. Example: - -\begtt -First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore - % text1 is scaled two times and it is reflected about vertical axis - % and next it is rotated by 30 degrees left. -second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore - % text2 is rotated by 30 degrees left then it is scaled two times - % and reflected about vertical axis. -third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}% - \pdfrestore % first slanted, then rotated by 15.3 degrees right -\endtt -% -\par\nobreak\bigskip\smallskip -This gives the following result. -First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore -second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore -third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}\pdfrestore -\par\nobreak\bigskip\penalty0%\bigskip - -You can see that \TeX/ knows nothing about dimensions of transformed material, -it treats it as with a zero dimension object. -\new -The \^`\transformbox{<transformation>}{<text>}` -macro solves the problem. This macro puts the transformed -material into a box with relevant dimensions. The <transfromation> parameter -includes one or more transformation commands `\pdfsetmatrix`, `\pdfscale`, -`\pdfrotate` with their parameters. The <text> is transformed text. - -Example: \~`\frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}` -creates \frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}. - -The \^`\rotbox{<deg>}{<text>}` is shortcut for -\^`\transformbox{\pdfrotate{<deg>}}{<text>}`. - -\secc Ovals, circles -%%%%%%%%%%%%%%%%%%%% - -\new -The \^`\inoval{<text>}` creates a box like this: \inoval{text}. -Multiline text can be put in an oval by the command \^`\inoval{\vbox{<text>}}`. -Local settings can be set by -\^`\inoval[<settings>]{<text>}` or you can re-declare global settings by -\^`\ovalparams={<settings>}`. The default settings are: - -\begtt -\ovalparams={\roundness=2pt % diameter of circles in the corners - \fcolor=\Yellow % color used for filling oval - \lcolor=\Red % line color used in the border - \lwidth=0.5bp % line width in the border - \shadow=N % use a shadow effect - \overlapmargins=N % ignore margins by surrounding text - \hhkern=0pt \vvkern=0pt} % left-righ margin, top-bottom margin -\endtt -The total distance from text to oval boundary is `\hhkern+\roundness` at the left and right -sides and -`\vvkern+\roundness` at the top and bottom sides of the text. - -If you need to set a parameters for the <text> (color, size, font etc.), -put such setting right in front of the <text>: -\^`\inoval{<text settings><text>}`. - -\new -The \^`\incircle[\ratio=1.8]{<text>}` creates a box like this \incircle[\ratio=1.8]{text}. -The \^`\ratio` parameter means width/height. The usage is analogical like for oval. -The default parameters are - -\begtt -\circleparams={\ratio=1 \fcolor=\Yellow \lcolor=\Red \lwidth=0.5bp - \shadow=N \ignoremargins=N \hhkern=2pt \vvkern=2pt} -\endtt - -\new -The macros \^`\clipinoval` `<x> <y> <width> <height> {<text>}` -and \^`\clipincircle` (with the same parameters) -print the `<text>` when a clipping path (oval or cirle with given -`<with>` and `<height>` shifted its center by `<x>` to right and by `<y>` to up) -is used. -The `\roundness=5mm` is default for \^`\clipinoval` and user can change it. -Example: - -\begtt -\clipincircle 3cm 3.5cm 6cm 7cm {\picw=6cm \inspic{myphoto.jpg}} -\endtt - -\secc Putting images and texts wherever - -\new -The \^`\puttext` `<x> <y> {<text>}` puts the `<text>` shifted by `<x>` right and by -`<y>` up from the current point of typesetting and does not change the -position of the current point. Assume a coordinate system with origin in the -current point. Then \^`\puttext` `<x> <y> {<text>}` puts the text at the -coordinates `<x>`, `<y>`. More exactly the left edge of its baseline is at that -position. - -\new -The \^`\putpic` `<x> <y> <width> <height> {<image-file>}` puts an image -given by `<image-file>` (including extension) of given -`<width>` and `<height>` at given position (its left-bottom corner). -You can write \^`\nospec` instead `<width>` or `<height>` if this parameter -is not specified. - -\sec Others -%%%%%%%%%%% - -\secc[lang] Using more languages -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\OpTeX/ prepares hyphenation patterns for all languages if such patterns are -available in your \TeX/ system. -\new -Only USenglish patterns (original from Plain \TeX/) are preloaded. -Hyphenation patterns of all other languages are loaded on demand when you first use -the `\<iso-code>lang` command in your document. -For example \^`\delang` for German, \^`\cslang` for -Czech, \^`\pllang` for Polish. The <iso-code> is a shortcut -of the language (mostly from ISO 639-1). -You can list all available languages by \^`\langlist` -macro. This macro prints now: - -\medskip -{\typosize[8.5/11.5]\emergencystretch=4em \hbadness=4000 -\noindent \langlist -\par} -\medskip - -\new -For compatibility with e-plain macros, there is the command -\^`\uselanguage{<language>}`. The parameter <language> is long-form of -language name, i.e.\ \^`\uselanguage{Czech}` works the same as \^`\cslang`. -The \^`\uselanguage` parameter is case insensitive. - -For compatibility with \csplain/, there are macros \^`\ehyph`, \^`\chyph`, -\^`\shyph` which are equivalent to \^`\enlang`, \^`\cslang` and \^`\sklang`. - -You can switch between language patterns by `\<iso-code>lang` commands mentioned -above. Default is \^`\enlang`. - -\OpTeX/ generates three phrases used for captions and titles in technical -articles or books: \"Chapter", \"Table" and \"Figure". These phrases need to be known -in used language and it depends on the previously used language selectors -`\<iso-code>lang`. \OpTeX/ declares these words only for few languages: -\new -Czech, German, Spanish, French, Greek, Italian, Polish, Russian, Slovak and -English, If you need to use these words in other languages or you want to -auto-generate more words in your macros, then you can declare it by -\~`\sdef` or \^`\_langw` commands as shown in section~\ref[langphrases]. - -The \~`\makeindex` command needs to know the sorting rules used in your language. -\OpTeX/ defines only a few language rules for sorting: Czech, -Slovak and English. How to declare sorting rules for more languages are -described in the section~\ref[makeindex]. - -If you declare `\<iso-code>quotes`, then the control sequences `\"` and `\'` -should be used like this: `\"<quoted text>"` or `\'<quoted text>'` -(note that the terminating character is the same but it isn't escaped). -This prints language-dependent normal or alternative quotes around -<quoted text>. The language is specified by <iso-code>. \OpTeX/ declares -quotes only for Czech, German, Spanish, French, Greek, Italian, Polish, -Russian, Slovak and English (\^`\csquotes`, \^`\dequotes`, \dots, \^`\enquotes`). -You can simply define your own quotes as shown in section~\ref[langphrases]. -The `\"` is used for quotes visually more similar to the `"` character which -can be primary quotes or secondary quotes depending on the language rules. -Maybe you want to alternate the meaning of these two types of quotes. Use -`\<isocode>quotes\altquotes` in such case. - -\secc[styles] Pre-defined styles -%%%%%%%%%%%%%%%%%%%%%%% - -\OpTeX/ defines three style-declaration macros \~`\report`, \~`\letter` and -\~`\slides`. You can use them at the beginning of your document if you are -preparing these types of documents and you don't need to create your own -macros. - -The \^`\report` declaration is intended to create reports. It -sets default font size to 11\,pt and `\parindent` (paragraph indentation) to 1.2\,em. -The `\tit` macro uses smaller font because we assume that \"chapter level" -will be not used in reports. The first page has no page number, but the next pages -are numbered (from number~2). Footnotes are numbered from one in the whole -document. The macro `\author <authors><end-line>` can be used when -\^`\report` is declared. It prints `<authors>` in italics at the center of the -line. You can separate authors by `\nl` to more lines. - -The \^`\letter` declaration is intended to create letters. -See the files `op-letter-*.tex` for examples. -The \^`\letter` style sets default -font size to 11\,pt and `\parindent` to 0\,pt. It sets half-line space -between paragraphs. The page numbers are not printed. The \^`\subject` macro -can be used, it prints the word \"Subject:" or \"Věc" (or something else -depending on current language) in bold. Moreover, the \^`\address` macro -can be used when \^`\letter` is declared. The usage of the \^`\address` macro -looks like: - -\begtt \catcode`\<=13 -\address - <first line of address> - <second line of address> - <etc.> - <empty line> -\endtt - -It means that you need not use any special mark at the end of lines: the ends -of lines in the source file are the same as in printed output. The -\^`\address` macro creates `\vtop` with address lines. The width of such -`\vtop` is equal to the widest line used in it. So, you can use -`\hfill\address...` to put the address box to the right side of the -document. Or you can use `<prefixed text>\address...` to put -`<prefixed text>` before the first line of the address. - -The \^`\slides` style creates a simple presentation slides. See an example -in the file `op-slides.tex`. Run `optex op-slides.tex` and see the documentation of -\^`\slides` style in the file `op-slides.pdf`. - -Analogical declaration macro `\book` is not prepared. Each book needs -individual typographical care. You need to create specific macros for -design. - -\secc Loading other macro packages -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -You can load more macro packages by `\input{<file-name>}` or by -\^`\load[<file-names>]`. The first case (`\input`) is \TeX/ primitive command, it can be -used in the alternative old syntax `\input <filename><space>` too. The -second case (\^`\load`) allows specifying a comma-separated list of included files. -Moreover, it loads each macro file only once, it sets -temporarily standard category codes during loading and it tries to -load `<filename>.opm` or `<filename>.tex` or `<filename>`, the first occurence -wins. Example: -\begtt -\load [qrcode, tikz] -\endtt -% -does `\input qrcode.opm` \,and `\input tikz.tex` \,and it saves -local information about the fact that these file names -`qrcode` and `tikz` were already used, i.\,e. next \^`\load` will skip them. - -It is strongly recommended to use the `\load` macro for loading external -macros if you need them. On the other hand, if your source document is structured -to more files (with individual chapters or sections), use simply the `\input` primitive. - -The macro packages intended to \OpTeX/ have the name `*.opm`. -The following packages are distributed as part of \OpTeX/: -\begitems -* `qrcode.opm` enables to create QR codes. -* `vlna.opm` enables to protect of one-letter prepositions and more things automatically. -* `emoji.opm` defines `\emoji{<name>}` command for colored emoticons. -* `plain-at.opm` defines the old names from plain \TeX/. -\enditems -See the directory `optex/pkg/` and these files for more information about -them. - -\secc Lorem ipsum dolor sit -%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\new -A designer needs to concentrate on the design of the output and maybe he/she -needs material for testing macros. There is the possibility to generate a -neutral text for such experiments. Use \^`\lorem[<number>]` or -\^`\lorem[<from>-<to>]`. It prints a paragraph (or paragraphs) with neutral -text. The numbers <number> or <from>, <to> must be in the range 1 to 150 -because there are 150 paragraphs with neutral text prepared for you. -The \^`\lipsum` macro is equivalent to \^`\lorem`. Example: \^`\lipsum[1-150]` -prints all prepared paragraphs. - -\secc Logos -%%%%%%%%%% - -\new -The control sequences for typical logos can be terminated by optional `/` -which is ignored when printing. This makes logos more legible in the source file: - -\begtt -We are using \TeX/ because it is cool. \OpTeX/ is better than \LaTeX. -\endtt - -\secc The last page -%%%%%%%%%%%%%%%%%%% - -The number of the last page (it may be different from the number of pages) is -expanded by \^`\lastpage` macro. It expands to `?` in first \TeX/ run and to -the last page in next \TeX/ runs. - -There is an example for footlines in the format \"current page / last page": - -\begtt -\footline={\hss \fixedrm \folio/\lastpage \hss} -\endtt - -\new -The \^`\lastpage` expands to the last \^`\folio` which is a decimal -number or Roman numeral (when \^`\pageno` is negative). If you need to know -the total pages used in the document, use \^`\totalpages` macro. It expands to -zero (in first \TeX/ run) or to the number of all pages in the document -(in next \TeX/ runs). - -\secc Use \OpTeX/ -%%%%%%%%%%%%%%%%% - -\new -The command \^`\useOpTeX` (or \^`\useoptex`) does nothing in \OpTeX/ but it causes -an error (undefined control sequence) when another format is used. You can -put it as the first command in your document: - -\begtt -\useOpTeX % we are using OpTeX format, no LaTeX :) -\endtt - -\sec Summary -%%%%%%%%%%%% - -\def\ttref#1'{\ea\~\ea`\csname#1\endcsname`} - -\begtt \typosize[9/11]\adef&{\kern.25em}\adef~#1'{\ea\~\ea`\csname#1\endcsname`} -~tit' Title (terminated by end of line) -~chap' Chapter Title (terminated by end of line) -~sec' Section Title (terminated by end of line) -~secc' Subsection Title (terminated by end of line) - -~maketoc' % table of contents generation -~ii' item1,item2 % insertion the items to the index -~makeindex' % the index is generated - -~label' [labname] % link target location -~ref' [labname] % link to the chapter, section, subsection, equation -~pgref' [labname] % link to the page of the chapter, section, ... - -~caption'/t % a numbered table caption -~caption'/f % a numbered caption for the picture -~eqmark' % a numbered equation - -~begitems' % start a list of the items -~enditems' % end of list of the items -~begblock' % start a block of text -~endblock' % end of block of text -~begtt' % start a verbatim text -~endtt' % end verbatim text -~verbchar' X % initialization character X for in-text verbatim -~code' % another alternative for in-text verbatim -~verbinput' % verbatim extract from the external file -~begmulti' num % start multicolumn text (num columns) -~endmulti' % end multicolumn text - -~cite' [labnames] % refers to the item in the lits of references -~rcite' [labnames] % similar to \cite but [] are not printed. -~sortcitations' ~shortcitations' ~nonumcitations' % cite format -~bib' [labname] % an item in the list of references -~usebib'/? (style) bib-base % direct using of .bib file, ? in {s,c} - -~load' [filenames] % loadaing macro files -~fontfam' [FamilyName] % selection of font family -~typosize' [font-size/baselineskip] % size setting of typesetting -~typoscale' [factor-font/factor-baselineskip] % size scaling -~thefontsize' [size] ~thefontscale' [factor] % current font size - -~inspic' file.ext % insert a picture, extensions: jpg, png, pdf -~table' {rule}{data} % macro for the tables like in LaTeX - -~fnote' {text} % footnote (local numbering on each page) -~mnote' {text} % note in the margin (left or right by page number) - -~hyperlinks' {color-in}{color-out} % PDF links activate as clickable -~outlines' {level} % PDF will have a table of contents in the left tab - -~magscale'[factor] % resize typesetting, line/page breaking unchanged -~margins'/pg format (left, right, top, bottom)unit % margins setting - -~report' ~letter' ~slides' % style declaration macros -\endtt - -\sec API for macro writers -%%%%%%%%%%%%%%%%%%%%%%%%%% - -All \TeX/ primitives and almost all \OpTeX/ macros are accesible by two -names: `\foo` (public or user name space) and `\_foo` (private name space). -For example `\hbox` and `\_hbox` means the same \TeX/ primitive. More about -it is documented in section~\ref[prefixed]. - -If this manual refers `\foo` then `\_foo` equivalent exists too. For example, -we mention the `\addto` macro below. The `\_addto` equivalent exists too, but it -is not explicitly mentioned here. If we refer only `\_foo` then its public -equivalent does not exist. For example, we mention the `\_codedecl` macro below, so -this macro is not available as `\codedecl`. - -If you are writing a document or macros specific for the document, then use -simply user namespace (`\foo`). If you are writing more general macros, -then use private namespace (`\_foo`), but you should declare your own namespace -by \~`\_namespace` macro and you have to follow the naming discipline described in -section~\ref[pkg-namespace]. - -The alphabetically sorted list of macros typically usable for macro writers follows. -More information about such macros can be found in the technical documentation. -You can use hyperlinks here in order to go to the appropriate place of the technical -documentation. - -\medskip \noindent -\^`\addto`` \macro{<text>}` adds <text> at the end of `\macro` body.\nl -\^`\adef` `<char>{<body>}` defines <char> active character with meaning <body>.\nl -\^`\afterfi` `{<text>}<ignored>\fi` expands to `\fi<text>`.\nl -\^`\bp`` {<dimen expression>}` expands \TeX/ dimension to decimal number in `bp` without unit.\nl -\~`\_codedecl`` <sequence> {<info>}` is used at beginning of macro files.\nl -\~`\colordef`` \macro {<mix of colors>}` declares `\macro` as color switch.\nl -\^`\cs` `{<string>}` expands `\<string>`.\nl -\~`\_doc` `...` \~`\_cod` encloses documenation text in the macro code.\nl -\^`\eoldef`` \macro #1{<body>}` defines `\macro` with parameter separated to end of line.\nl -\~`\_endcode` closes the part of macro code in macro files.\nl -\~`\_endnamespace` closes name space declared by \~`\_namespace`.\nl -\~`\eqbox`` [<label>]{<text>}` creates `\hbox{<text>}` with common width across whole document.\nl -\^`\expr`` {<expression>}` expands to result of the <expression> with decimal numbers.\nl -\~`\fontdef`` \f {<font spec.>}` declares `\f` as font switch.\nl -\~`\fontlet` `\fa=\fb <sizespec.>` declares `\fa` as the same font switch - like `\fb` at given <sizespec.>.\nl -\^`\foreach` `<list>\do <parameters>{<what>}` is exapandable loop over <list>.\nl -\^`\foreachdef` `\macro <parameters>{<what>}` declares expandable `\macro` as loop over <list>.\nl -\^`\fornum` `<from>..<to>\do {<what>}` is expanadable loop with numeric variable.\nl -\^`\incr` `<counter>` increases and \^`\decr` `<counter>` decreases `<counter>` by one globally.\nl -\^`\ignoreit` `<one>`, \^`\ignoresecond` `<one><two>` ignores given parameter.\nl -`\expandafter` \^`\ignorept` `\the<dimen>` expands to decimal number <dimen> without `pt`.\nl -\~`\isempty`, \~`\istoksempty`, \~`\isequal`, \~`\ismacro`, \~`\isdefined`, \~`\isinlist` -\~`\isfile`, \~`\isfont` do various tests. Example: \~`\isinlist\list{<text>}\iftrue` does - `\iftrue` if <text> is in `\list`.\nl -\^`\isnextchar`` <char>{<text1>}{<text2>}` performs <text1> if next - character is <char>, else <text2>.\nl -\~`\kv` `{<key>}` expands to value when key-value parameters are used.\nl -\^`\loop` `...` \^`\repeat` is classical Plain \TeX/ loop.\nl -\^`\mathstyles`` {<math list>}` enables to create macros dependent on current math style.\nl -\~`\_namespace`` {<pkg>}` declares name space used by package writers.\nl -\^`\newcount`, \^`\newdimen` etc. are classical Plain \TeX/ allocators.\nl -\^`\newif` `\iffoo` declares boolean `\iffoo` as in Plain \TeX/.\nl -\^`\_newifi` `\_iffoo` declares boolean `\_iffoo`.\nl -\^`\opinput`` {<filename>}` reads file like `\input` but with standard catcodes.\nl -\^`\optdef`` \macro [<opt-default>] <parameters>{<body>}` defines `\macro` with [opt.parameter].\nl -\^`\opwarning` `{<text>}` prints <text> to the terminal and .log file as warning.\nl -\~`\private`` <sequence> <sequence> ... ;` declares <sequence>s for private name space.\nl -\~`\public`` <sequence> <sequence> ... ;` declares <sequence>s for public name space.\nl -\~`\readkv` `\macro` reads parameters from `\macro` in key-value format.\nl -\^`\replstring`` \macro{<stringA>}{<stringB>}` replaces all <stringA> to <stringB> in `\macro`.\nl -\^`\sdef` `{<string>}<parameters>{<body>}` behaves like `\def\<string><parameters>{<body>}`.\nl -\^`\setctable` and \^`\restorectable` manipulate with stack of catcode tables.\nl -\^`\slet` `{<stringA>}{<stringB>}` behaves like `\let\<stringA>=\<stringB>`\nl -\^`\sxdef` `{<string>}<parameters>{<body>}` behaves like `\xdef\<string><parameters>{<body>}`.\nl -\^`\trycs`` {<string>}{<text>}` expands `\<string>` if it is defined else expands <text>.\nl -\^`\useit` `<one>`, \^`\usesecond` `<one><two>` uses given parameter.\nl -\^`\wlog`` {<text>}` writes <text> to .log file.\nl -\^`\wterm`` {<text>}` writes <text> to the terminal and .log file.\nl -\^`\xargs`` <what> <token> <token> ... ;` repeats <what><token> for each <token>.\nl -\unpenalty\unskip - -\sec Compatibility with Plain \TeX/ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -All macros of Plain \TeX/ are re-written in \OpTeX/. Common macros should -work in the same sense as in original Plain \TeX. Internal control sequences -like `\p@` or `\f@@t` are removed and mostly replaced by control sequences -prefixed by `_` (like `\_this`). If you need to use the basic set of old Plain -\TeX/ control sequences like `\p@` (for example you are reading an old macro file), -use `\load[plain-at]`. - -All primitives and common macros have two -control sequences with the same meaning: in prefixed and unprefixed form. -For example `\hbox` is equal to `\_hbox`. -Internal macros of \OpTeX/ have and use only prefixed form. User should use -unprefixed forms, but prefixed forms are accessible too because the `_` is -set as a letter category code globally (in macro files and users document too). User -should re-define unprefixed forms of control sequences without worries that -something internal will be broken (only the sequence `\par` cannot be -re-defined without change of internal \TeX/ behavior because it is -hard-coded in \TeX/, unfortunately). - -\new -The Latin Modern 8bit fonts instead Computer Modern 7bit fonts are -preloaded in the format, but only a few ones. The full family set is ready to -use after the command \~`\fontfam[LMfonts]` which reads the fonts in OTF -format. - -\new -Plain \TeX/ defines `\newcount`, `\bye` etc. as `\outer` macros. \OpTeX/ -doesn't set any macro as `\outer`. Macros like `\TeX`, `\rm` are defined as -`\protected`. - -\new -The text accents macros `\"`, `\'`, `\v`, `\u`, `\=`, `\^`, `\.`, `\H`, -`\~`, \code{\\`}, `\t` are undefined\fnote -{The math accents macros like `\acute`, `\bar`, `\dot`, `\hat` still work.} -in \OpTeX/. Use real -letters like á, ř, ž in your source document instead of these old accents macros. -If you really want to use them, you can initialize them by the \^`\oldaccents` -command. But we don't recommend it. - -\new -The default paper size is not set as the letter with 1\,in margins but as A4 with -2.5\,cm margins. You can change it, for example by -\^`\margins/1 letter (1,1,1,1)in`. This example sets the classical Plain \TeX/ -page layout. - -\new -The origin for the typographical area is not at the top left 1\,in 1\,in coordinates -but at the top left paper corner exactly. For example, `\hoffset` includes directly left -margin. - -The tabbing macros `\settabs`\iindex{settabs} and `\+` (from Plain \TeX/) -are not defined in \OpTeX/ because they are obsolete. But you can use the -\ulink[http://petr.olsak.net/optex/optex-tricks.html\#tabs]{\OpTeX/ trick 0021} -if you really need such feature. - -The `\sec` macro is reserved for sections but original Plain \TeX/ declares this -control sequence for math secans. - -\enddocument - - -\sec Dependencies -%%%%%%%%%%%%%%%%% - -When `optex.fmt` is created then the following must be installed - -\begitems -* The `\luatex` program. -* Latin moder font metrics - `ec-lmr10.tfm`, `ec-lmbx10.tfm`, `ec-lmri10.tfm`, - `ec-lmbxi10.tfm`, `ec-lmtt10.tfm` (for basic text font initializing). -* Computer rmodern font metrics - `cmr10.tfm`, `cmmi10.tfm`, `cmsy10.tfm`, `cmex10.tfm` (for basic math - initializing). If there are more Computer Modern fonts then they are read - too. -* The file `hyphen.tex` form plain \TeX. -\enditems - -When `\fontfam` is used then the ability of Unicode fonts reading -is initialized using Lua scripts: `ltluatex.lua` (from \LaTeX/ package), -`luaotfload-main.lua` and more 20 similar `.lua` files (from `luaotfload` -package). - -When a font family is needed using `\fontfam` then such font family must be -installed in the OTF format otherwise, the `\fontfam` command is ignored -(only warning about no-existent font family is printed). - -When `\cslang`, `\delang` etc. commands are used in the document -then the hyphenation patterns of relevant languages must be installed. -Moreover the Lua script `luatex-hyphen.lua` (from `hyph-utf8` package) -and data file `language-dat.lua` (from `hyphen-base` package) -must be installed. - -When `\usebib` command is used then `librarian.tex` file -(from the `librarian` macro package) must be installed. - -When `\morecolors` command is used then `x11nam.def` file -(from the `xcolor` package) must be installed. - -When `\lorem` command is used then `lipsum.ltd.tex` file -(from the `lipsum` package) must be installed. - diff --git a/Master/texmf-dist/doc/optex/README b/Master/texmf-dist/doc/optex/README new file mode 100644 index 00000000000..b8f925e47c1 --- /dev/null +++ b/Master/texmf-dist/doc/optex/README @@ -0,0 +1,120 @@ +OpTeX: the LuaTeX format based on Plain TeX and OPmac + +Author: Petr Olsak, <petr@olsak.net> + +This software is in public domain. + +See http://petr.olsak.net/optex + +Files: + +base/ ... basic set of macro files used when optex.fmt is generated + and more basic macros loaded on demand during document processing. +demo/ ... examples: short document: op-demo.tex, short letter: op-letter.tex, + presentation slides: op-slides.tex. +pkg/ ... external macros. Maybe, they can be created by other authors if + the macro file conforms to the rules given in the section 2.2.5 + in the OpTeX documentation. +doc/ ... PDF version of the OpTeX documentation and sources. + +History: + +<1.01> Mar. 2021 + Minor code fixes (thanks to reports from users). + LibreCaslon font file added. + two new callbacks from new LuaTeX 1.13 added to optex.lua + active * (in lists) works as normal in math mode. + f-heros(\slides): additional font XITSMath loaded (to the base FiraMath font). + \_xhsize seting added to \margins. +<1.00> Feb. 2021 + The OMLS (OpTeX Markup Language Standard) was developed. It helps to create + convertors from/to OpTeX documents and similar applications. + \pdfunidef re-imeplemted. + \thisoutline introduced. + \verbchar introduced instead \activettchar. + Bugs fixing. +<0.19> Jan. 2021 + emoji support as pkg/emoji.opm. + non-braakable places generated by luavlna, suported as pkg/vlna.opm. + \begblock...\endblock introduced. + comment character allowed after \begtt. + more robust macros: \replstring, \table. + complete revision of documentation, spelling corrections. + Several bugs fixed. +<0.18> Dec. 2020 + Font support for next 9 families added. + Font selection system improved. + Documentation (especially about font selection system) corrected. + Macros supporting key=value included to the format. + \foreach macro improved. + Concept of multilang in bib rewritten. + \opwarning format changed (line numbers are printed too). + Several bugs fixed. +<0.17> Nov. 2020 + optex.lua introduced (instead external ltluatex.lua) + hyph.patterns are loaded directly by \patterns, not using lua code + \commentchars introduced (comments which are able to interrupt verbatim mode) +<0.16> Oct. 2020 + callback.register_x introduced, namespaces for packages corrected + kerkis and EBGaramond fontfiles added + little corrections + optex-math manual: Index added +<0.15> Jun. 2020 + Release for Overleaf - TL2020. + More vertical space above in \chap and \secc. +<0.14> Jun. 2020 + Typeseting Math with OpTeX: new document added. + Math macros corrected. + In-line verbatim in section titles allowed. + \eqbox implemented. + "\mnote up", "\displaylines to" (new features implemented) +<0.13> May 2020 + \table have more features: \tabskip, \table to, \table pxto, \vspan + The \eqalign reimplemented to be more flexible. + The boundary character ":" introduced in the \table. + \| undefined in 8bit math: bug fixed. + \isnextchar: \let\tmp=#1 -> \let\tmp= #1 +<0.12> May 2020 + The external macro qrcode.opm introduced + New directory structure: base/, demo/, pkg/, doc/ introduced. + \load macro introduced + \newif: bug fixed, other bug fixed. +<0.11> Apr. 2020 + \phi, \varpi in Unicode: bug fixed + \mathstyles introduced. +<0.10> Apr. 2020 + Technical documentation added + \_famdecl instedad \_fontdecl in font family files (incompatible change). +<0.09> Syntax highlighting implemented. +<0.08> \numberedpar implmented. \emergencystretch=20pt added as default. + \inoval, \incircle, \clipinoval, \clipincircle imlemented. + \puttext, \putpic x,y instead -y,x (incompatible change!) + footnotes have separated color stack now. + \fnotelinks implemented. + Lists by \begitems...\enditems improved (\novspaces \_vspacehalf, \ilevel). +<0.07> demos: op-letter.tex and op-slides.tex added. + \inkinspic, \transformbox, \slides added. + documentation improved and updated. +<0.06> tables re-implemented, opmac-rest removed. + footnotes, marginal notes reimplemented. + sections.opm, graphics.opm, colors.opm, languages re-implemented + Cite-bib re-implemented. + Index, sorting re-implemented. +<0.05> \boldmath reimplemented + \fontcolor, \letterspacing implemented + font catalogue improved +<0.04> references.opl, hyperlinks.opl re-implemented. + \fontfam, f-* rewritten: no usage of boundary "..." in \_fontnamegen + \fnote{...} corrected: (parameter is not really parameter) + verbatim.opl re-implemented + doc added + file-ref.opl implemented (new \_Xrefversion{3}) + bugfixing +<0.03> optex-doc optex.1 included, + verbatim.opm re-implmented, + math-unicode implemented, + usebib.opm + bib-style.opm included + \catcodetable stack implemented + bugfixing of macros. + catcodes.opl: removed, one can use \catcodetable, ... primitives, + pdfuni-string: lua code for lua5.3 fixed. +<0.02> Released. diff --git a/Master/texmf-dist/doc/optex/omls.tex b/Master/texmf-dist/doc/optex/omls.tex new file mode 100644 index 00000000000..bcc5749a512 --- /dev/null +++ b/Master/texmf-dist/doc/optex/omls.tex @@ -0,0 +1,832 @@ +\fontfam[lm] + +\adef<#1>{\ifcsname s:#1\endcsname + \link[s:#1]{}{\Blue$\langle$\hbox{\it#1\/}$\rangle$}% + \else {\Blue$\langle$\hbox{\it#1\/}$\rangle$}\fi} +\everyintt={\catcode`<=13 \Red} +\verbchar` +\enlang +\enquotes + +\def\r[#1]{\label[#1]\wlabel{\the\_itemnum}} +\def\:{$\to$} +\let\_narrowlastlinecentered=\ignoreit +\_def\_printsecc#1{\_par + \_abovetitle{\_penalty-200}{\_medskip\_smallskip} + {\_seccfont \_noindent \_raggedright \_printrefnum[@\_quad]% + \_label[\the\_secnum.\the\_seccnum]\wlabel{\the\_secnum.\the\_seccnum}#1\_nbpar}% + \_nobreak \_belowtitle{\_medskip}% + \_firstnoindent +} +\def\.`{\bgroup\catcode`\ =12 \scancs} +\def\scancs#1{\egroup + \immediate\_wref\Xknowncs{\string#1{\the\_secnum.\the\_seccnum}}% + \ea`\string#1% +} +\def\printcs#1{\ea\printcsred\csstring#1;~\ref[#1] \ } +\def\printcsred,#1;{{\Red\tt \bslash#1}} +\def\printknowncs{\ifx\knowncslist\undefined \let\knowncslist=\empty \fi + \ifx\knowncslist\empty TeX me again...\else + \_dosorting\knowncslist \ea\xargs \ea\printcs \knowncslist;\fi} + +\def\~`<#1>`{<#1>\sxdef{s:#1}{}\dest[s:#1]} + +\refdecl{ + \def\knowncslist{}^^J + \def\Xknowncs#1#2{% + \sxdef{,\csstring#1}{#2}% + \global\ea\addto\ea\knowncslist\ea{\csname,\csstring#1\endcsname}% + } +} +\sdef{_item:c}{\pdfsave\llap{\pdfscale{1.3}{1.3}$\circ$\enspace}\pdfrestore} + +%\parindent=15pt \iindent=\parindent \ttindent=\parindent +%\ttindent=0pt +\everylist={\advance\ttindent by-1em} +\hyperlinks \Green \Green +\def\cskip{\par\nobreak} +\def\begblock{\medskip\hbox\bgroup\vrule\vbox\bgroup\hrule\smallskip + \_fnset\leftskip=\parindent \rightskip=\parindent \medskip\noindent} +\def\endblock{\medskip\hrule\egroup\vrule\egroup} + +\def\raggedright{\rightskip=10pt plus1fil\relax} +\def\optexmanual{\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf]{\OpTeX/ manual}} + +\titskip=1cm + +\hfill Version 0.1 + +\tit \OpTeX/ Markup Language Standard + +{\it\hfil Petr Olšák, 2021}\bigskip + +The \OpTeX/ markup language standard (OMLS) declares a list of control +sequences used in \OpTeX/ documents including their syntax and sematic. The +listed control sequences in OMLS in section~\ref[listcs] in table~\ref[alistcs] +are called {\it known} and other control sequences are {\it unknown}. + +The main reason for OMLS is to give instructions on how to program convertors +from \OpTeX/ documents to another formats (Html, Markdown, \LaTeX/) or how +to interpret the \OpTeX/ document sources in such applications as +{\tt texcount} or text editors\fnote +{We suppose advanced editor features: color highlighting, sections/chapters folding, + auto-completions, etc.}. +These converters and applications are called {\it cnv-programs} in this document. + +We suppose that if you need absolute control over the typography of the +document when it is converted to PDF pages, then you use \OpTeX/ itself. If +you need to create other formats of the same document then you can use a +cnv-program which accepts OMLS. The result is a document without +typographical instructions like dimensions of pages, margins, paginations +and headers, selection of a font-family, dimensions of the fonts, etc.\ You can +imagine the result of such a conversion as a single Html page where more +typographical features can be controlled in a different way, for example by +an external CSS file. This is a reason why control sequences like `\fontfam` or +`\margins` are ignored by cnv-programs. + +Obviously, \TeX/ and \OpTeX/ itself gives possibility to declare various +input formats for various purposes. Sometimes (in very special cases) there +exists a good reason to declare a different and special input format by +\TeX/ macros. But if the source of the document respects the OMLS then it is +reasonably transformable to other formats by cnv-programs. We hope that +OMLS-ready documents cover a very large set of typical documents used these +days. + +We suppose that cnv-programs work internally with strings of source lines +without tokenization. This is one of the great differences in processing the +document directly by \OpTeX/ and using a cnv-program. The second difference is +that the expansion process of macros is not implemented in cnv-programs in +its full range. We respect that the result of cnv-programs will be different +than from processing directly by \OpTeX/. But this is not a bug, this is +the feature. We concentrate on the fixed syntax and sematic given by OMLS of the +\OpTeX/ document and we throw behind the head the typographical +exactness of the document which can be done only directly by \TeX/ (and it is +exactly described in \TeX/book, for example). + +\notoc\nonum\sec Table of contents + +\begmulti 2 +\maketoc +\endmulti +\vfil\break + +\sec Syntactical rules + +The syntactical elements are described as strings here. No \TeX/'s tokenization is +taken into account. The rule with a smaller number has precedence. + +\begitems \style n +* end of line or end of file \: \~`<eol>`.\r[eol] +* `%%:` at beginning of the line \: \~`<cnv-declarator>`, see section~\ref[cnv-decl]. +* `<cnv-declarator><text><eol>` is interpreted specially. +* space or a tab-character \: \~`<space>`. +* non-empty sequence of `<space>`s \: \~`<spaces>`.\r[spcs] +* an empty line or a line only with `<spaces>` \: \~`<empty-line>`. +* a character `a`--`z` or `A`--`Z` \: \~`<letter>`. +* a `<letter>` or `_` \: \~`<specletter>`. +* a character different from previous rule or `<eol>` or `<spaces>` \: \~`<non-specletter>` +* `\<non-specletter>` \: \~`<singlechar-control-sequence>`.\r[scs] +* a non-empty sequence of `<specletter>`s \: \~`<letters-seq>`. +* `\<letters-seq><non-specletter>` \: \~`<multiletter-control-sequence>``<non-specletter>`. +* `%<text><eol>` \: `<comment>` and it is completely ignored including `<eol>`.\r[com] +* `<spaces>` at beginning of the line marks that the line as {\it indented}. +* `<spaces>` at beginning of the line \: are ignored.\r[bspace] +* `<spaces><eol>` or `<eol>` \: `<spaces>`.\r[eolrm] +* `<multileter-control-sequence><spaces>` \: `<multileter-control-sequence>`.\r[csspace] +* `<multiletter-control-sequence>` or `<singlechar-control-sequence>` \: \~`<control-sequence>`.\r[cs] +* `<spaces>` \: `<space>`.\r[sspace] +* `~` \: non-breakable space. +* text where all pairs `{` and `}` match at arbitrary level \: \~`<balanced-text>`.\r[balt] +* `{<balanced-text>}` can be interpreted as a parameter of a `<control-sequence>`, see section~\ref[listcs]. +* The `{` alone not used by previous rule opens a group and the `}` alone closes the same group.\r[group] +* There are two main modes: h-mode, v-mode\fnote + {this is great simplification of real \TeX/ modes.}. + The document processing starts in v-mode. +* In v-mode: a `<non-space>` character or a control sequence listed + in table~\ref[vtohmode] swithes to h-mode. +* In h-mode: an `<empty-line>` or a control sequence listed in table~\ref[htovmode] switches to v-mode.\r[htov] +* The switching from v-mode to h-mode \: a paragraph begins. +* The switching from h-mode to v-mode \: the current paragraph ends. +* `$<text>$` or `$$<text>$$` \: process `<text>` in math-mode, see section~\ref[math]. +* a non-empty sequence of digits with optional `+` or `-` in the front \: \~`<number>`. +* `<number>` with optional dot inside the sequence of digits \: \~`<decimal-number>`. +* a pair of letters listed in the table~\ref[tex-units] \: \~`<tex-unit>`. +* optional space, i.e.\ `<space>` or nothing \: \~`<o-space>`. +* `<decimal-number><o-space><tex-unit><o-space>` \: \~`<dimen>`. +* `<control-sequence>` not listed in table~\ref[alistcs] nor in configuration \: \~`<unknown-control-sequence>`.\r[unkncs] +* `=<o-space>` or `<o-space>` \: \~`<o-equal>`. +* `<unknown-control-sequence><o-equal><dimen>` \: should be completely ignored.\r[eqdim] +* `<unknown-control-sequence><o-equal><number>` \: should be completely ignored. +* `<unknown-control-sequence>=<o-space>{<balanced-text>}` \: should be completely ignored. +* `<unknown-control-sequence>[<balanced-text>]` \: should be completely ignored.\r[ibkt] +* `<unknown-control-sequence>` \: should be ignored.\r[ignore] +* `<control-sequence>`s are processed as described in section~\ref[listcs] or + by a configuration of the cnv-program. +\enditems + +\bigskip +\label[vtohmode]\caption/t +List of control sequences which switch from v-mode to h-mode. +\cskip +\begblock +`\`<space>, +`\hfil`, +`\hfill`, +`\hskip`, +`\hss`, +`\indent`, +`\leavevmode`, +`\noindent`, +`\quad`, +`\qquad`, +`\vrule`. +\endblock + +\bigskip +\label[htovmode]\caption/t +List of control sequences which switch from h-mode to v-mode. +\cskip +\begblock +`\begblock`, +`\begitems`, +`\begmulti`, +`\begtt`, +`\bib`, +`\bigskip`, +`\bye`, +`\caption`, +`\chap`, +`\cskip`, +`\end`, +`\endblock`, +`\enditems`, +`\endmulti` +`\hrule`, +`\medskip`, +`\par`, +`\sec`, +`\secc`, +`\secl`, +`\smallskip`, +`\vfil`, +`\vskip`. +\endblock + +\bigskip +\label[tex-units]\caption/t +List of \TeX/ units. +\cskip +\begblock +`bp`, +`cc`, +`cm`, +`dd`, +`em`, +`ex`, +`in`, +`mm`, +`pc`, +`pt`, +`sp`. +\endblock + +\nonum\secc Examples + +\begitems +* `\%` is `<control-sequence>` by rules \ref[scs], \ref[cs]. It does not start + comment, because rule \ref[scs] has precedence before rule \ref[com]. +* `\%<space>`: the `<space>` is kept, but `\foo<space>`: the space is removed + by rule~\ref[csspace]. +* `wordA<spaces><eol><spaces>wordB` is `wordA<space>wordB` by rules~\ref[bspace], + \ref[eolrm], and~\ref[sspace]. +* `\kern-3pt` should be ignored, because `\kern` is `<unknown-control-sequence>` and rule + \ref[eqdim] is applied. +* `\vskip42mm` should finalize paragraph in h-mode by rule~\ref[htov] and then it + is ignored by rule~\ref[eqdim] because `\vskip` is + `<unknown-control-sequence>` not listed in table~\ref[alistcs]. +* `\typosize[12/16]` is ignored by rule~\ref[ibkt]. +* `\foo{text}` is `{text}` (i.e. `text` in a group) by rules~\ref[ignore] and~\ref[group]. +\enditems + +\sec Scanning parameters + +If a control sequence listed in rules above or in the section~\ref[listcs] +has a parameter, the parameter is scanned +as a string with interpretation only those rules which are needed to +determine the boundary of the parameters. For example `\tit <title><eol>` +applies only rule~\ref[eol] during scanning the parameter, i.e.\ `<title>` +is a string telemetered by the end of the line or the end of the file. +Or `\fnote{<balanced-text>}` applies only rule~\ref[balt]. + +If the parameter is in the format `{<something>}` then the `<something>` is +always meant as `<balanced-text>`. We don't specify the type `<balanced-text>` +explicitly here, so we refer to `\fnote{<text>}` and not +`\fnote{<balanced-text>}`, for example. + +The spaces before the scanned parameter are optional +and they are ignored. Spaces inside `{`...`}` are not ignored. + +If the parameter is in the format `{<something>}` and the first non-space +character is not `{` then the parameter is this first non-space character or +a `<control-sequence>` if the first non-space character is~`\`. For example +`\fnote a` is equal to `\fnote{a}`. The difference from this rule is given +for `\input`, `\verbinput`,`\inspic` and `\inkinspic` control sequences in +section~\ref[listcs]. + +If the parameter is scanned as a string already then +all syntactical rules are applied when it is used. For example: +\begtt +\tit This is a title +\endtt +the parameter is scanned as `This is a title` and the rules~\ref[spcs] +and~\ref[sspace] are applied when it is used. + + +\sec Declaration and text parts of the document + +A typical \OpTeX/ document has two parts. A declaration part, where +macros are defined by `\def` and friends, fonts and sizes are declared, etc. +This part should be ignored by cnv-programs. +The second part includes the document text with a markup using well-declared control +sequences. The cnv-program has to interpret the second part. + +So, the cnv-program starts in declaration-skipping mode and it switches to +the text mode later. + +When cnv-program is in declaration-skipping mode then all indented lines are +ignored. And lines which begins by `}` or by a <control-sequence> not listed +in table~\ref[textopen] are ignored too. + +If the line begins by a character other than `}` or by a <control-sequence> +listed in table~\ref[textopen] then cnv-program switches to text mode. All +texts are interpreted from this line including this one. + +User can say explicitly where the second part of the document starts by +`%%:text` given at beginning of a line. Moreover, if `%%:decl` is given at +beginning of a line, then all text between `%%:decl` and `%%:text` is +ignored, only other possible `<cnv-declarator>`s are processed here. +It means that the declaration part and the text part of the document can be +simply determined by the pair `%%:decl` and `%%:text`. + +\bigskip +\label[textopen]\caption/t +List of control sequences which start the text mode. +\cskip +\begblock \raggedright +`\address`, +`\begblock`, +`\begitems`, +`\begmulti`, +`\begtt`, +`\bf`, +`\bi`, +`\bib`, +`\caption`, +`\cite`, +`\clipinoval`, +`\clipincircle`, +`\ecite`, +`\fnote`, +`\frame`, +`\hfil`, +`\hfill`, +`\ii`, +`\iid`, +`\incircle`, +`\inkinspic`, +`\inoval`, +`\inspic`, +`\it`, +`\LaTeX`, +`\LuaTeX`, +`\maketoc`, +`\mnote`, +`\OpTeX`, +`\putpic`, +`\puttext`, +`\rcite`, +`\rm`, +`\rotbox`, +`\sec`, +`\secc`, +`\secl`, +`\table`, +`\TeX`, +`\tit`, +`\usebib`, +`\verbinput`. +\endblock + + +\sec[cnv-decl] The `%%:` declarators + +The `%%:` declarators are ignored when the document is processed by \TeX/ +but they can give instructions to cnv-programs. The `%%:` must be placed at +beginning of the line. The list of `%%:` declarators follows: + +\begitems +* `%%:decl` -- the following text is ignored until `%%:text` occurs. Only + other `%%:` declarators are interpreted. +* `%%:text` -- the following text must be interpreted in text mode. +* `%%:to <format> <config-file>` -- if the cnv-program converts to the + <format> then it has to use the <config-file>. For example: + \begtt + %%:to html html-mydocument.cfg + %%:to markdown markdown-mydocument.cfg + %%:to latex preamble-mydocument.cfg + \endtt + The language of the config files are not a part of this standard, we + suppose something to be natural for used cnv-program. The config file should + give additional rules for interpreting control sequences not listed in the + section~\ref[listcs] (see rule~\ref[unkncs]). For example a tool for + defining a behavior of unknown control sequences can be here. + These definitions can depend on the converted document and on the output + format and they can be given in the configuration files. +* `%%:app <application> <config-file>` -- behaves like `%%;to` but the + cnv-program name instead output format is given here. +* `%%:do <format-or-app> <action>` -- does an `<action>` if `<format-or-app>` + is output format or used cnv\hbox{-}program name. The `<action>` syntax depends + on used cnv-program and it typicaly does a change in its configuration or + give a command to it. +* `%%:skip <formats-or-apps>` -- ignores all following lines until another `%%:` occurs + if the output format or application name is included in the `<formats-or-apps>` + space-separated list. Example: + \begtt + %%:skip html markdown + This text is not interpreted when Html or Markdown output is generated. + %%: + \endtt + If the `<formats-or-apps>` is empty then the `%%:skip` is applied for + each cnv-program and for each output. +* `%%:if <formats-or-apps>` -- processes following lines until another `%%:` + only if the output format or application name is included in the + `<formats-or-apps>` space-separated list. Other cnv-programs or output formats + not mentioned here skip these lines. Note that \TeX/ processes such lines always. + But you can use `\ignoreit{<text>}` which is processed as + `{<text>}` by cnv-programs (see rule~\ref[ignore]) but it is ignored by \OpTeX. + Example: + \begtt + %%:if html latex + \ignoreit{\input{file.tex}} + %%: + \endtt + The `file.tex` in this example is processed only if \LaTeX/ or Html output is generated. +* `%%:use` -- the next single line is fully interpreted unless cnv-program ignores + declarations by `%%:decl` or because it is in declaration-skipping mode. + Example: + \begtt + %%:use + \verbchar` \picdir={img/} + \endtt + The example shows how cnv-program is able to read `\verbchar` or + `\picdir` settings in the declaration\hbox{-}skipping mode although these control + sequences are not listed in table~\ref[textopen]. +* `%%:quotes <qql> <qqr> <ql> <qr>` -- declares \~`<qql>` and \~`<qqr>` (left + and right double quotation marks), \~`<ql>` and \~`<qr>` (left and right single + quotation mark). They are used when `\"` or `\'` control sequences are + processed. Default: unset, i.e.\ `\"` and `\'` are interpreted as + unknown control sequences. +\enditems + + +\sec[listcs] List of known control sequences + +The phrase \"should be" is used very often when the interpretation of +control sequences is declared here. It means that this is only a common +interpretation, but differences are possible due to the type of the output +format and used cnv-program. For example, when we convert to \LaTeX\, then +`\-` and `\/` are not ignored but they are re-written without change to the +output of the \LaTeX/ source file. + +\bigskip +\label[alistcs] +\caption/t List of known control sequences alphabeticaly sorted. +\cskip +\begblock +\raggedright \printknowncs +\endblock + + +\secc Character-like control sequences + +\begitems +* \.`\%`, \.`\$`, \.`\&`,\.`\#` respectively \: should be normal characters + `%`, `$`, `&`, `#` respectively. +* \.`\bslash` \: normal character `\`. +* \.`\space`, `\<space>`, `\<eol>` \: space. +* `\,` \: should be small space or space. +* \.`\quad`, \.`\qquad` \: should be bigger space or more spaces. +* \.`\-`, \.`\/` \: should be ignored. +* \.`\"<text>"` or \.`\'<text>'` \: `<qql><text><qqr>` or `<ql><text><qr>`, + only if `%%:quotes` are set. +\enditems + +\secc Input files + +\begitems +* \.`\input {<file-name>}` or `\input <file-name><space>` should redirect the + input to given file. At the end of the input-ed file or at \.`\endinput` the + reading of the current file continues. The file is read from the current + directory, but the <file-name> should include the full path to the file + or relative path starting from the current directory. First, the file + `<file-name>.tex` is tried to read and if it doesn't exist then + the file `<file-name>` is read. +* \.`\picdir <o-equal>{<text>}` saves `<text>` to `<picdir-value>`. By + default, `<picdir-value>` is empty. +* \.`\inspic {<file-name>}` or `\inspic <file-name><space>` should include the + given picture from the `<picdir-value><file-name>`. +* \.`\inkinspic {<file-name>}` or `\inkinspic <file-name><space>` behaves like + `\inspic`. +* \.`\verinput <ignore> (<lines>) <file-name><space>` should include the + <file-name> (only given lines) as a verbatim text, i.\,e. without any + syntactical interpretation. +* \.`\usebib/<letter> (<style>) <file-names>` should use files from + `<file-names>` to generate the list of bib references. The `<file-names>` + is comma separated list (the `.bib` extension is appended to + each such file name). Only cited bib records should be used in this + bib-references, i.e. their label must be used in a `\cite[<labels>]` or + `\rcite[<labels>]` or `\ecite[<label>]`. + What bib fields are used in bib records depends on the cnv-program and + on its configuration. Maybe, simple cnv-programs should generate nothing here. +\enditems + +\secc Titles + +\begitems +* \.`\tit <title><eof>` should be a title of the document. +* \.`\chap <title><eof>` or `\chap [<label>] <title><eof>` is the title of + first level. +* \.`\sec <title><eof>` or `\sec [<label>] <title><eof>` is the title of + second level. +* \.`\secc <title><eof>` or `\secc [<label>] <title><eof>` is the title of + third level. +* \.`\secl<level> <title><eof>` is the title of given level. +\enditems + +\secc Fonts + +\.`\rm` selects upright normal font (it is selected by default), \.`\it` selects +italic, \.`\bf` selects upright bold font, \.`\bi` selects bold italic and +\.`\tt` selects a monospaced font, \.`\em` select italic (if upright is current) or upright +(if italic is current). The font sizes or other font features are typically ignored +by cnv-programs. The actual font selection is closed at the end of the current group. +The groups are given: +\begitems +* explicitly by `{` and `}` characters (which are not delimiters of + parameters of known control sequences), +* implicitly: parameters of control sequences listed in table~\ref[groupcs] + are processed in a group and blocks of text enclosed by + `\begitems`...`\enditems`, `\begblock`...`\endblock`, `\begmulti`...`\endmulti` + are processed in a group. + Each item in `\table` is in a group. +\enditems + +\label[groupcs] +\caption/t Parameters of following control sequences are processed in a group. +\cskip +\begblock +`\caption`, +`\chap`, +`\fnote`, +`\mnote`, +`\sec`, +`\secc`, +`\tit`. +\endblock + +\secc Colors + +\.`\Red`, \.`\Green`, \.`\Blue`, \.`\Cyan`, \.`\Magenta`, \.`\Yellow`, \.`\White`, +\.`\Black`, and \.`\Brown` should select the given color of the font. The selection +is closed at the end of the current group (like font selectors). + +\secc Blockquotes + +The blockquote\fnote +{The terminology is borrowed from Markdown.} +is opened by \.`\begblock` and closed by \.`\endblock`. +Blockquotes can contain multiple paragraphs and can contain nested +blockquotes. + +\secc Lists + +The list is opened by \.`\begitems` and closed by \.`\enditems`. The `*` starts +a new item in this environment. Nested lists are allowed. + +The type of items (ordered/unordered) +is given by \.`\style <character>`, see section 1.4.5 in the +\optexmanual. Default type is unordered (bullets are used). + + +\secc Code blocks (verbatim texts) + +Code blocks are inline verbatim or display verbatim. + +\begitems +* \.`\begtt <ignored><eol><text>\endtt<ignored><eol>` processes `<text>` in + \"display verbatim mode", i.\,e. there are no special characters, each character + is processed without special interpretation, the <eol>s are end of lines. + The text at the same line after `\begtt` and after `\endtt` (if any) is + ignored. +* \.`\verbchar <character>` declares `<verbchar>`. By default, it is undeclared.\nl + New `\verbchar <character>` rewrites previous setting. The setting is + local in the group. +* Inline verbatim is enclosed in the pairs of `<verbchar>`s. + The text between two `<verbchar>`s is processed without special interpretation. + Only possibly <eol>s are replaced by space. + Example: + \begtt + %%:use + \verbchar` + Now, `$this %text ~\` is processed as inline verbatim. + \endtt + gives: Now, `$this %text ~\` is processed as inline verbatim. +* \.`\code{<text>}` processes `<text>` like inline verbatim, but + all `\<character>` are processed as `<character>`, specially `\{` and `\}` + are `{` and `}` but without taking them into `<balanced-text>` rule, + `\\` is `\` but do not create a `<control-sequence>`, etc. +\enditems + + +\secc Multicolumns + +\.`\begmulti <number><space>` opens the group and \.`\endmulti` +closes the group. If output format allows multi-columns then +the text enclosed between `\begmulti <number><space>` and matching +`\endmulti` should be printed in `<number>` balanced columns. + + +\secc Links + +\begitems +* \.`\url{<text>}` creates `<text>` as an external link which points to `<text>`. + The `\<character>` is interpreted as `<character>` in `<text>` with one + exception: `\|` is ignored. +* \.`\ulink[<url>]{<text>}` creates `<text>` as an external link which points + to `<url>`. The `\<character>` is interpreted as `<character>` only in + `<url>` parameter. +* \.`\label[<label>]` sets the `<label>`. First following occurence of `\chap`, `\sec`, + `\secc`, `\caption` or `\eqmark` sets this `<label>` as bounded to its + position in the document. +* \.`\ref[<label>]` should create an internal link to the position given by + `\chap`, `\sec`, `\secc`, `\caption` or `\eqmark`, + if `[<label>]` is used as the parameter of this control sequence + else if `<label>` is bounded here by previous `\label[<label>]` + The visual aspect of the link + is not declared by OMLS because we don't suppose that the chapters, + sections, equations, etc.\ are automatically numbered by exactly the same way as in + \OpTeX/. A recommendation should be: create a simple sequence of numbers over + all internal links. +* \.`\pgref[<label>]` should be replaced by `??` if cnv-program generates single-page + output (like Html, Markdown). Unfortunately, we get the irrelevant phrases in the output: + \"{\tt The problem is shown at the page ??}". + Users can declare `%%:skip` for such cases. +* \.`\bib[<label>]` or `\bib[<label>]<o-space>=<o-space>{<ignored>}` should open the new bib + record. More exactly, it closes previous paragraph (if h-mode is current) + and opens new h-mode. Then prints an auto-generated reference number in + `[...]`. Following text is interpreted as a bib record until the h-mode ends. +* \.`\cite[<labels>]` should create internal links to corresponding bib + records generated by `\usebib` or by `\bib`. The `<labels>` is a comma-separated list + of labels used in `.bib` files or in `\bib` commands to indicate + the corresponding bib record. The labels should be replaced by auto-generated + reference numbers used in bib records. All reference numbers created by + single `\cite` should be enclosed by single `[...]`. These numbers are + internal links. If the cnv-program does not implement this complicated + bib machinery then `\cite[<labels>]` should print only `[<labels>]`. +* \.`\rcite[<labels>]` does the same as `\cite[<labels>]` but doesn't print + outer `[...]`. +* \.`\ecite[<label>]{<text>}` creates the link to corresponding bib record, + `<text>` is is hyperlinked (no the auto-generated reference number). +* \.`\maketoc` should create a list of titles from all `\chap`, `\sec` and `\secc` + used in the document if they are not preceded by \.`\notoc`. All lines in + this list should include internal links to the position where the corresponding title + is used. +\enditems + +\secc Tables + +\begitems +* \.`\caption/<letter>` opens a caption. More exactly, if current mode is + h-mode, then switch to v-mode first (i.e.\ close the current paragraph). + Then switch from v-mode to h-mode and put a <caption-head>. The following + text should be interpreted as the caption text until h-mode ends. + If <letter> is `t` then <caption-head> is `Table` followed + by an auto-generated number. If the <letter> is `f` then <caption-head> is + `Figure` followed by an auto-generated number. The configuration of + cnv-programs shoud allow different words than default `Table` or `Figure` (for + example, if another language is used). +* \.`\table<ignored>{<declaration>}{<data>}` should create a table. The fidelity + rate of created output depends heavily on the used cnv-program and the output + format. We don't suppose that all aspects of \OpTeX/ tables are implemented. + The following features are listed in their priority of implementation. + \begitems \style c + * Items in `<data>` are separated by `&`. + The last item in each row is separated by end-row separator: \.`\cr`, \.`\crl`, \.`\crll`, + \.`\crli`, \.`\crlli`, or \.`\crlp{<list>}`. If there are $n$ columns in + the table then we have $n-1$ `&` separators and one end-row separator + for each table row. + There can be an optional end-row separator at the first item in `<data>` and + it should be ignored. The `<data>` can end without the end-row separator, it + should be added here. + * Spaces around `&` and before end-row separator are ignored. + * \.`\noalign{<text>}` and \.`\tskip <dimen>` should be ignored. + * Colum declarators in <declaration> should be interpreted: `l` (left aligned), `c` (center + aligned), `r` (right aligned) or `p{<ignored>}` (paragraph-like item). + * The `<number><letter>` or `<number>{<text>}` should be interpreted as + `<number>`-times repeated `<letter>` or `<text>` in `<declaration>`. + * \.`\vspan<decimal-number>{<text>}` should be an item with only `<text>`. + * \.`\mspan<number>[<decl>]{<text>}` should create `<text>` as an item which + spans over `<number>` columns. It is used instead `<number>` real + items, i.e.\ `<number>`$-1$ separators `&` aren't used here. + * Rules in the table should be interpreted, i.e. `|` in <declaration> + should be not ignored and + various end-row separators should be distinguished (see \optexmanual, + section 1.4.6). + * The aligning of `p{<p-data>}` columns should be interpreded by reading + \.`\fL`, \.`\fR`, \.`\fC`, \.`\fS` and \.`\fX` control sequences in `<p-data>`. + See \optexmanual, section 1.4.6. + \enditems +\enditems + +\secc Footnotes, marginal notes + +\begitems +* \.`\fnote{<text>}` should create a footnote link as an auto-generated + reference number. + The `<text>` should be appended at the end of the document labeled by this + reference number. Another alternative (for Html output, for example): the mouse over + the reference number riases an auto-popup `<text>`. +* \.`\fnotemark<number>` should create a pointer to a next declared + footnote as auto-generated reference number. The `<text>` of the footnote is + declared after that by \.`\fnotetext{<text>}`. Exact behavior: if the + reference number of the last processed `\fnote` is $n$ then + `\fnotemark<number>` uses the value + $n+{}$`<number>` as its reference number. A set of `\fnotemark`s + is followed by an equally large set of `\fnotetext{<text>}`. First one + have reference number $n+1$, second $n+2$, etc. When whole set of `\fnotetext{<text>}` + is processed then $n$ is reset to the last reference number used here. +* \.`\mnote <ignored>{<text>}` should be created as auto-popup `<text>` or the `<text>` + is inserted at the margin. +\enditems + +\secc Tagging for index + +We don't suppose that the cnv-program can generate the alphabetically sorted +index. So, the markup for creating the index should be ignored: + +\begitems +* \.`\ii <word><space>` (where `<word>` is a sequence of non-space characters) + should be ignored. +* \.`\iid <word><space>` is `<word><space>` by default, but + if `,` or `.` follows after `<space>` then the `<space>` is removed. +\enditems + +\secc Logos + +\.`\TeX`, \.`\LuaTeX`, \.`\OpTeX`, \.`\LaTeX`, respectively \: +`TeX`, `LuaTeX`, `OpTeX`, `LaTeX`, respectively. If `/` follows +these control sequences then it is ignored. Other logos should be declared +in the configuration of the cnv-program. + +\secc What should be ignored + +\begitems +* \.`\def<text>{<text>}` and other variants with \.`\gdef`, \.`\edef`, \.`\xdef`. + Reason: user can insert a special definition in the `%%:text` part of the + document in order to solve a problem. But cnv-program should ignore~it. +* \.`\outlines{<text>}`, \.`\insertoutline{<text>}` and \.`\thisoutline{<text>}`. +\enditems + + +\sec[math] Math mode processing + +There are two math modes, inline: `$<formula>$` or display: `$$<formula>$$`. +We suppose that `<formula>` will be processed by MathJax or similar +software. So, the `<formula>` should be kept without changes in cnv-program +output, but there are exceptions: + +\begitems +* `$<sign><decimal-number>$` should be transformed to non-math text + `<sign><decimal-number>`. The `<sign>` is~`+` or~`-` or nothing. + The `<decimal-number>` can include `,` (comma) instead `.` (period). + If the `<sign>` is~`-` (character U+002D) then + it must be converted to `−` (character U+2212, math minus). +* `{\bbchar <text>}` should be converted to `\mathbb{<text>}`, because + MathJax doesn't understand `\bbchar`. `$\bbchar <text>$` should be + converted to `$\mathbb{<text>}$`. +* `{\frak <text>}` or `$\frak <text>$` \: + `\mathfrak{<text>}` or `$\mathfrak{<text>}$`. +* `{\script <text>}` or `$\script <text>$` \: + `\mathscr{<text>}` or `$\mathscr{<text>}$`. +* `\eqmark`, `\eqmark[<label>]` \: `\leqno (<num>)`, where `<num>` is + auto-generated number. Or it should be completely ignored. +* It is strongly recommended to allow users to declare another replacement + rules over `<formula>` in configuration files of cnv-programs. +\enditems + + +\sec Notes on various conversions + +The cnv-programs behave differently because output formats have different +concepts and are intended for different purposes. The following sections +mention the main differences for typical conversions. + +\secc To Html + +The Html document is one single page. If we want to split the document to more +pages, then we can use `%%:do html <action>` in positions where the document +should be split (the syntax of `<action>` depends on the used cnv-program.) + +The design of Html pages should be declared by CSS files. + +Pictures inserted by `\inspic` should be inserted into the Html page as +\code{<img src="...">}, so the picture files must be installed in +the webserver to render the Html page correctly in a web browser. + +The `\maketoc` used in the \OpTeX/ document means that the Table of contents should +be here. It should be generated by the cnv-program, two-pass processing is +needed because the cnv-program needs to read all titles of `\chap`, `\sec` and +`\secc`. Another approach is to read the `.ref` file produced by \OpTeX/. + + +\secc To Markdown + +Markdown source file is \"one-page document" too. The principles a +re similar to conversion to Html. + +\secc From Markdown + +The cnv-program which does such a reverse conversion should be very useful for +people they prefer even clearer markup than in \OpTeX/. + +\secc To \LaTeX + +\LaTeX/ gives the same main feature as \OpTeX/: it can generate PDF +output from a source file. But different macros, a different concept, and +a different markup are used. + +The main reason for such conversion is that journal editors +require \LaTeX/ source file, but user want to prepare their real document in +more comfortable (\OpTeX/) markup and with more simple macros. + +This conversion should keep almost all features. For example, the +`\pgref[<label>]` is converted to `\pageref{<label>}`. The cnv-program +needs not to generate a Table of contents, bibliography references, etc. Only +appropriate \LaTeX/ markup must be used. + +The contents of generated \LaTeX/ preamble should be configurable. + + +\secc From \LaTeX + +The reverse conversion from \LaTeX/ to \OpTeX/ can be usable +for people, they want to switch to creating their documents in \OpTeX/. + +The cnv-program must solve additional problem in this type of conversion. +There are various math \LaTeX/ environments, they must be converted to +plain~\TeX/ syntax of math typesetting. For example:\nl +`\begin{array}...\end{array}` \: `\matrix{...}`,\nl +`\begin{align*}...\end{align*}` \: `$$\eqalign{...}$$`\nl +`\frac{...}{...}` \: `{...\over...}`. + +\bye diff --git a/Master/texmf-dist/doc/optex/optex-doc.pdf b/Master/texmf-dist/doc/optex/optex-doc.pdf new file mode 100644 index 00000000000..a4df4f013ab Binary files /dev/null and b/Master/texmf-dist/doc/optex/optex-doc.pdf differ diff --git a/Master/texmf-dist/doc/optex/optex-doc.tex b/Master/texmf-dist/doc/optex/optex-doc.tex new file mode 100644 index 00000000000..9f2fadeeb4a --- /dev/null +++ b/Master/texmf-dist/doc/optex/optex-doc.tex @@ -0,0 +1,114 @@ +%% This is part of the OpTeX project, see http://petr.olsak.net/optex + +% Run optex optex-doc +% (three times) to generate OpTeX documentation including references and the index. + +\load [doc.opm] \let\enddocument=\endinput + +\typosize[10/12] % Main size (used in techdoc) + +\begingroup \typosize [11/13.5] % Different size used in useroc. + +\insertoutline{OpTeX} % PDF outlines generated from TOC + +% Title: + +\vglue1cm +\centerline{\setfontsize{at50pt}\rm\OpTeX} +\vskip-8mm + +\tit Format Based on Plain \TeX/ and OPmac\fnotemark1 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\hfill Version 1.01 + +\centerline{\it Petr Olšák, 2020, 2021} + +\bigskip +\centerline{\url{http://petr.olsak.net/optex}} + +\fnotetext {OPmac package is a set of simple additional macros to Plain \TeX{}. +It enables users to take advantage of \LaTeX/ functionality but keeps +Plain \TeX/ simplicity. See +\url{http://petr.olsak.net/opmac-e.html} for more information about it.} + +\bigskip +\noindent +\OpTeX/ is \LuaTeX/ format with Plain \TeX/ and OPmac. Only \LuaTeX/ engine +is supported. + +\OpTeX/ should be a modern Plain \TeX/ with power from OPmac (Fonts +Selection System, colors, graphics, references, hyperlinks, +indexing, bibliography, ...) with preferred Unicode fonts. + +The main goal of \OpTeX/ is: + +\begitems +* \OpTeX/ keeps the simplicity (like in Plain \TeX/ and OPmac macros). +* There is no old obscurities concerning various 8-bit encodings and + various engines. +* \OpTeX/ provides a powerful Fonts Selection System (for Unicode font + families, of course). +* \OpTeX/ supports hyphenations of all languages installed in your \TeX/ system. +* All features from OPmac macros are copied. For example sorting words in + the Index\fnotemark1, reading `.bib` files directly\fnotemark1, syntax + highlighting\fnotemark1, colors, graphics, hyperlinks, references). + \fnotetext{All these features are implemented by \TeX/ macros, no external + program is needed.} +* Macros are documented in the same place where code is. +* User namespace of control sequences is separated from the internal namespace + of \OpTeX/ and primitives (`\foo` versus `\_foo`). + The namespaces for macro writers are designed too. +\enditems + +If you need to customize your document or you need to use something +very specific, then you can copy relevant parts of \OpTeX/ macros into your macro +file and do changes to these macros here. This is a significant difference from +\LaTeX/ or ConTeXt, which is an attempt to create a new user level with a +plenty of non-primitive parameters and syntax hiding \TeX/ internals. +The macros from \OpTeX/ are simple and straightforward because they solve only +what is explicitly needed, they do not create a new user level for +controlling your document. We are using \TeX/ directly in this case. +You can use \OpTeX/ macros, understand them, and modify them. + +\OpTeX/ offers a markup language for authors of texts (like \LaTeX), +i.\,e.\ the fixed set of tags to define the structure of the document. This +markup is different from the \LaTeX{} markup. It may offer to write the +source text of the document somewhat clearer and more attractive. + +The manual includes two parts: user documentation and technical +documentation. The second part is generated directly from the sources of +\OpTeX/. There are many hyperlinks from one part to second and vice versa. + +This manual describes \OpTeX/ features only. We suppose that the user knows \TeX/ +basics. They are described in many books. You can see a short +document \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf] +{\TeX/ in nutshell} too. + +\vfil\break + +\insertoutline{CONTENTS} \outlines{0} + +\notoc\nonum \sec Contents +\maketoc + +\thisoutline {USER DOCUMENTATION} + +\chap User documentation + +\input optex-userdoc +\endgroup + +%\end + +\input optex-techdoc + +\vfil\break + +\def\_printchap#1{\noindent{\_printrefnum[@]\_secfont #1}\medskip} + +\nonum\chap Index + +\begmulti 3 \tt \makeindex \endmulti + +\bye diff --git a/Master/texmf-dist/doc/optex/optex-math.tex b/Master/texmf-dist/doc/optex/optex-math.tex new file mode 100644 index 00000000000..789dd5a1877 --- /dev/null +++ b/Master/texmf-dist/doc/optex/optex-math.tex @@ -0,0 +1,1662 @@ +%% This is part of the OpTeX project, see http://petr.olsak.net/optex + +% Run optex optex-math (two times) to generate this document +% or look at PDF here: http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf + +\fontfam[lmfonts] + +\font\ttlib=[LiberationMono-Regular] +\def\ttspec{\let\_ttfont=\ttlib} + +\report + +\def\new #1 {\mnote{\Red$\blacktriangleleft$\,\sans\setfontsize{at9pt}\rm#1}} +\fixmnotes\right +\enquotes +\verbchar` +\catcode`\<=13 +\def<#1>{$\langle\hbox{\it#1\/}\rangle$} +\everyintt={\catcode`\<=13 } +\def\ss#1{$\vrule height3pt#1\vrule height3pt$} + +\addto\_secfont\Blue \addto\_seccfont\Blue +\_def\_printsec#1{\_par + \_abovetitle{\_penalty-400}\_bigskip + {{\_secfont \_noindent \_raggedright \llap{\_printrefnum[@\_quad]}#1}\_nbpar}\_insertmark{#1}% + \_nobreak \_belowtitle{\_medskip}% + \_firstnoindent +} +\_def\_printsecc#1{\_par + \_abovetitle{\_penalty-200}\_medskip + {{\_seccfont \_noindent \_raggedright \llap{\_printrefnum[@\_quad]}#1}\_nbpar}% + \_nobreak \_belowtitle{\_medskip}% + \_firstnoindent +} + +\def\i #1 {\ii .#1 \iis .#1 {{\code{\\#1}}}} +\def\x`{\bgroup\_setverb\xx} +\bgroup \lccode\string`\.=\string`\` \lowercase{\egroup \def\xx #1#2.{\i #2 \egroup `#1#2.}} + + +\hyperlinks\Green\Green + +\insertoutline{MATH} +\outlines{0} + + + +\tit Typesetting Math with \OpTeX/ + +\hfill Version 03, January 2021 + +\author Petr Olšák + + +This document is a brief summary of typesetting math. It describes \TeX/, +Plain \TeX/ and \OpTeX/ features concerned to math. The first two types of +features are documented in \TeX/book in chapters 16, 17, and 18, but it is +summarized here in short again in order to give a complete guide about math +typesetting for \OpTeX/ users. + +\new {} +The \OpTeX/ features which differs from standard \TeX/ or Plain \TeX/ are +documented with the red triangle at the margin (like in this paragraph). +Reader can simply distinguish between \"standard" features (given by +\TeX/ or Plain \TeX/) and new \OpTeX/ features. + +There are more types of extensions: e\TeX, lua\TeX/, Unicode math and +\OpTeX/ macros. The appropriate label (e\TeX, Lua\TeX/, Unicode, \OpTeX/) +is appended to the red triangle to inform you about the extension type. +Nevertheless, \OpTeX/ user doesn't have to worry about it, all extensions +are available if Unicode Math font is loaded (e.g., by the command +`\fonfam[lmfonts]`). See section 1.3.3 in \OpTeX/ documentation about +loading Unicode math fonts. + +{\iindent=2em +\bigskip +\maketoc } +\vfil\break + +\sec Basics structure of math formulas + +\secc General rules and terminology + +The \ii in-line/math in-line math (in the paragraph) is created by `$<math list>$`. The +\ii display/math display math (a standalone line between paragraphs) is created by `$$<math list>$$`. +More than one line can be here if an appropriate macro is used. In-line math is +processed in a \TeX/ group in \ii in-line/math/mode {\em in-line math mode}. The display math is +processed in a \TeX/ group in \ii display/math/mode {\em display math mode}. Spaces are +ignored in math modes, so `$x+y$` and `$x + y$` gives the same result: $x+y$. + +The \ii math/list <math list> is a sequence of \ii math/atom,atom {\em math atoms} and +\ii other/material {\em other material}. +The math atoms are \ii single/math/object {\em single math objects} or +\ii composed/math/atom composed math atoms. + +\begitems \hfuzz=.6pt +* The single math object is a single character to be printed in math mode + like `x`, `+`, `\int`. +* The math atom is constructed in general by `{<math list 1>}^{<math list 2>}_{<math list 3>}`. + It consists from \ii nucleus {\em nucleus} <math list 1>, \ii exponent exponent <math list 2> + and \ii subscript subscript <math list 3>. Each part of the atom should be empty. + If <math list 2> or <math list 3> is empty, we need not to write brackets and + the prefix `^` or `_`. + If the <math list 1> or <math list 2> or <math list 3> + consist only from a single math object then we need not use brackets. + For example + `x^2` is a math atom with `x` in the nucleus, `2` in the exponent, and with empty subscript. + Or `a_{i,j}` is a math atom with `a` in the nucleus, empty exponent, and `i,j` in the subscript.% + \fnote{In \OpTeX/, the character `_` can be interpreted as a part of + the control sequence name, not as the subscript constructor. But in common cases, + constructions of math atoms are interpreted exactly as in plain \TeX. See sections + 2.2.2 and 2.14 of \OpTeX/ documentation for more details. If you want to + be sure that `_` is just a subscript constructor in \OpTeX/ then you can set \code{\\catcode`\\_=8} + but after this, you cannot use control sequences with `_` character.} + The constructors for exponent `^` and subscript `_` can be used in arbitrary order + after the nucleus, for example, `z_1^{x+y}` is the same math atom as + `z^{x+y}_1`. The single math objects not followed by `^` nor `_` are + considered as math atoms with this object in the nucleus and with empty + exponent and subscript (this is a very common case). + \TeX/ assigns the \ii class {\em class} for each math atom, see section~\ref[class]. +* Other material can be \TeX/ box or glue (space) or `\kern` or `\vrule` etc. +\enditems + +Example: The `Z = \int``_\Omega x^{2y} + z\, dx` generates +$Z = \int_\Omega x^{2y} + z\, dx$ and it is <math list> which consists from: + +\begitems +* `Z` is math atom with empty exponent and subscript, class: Ord, +* `=` is math atom with empty exponent and subscript, class: Rel, +* `\int``_\Omega` is math atom with empty exponent and with subscript `\Omega`, class: Op, +* `x^{2y}` is math atom with exponent `2y` and empty subscript, class: Ord, + \begitems \let\_bullet=\circ + * `2` is math atom with empty exponent and subscript, class: Ord, + * `y` is math atom with empty exponent and subscript, class: Ord, + \enditems +* `+` is math atom with empty exponent and subscript, class: Bin, +* `z` is math atom with empty exponent and subscript, class: Ord, +* `\,` is another material, the glue (space) in this case, +* `d` is math atom with empty exponent and subscript, class: Ord, +* `x` is math atom with empty exponent and subscript, class: Ord. +\enditems + +\secc[class] Classes of math atoms + +\TeX/ assigns \ii class {\em a class} for each math atom.\fnote +{Using terminology of \TeX/book, each single math object has its {\em class} but the + math atom has its {\em kind} derived from this class. I use only one word + for both meanings in this document.} +This data type is used when +\TeX/ decides about \ii horizontal/spacing horizontal spaces between atoms in the output. (Note +that spaces in the input are ignored.) For example, +`$xy$` prints two atoms without space between them but `$x+y$` is printed with +small spaces around the `+` binary operator. Compare: $xy$ and $x+y$. + +The class is assigned depending on the nucleus of the atom. If the nucleus is +not a single math object, i.e. it is constructed by `{<math list>}` with braces +then the atom has its class Ord. If the nucleus is a single math object constructed +without braces then the class of the atom depends on this single math +object. Each single math object must be declared in \TeX/ with its default +class. The following table lists the classes with typical examples. +The full set of all math objects used in math typesetting +is listed in section~\ref[objects] with their default classes. + +\bigskip +\noindent\hfil\table{llll}{ + & \ii class Class & Meaning & Example \crl + 0 & \iid Ord & ordinary object & variables, digits, $x, {\bbchar R}, \Gamma, 0, 1$ \cr + 1 & \iid Op & big opertator & $\sum, \int, \bigcup$ \cr + 2 & \iid Bin & binary operator & $+, \times, -, \pm, \cup$ \cr + 3 & \iid Rel & reations & $=, \ne, \leq, \supseteq, \succsim$ \cr + 4 & \iid Open & opening bracket & $\{, (, [, \langle$ \cr + 5 & \iid Close & closing bracket & $\}, ), ], \rangle$ \cr + 6 & \iid Punct & punctuation & comma \cr + & \iid Inner & left-right & \code{\\left...\\right} outputs, see section~\ref[delims] +} +\bigskip + +There are \ii horizontal/spacing,spacing three space types used +by the algorithm for horizontal spacing in the math formulas. + +\begitems +* \ii thin/space Thin space: \x`\thinmuskip` primitive register, `\,` macro. Used around Op atoms. +* \ii medium/space Medium space: \x`\medmuskip` primitive register, `\>` macro. Used around Bin atoms. +* \ii thick/space Thick space: \x`\thickmusip` primitive register, `\;` macro. Used around Rel atoms. +\enditems + +\puttext 7.8cm -3.7cm {\rotbox{90}{Left atom}} +\puttext 11.5cm -.5cm {Right atom} +\puttext 8.2cm -4.4cm {\typosize[9/11] +\thistable{\def\_enspace{ }}% +\table {l|8c|} { + \omit & Ord & Op & Bin & Rel & Open & Close & Punct & \omit \hfil Inner \crlp{2-9} + Ord & 0 & 1 & 2 & 3 & 0 & 0 & 0 & 1 \cr + Op & 1 & 1 & & 3 & 0 & 0 & 0 & 1 \cr + Bin & 2 & 2 & & & 2 & & & 2 \cr + Rel & 3 & 3 & & 0 & 3 & 0 & 0 & 3 \cr + Open & 0 & 0 & & 0 & 0 & 0 & 0 & 0 \cr + Close & 0 & 1 & 2 & 3 & 0 & 0 & 0 & 1 \cr + Punct & 1 & 1 & & 1 & 1 & 1 & 1 & 1 \cr + Inner & 1 & 1 & 2 & 3 & 1 & 0 & 1 & 1 \crlp{2-9} +}} + +\hangindent=-8.7cm \hangafter=0 +Ord atoms are printed without spaces between them. The spaces are not +cumulated, so the rule about spaces mentioned above is only a rough idea. +The exact rule for horizontal spaces is given for each pairs of atoms +in the table here. The symbol 0 means no space, 1 thin space, 2 medium space, +and 3 means thick space. + +\hangindent=-8.7cm \hangafter-2 +The Bin atom is automatically transformed to the +Ord atom if no atom precedes or if Op, Bin, Rel, Open, or Punct atom +precedes. And it is transformed to the Ord atom if Rel, Close or Punct atom +follows. This corresponds to the empty cells in the table. +Why such behavior? Compare \"\hbox{$0-3$}" and \"$-3$". The Bin atom in +the second case behaves like Ord atom because it is \ii unary/minus {\em unary minus}. +There is no space between the unary minus and the following object. + +All medium spaces and thick spaces and some thin spaces from this table are +omitted if the <math list> is processed in +\ii script/style,scriptscript/style script or scriptscript styles +(smaller size). See section~\ref[styles] about math styles. + +You can overwrite the default class derived from the nucleus of the atom by +\TeX/ primitives \x`\mathord`, \x`\mathop`, \x`\mathbin`, \x`\mathrel`, \x`\mathopen`, +\x`\mathclose`, \x`\mathpunct` and \x`\mathinner`. They can precede a nucleus of +the atom and they set the class of the atom. +For example, `x \mathrel+ y` behaves like `x = y` from a spacing point of view but + +is printed. Another example: `\mathop{\rm lim} z` creates the atom `lim` in +roman font of class Op. So, the thin space is inserted between lim and $z$. + +There are more special kinds of math atoms: fractions, math accents, +radicals. They are constructed in a special way (see next sections) but they behave +like Ord atom in the horizontal spacing algorithm. + +\secc[styles] Math styles + +When a formula (or a sub-formula) is processed by \TeX/ then one from four +\ii math/style,display/style,text/style,script/style,scriptscript/style +styles is active: display style ($D$), text style ($T$), script style ($S$) or +scriptscript style ($SS$). + +\ii T/style,D/style,S/style,SS/style The $T$ style is started in in-line math mode `$...$` and the $D$ +style is started in display math mode `$$...$$`. The first level of exponents or +subscripts is processed in $S$ style and the second and more levels of +exponents or indexes are processed in $SS$ style. +There are special rules for math styles when fractions are constructed, see +section~\ref[frac]. + +The $D$ and $T$ styles use basic \ii font/size font size, $S$ uses smaller font size (typically +70~\%) and $SS$ style uses more smaller font size (typically 50~\%). Next +levels of \"more smaller fonts" are not used due to classical typographic rules. + +The \ii nucleus nucleus of \iid Op atoms (big operators, $\sum$, $\int$, etc.) have typically bigger versions +of the character shape for $D$ style than for $T$ style. +So, there are four sizes for such math +objects: one size for each math style. All other math objects (with non Op +class) are printed only in three sizes: The sizes for $T$ and $D$ styles are equal. + +The \iid Op atom puts its \iid exponent and \iid subscript above and below the nucleus in $D$ +style but right to the nucleus in other styles: +$$ + `\sum``_{i=1}^\infty` \quad \hbox{gives}\quad \sum_{i=1}^\infty \hbox{ in $D$ style and} + \quad \textstyle \sum_{i=1}^\infty \hbox{ in $T$ style}. +$$ +This default behavior of the Op atom +can be modified by placing \x`\limits` or \x`\nolimits` or +\x`\displaylimits` \TeX/ primitive just after its nucleus before the constructors +of exponent and/or index. The `\nolimits` puts exponent and subscript right +to the nucleus (regardless of the current style) and `\limits` puts these +objects above and below the nucleus (regardless of the current style). There +can be more such primitives in a queue (due to a macro expansion, for +instance). Then the last primitive in the queue wins. +If the last primitive is \x`\displaylimits` then +the default behavior is processed regardless there are \x`\limits` or \x`\nolimits` +before it. +$$ + `\sum\nolimits``_{i=1}^\infty` \quad \hbox{gives}\quad \sum\nolimits_{i=1}^\infty + \hbox{ in $D$ style and}\quad \textstyle\sum\nolimits_{i=1}^\infty + \hbox{ in $T$ style}. +$$ +Atoms of all other classes have their exponents and/or subscripts only right +to their nucleus without any exception. + +The primitives \x`\displaystyle`, \x`\textstyle`, \x`\scriptstyle` and +\x`\scriptscriptstyle` set the given style regardless the default rules. For +example, you can create a formula in in-line math mode and in $D$ style by +`$\displaystyle <fomula>$` or a formula in display mode and $T$ style can be printed +by `$$\textstyle <fomrula>$$`. + +If a subformula is placed below something (below a line from root symbol, +below a fraction line), then the processed style $D, T, S$ or $SS$ is +\ii cramped/style {\em cramped}. +The exponents are positioned slightly lower than in +\ii non-cramped/style non-cramped style. The selectors `\displaystyle`\,\dots +`\scriptscriptstyle` mentioned above select non-cramped style. The +non-cramped style is selected when math mode starts too. +\new \OpTeX/ +You can select a cramped style by the macro \x`\cramped` at the start of the +math formula or after the math-style selectors: `\scriptstyle\cramped` for +example. + +Several macros need to know what math style is currently processed (for +example they need to draw something in an appropriate size). But it +not possible simply due to the syntax of fractions (section~\ref[frac]). +This syntax requires to process all math lists in two steps: the first step +expands all macros and creates structured data of processed math list. The +second step reads the output of the first step, switches between math +styles and creates definitive output. So, macros (working in the first step) +cannot know the current math +style because it is set only in the second step. \TeX/ supports the primitive +\x`\matchchioce``{<D>}{<T>}{<S>}{<SS>}` which prepares four math lists in the +first step and only one of these four lists are used in the second step. We +can put different macros into each of the four parameters of `\mathchoice`. +Plain \TeX/ supports the macro \x`\mathpalette` which gives a more comfortable +interface of \x`\mathchoice` to the macro programmer. +The cramped/non-cramped variants of the current style are kept when `\mathchioce` +is used. + +\new \OpTeX/ +We describe another interface for creating macros depending on the current +style. You can use \x`\mathstyles``{<math list>}`. It +behaves like `{<math list>}`, moreover, you can use the following commands inside such +<math list>: +\begitems +* The macro \x`\currstyle`. It expands to + `\displaystyle`, `\textstyle`, + `\scriptstyle` or `\scriptscriptstyle` depending on the current math style + when the `\mathstyles` was opened. +* The \x`\dobystyle``{<D>}{<T>}{<S>}{<SS>}` is expandable macro. It expands its + parameter `<D>`, `<T>`, `<S>` or `<SS>` depending on the current math style + when `\mathstyles` was opened. +* The value of the \x`\stylenum` register is 0, 1, 2 or 3 + depending on the current math style when `\mathstyles` was opened. +\enditems +% +Example of usage of \x`\mathstyles`: +\def\mysymbol{\mathbin\mathstyles + {\kern1pt\vrule height\mysymbolA width\mysymbolA\kern1pt}} +\def\mysymbolA{\dobystyle{5pt}{5pt}{3.5pt}{2.5pt}} +\begtt +\def\mysymbol{\mathbin\mathstyles + {\kern1pt\vrule height\mysymbolA width\mysymbolA\kern1pt}} +\def\mysymbolA{\dobystyle{5pt}{5pt}{3.5pt}{2.5pt}} +Test: $a\mysymbol b_{c \mysymbol d}$ or $a\mysymbol b\over c$. +\endtt +This example gives Test: $a\mysymbol b_{c \mysymbol d}$ or $a\mysymbol b\over c$. + +The \x`\mathstyles` macro mentioned above uses \TeX/ primitive \x`\mathchoice`, so it +creates four math lists and only one is used. It may take more +computer time in special cases. +\new Lua\TeX/ +Lua\TeX/ supports the \x`\mathstyle` primitive +(no \"`s`" at the end of this control sequence) which +expands to values 0 to 7 depending on the current style: +$D, D', T, T', S, S', SS, SS'$ +(where $X'$ means cramped variant of the style). This primitive does +not use `\mathchoice` but it simply ignores the fraction syntax, so +`$a\mysymbol b\over c$` cannot work if `\mysymbol` is defined using the `\mathstyle` +primitive. See section 7.3.1 of Lua\TeX/ documentation for more information. + + +\secc[frac] Fractions + +The \iid fraction can be constructed by `{<numerator>`\x`\over``<denominator>}`. If the +fraction is only a single object in the whole math mode (between dollars), +you need not use the outer braces, so you can write `$1\over2$` to get $1\over2$. + +The \ii numerator,denominator <numerator> and <denominator> are printed in \"smaller" math style than +current math style. More exactly the following schema is used. +$D$: $T\over T$., $T$: $S\over S$, $S$: $SS\over SS$, $SS$: $SS\over SS$. +For example +$$ + `{a+b \over c}` \quad \hbox{is printed as } + {a+b\over c} \hbox{ in $D$ style and as } + \textstyle {a+b\over c} \hbox{ in $T$ style}. +$$ + +The \LaTeX/ macro \x`\frac``{<numerator>}{<denominator>}` is not supported in +Plain \TeX/ nor in \OpTeX/ but you can define such macro if you want. + +The syntax with \x`\over` is more preferred because it is more human-readable +notation. You can write the fraction in the same manner as you can read it. +You can compare: `$1\over2$` (one over two) with `$\frac12$` (frac twelve). + +Besides the `\over` primitive, there are analogical \TeX/ primitives which +create \"generalized" fractions. The result is similar to `{<above>\over <below>}` +but there is something extra: + +\begitems +* `{<above>`\x`\atop``<below>}` does `{<above>\over<below>}` but + without the fractional rule. +* `{<above>`\x`\above``<dimen><below>}` creates fractional rule with <dimen> thickness. +* `{<above>`\x`\overwithdelims``<delim-l><delim-r><below>}` adds the <delim-l> left to + the fraction and the <delim-r> right to the fraction. +* `{<above>`\x`\atopwithdelims``<delim-l><delim-r><below>}` is analogical to + `\overwithdelims` but without fractional rule. +* `{<above>`\x`\abovewithdelims``<delim-l><delim-r><dimen><below>}` behaves as + `\overwithdelims` but the fractional rule has <dimen> thickness. +\enditems +% +The `\...withdelims` variants read <delim-l> and <delim-r>, they must be +declared as {\em math delimiter} in \TeX. They are vertically scalable +math objects, typically brackets. See section~\ref[delims] for more +information about math delimiters. Example: +$$ + `{n \atopwithdelims() k}`\quad \hbox{ creates } + {n \choose k} \hbox{ in $D$ style and } + \textstyle {n \choose k} \hbox{ in $T$ style}. +$$ +The \x`\choose` macro is defined by `\def\choose{\atopwithdelims()}`, so the +user can write `{n\choose k}` in order to get binomial coefficients. + + +\secc[delims] Vertically scalable objects: math delimiters + +The vertically scalable objects are called \ii delimiters {\em delimiters}. For example, +all types of brackets are declared as delimiters. +This means that you can use a bracket in arbitrary +vertical size.\fnote{ +This is not exactly true, because traditional typography says that they +cannot be scaled continuously but by visible steps. This means that there is +a sequence of increasing brackets in the font, the reader must see a difference +between every two sizes of brackets.} + +The following objects are declared as delimiters (i.e.\ vertically scalable): + +\bigskip +{\tt \adef!{\bslash} +\table{l 14c}{ + \rm source: & ( & ) & [ & ] & \code{\\\{} & \code{\\\}} & / + & !backslash & !langle & !rangle + & | & \code{\\|} & \cr + \rm output: &$($&$)$&$[$&$]$& $\{$ & $\}$ & $/$ + & $\backslash$ & $\langle$ & $\rangle$ + & $|$ & $\|$ +} +\medskip +\table{l 14c}{ + \rm source: & !lfloor & !rfloor & !lceil & !rceil \cr + \rm output: & $\lfloor$ & $\rfloor$ & $\lceil$ & $\rceil$ +} +\medskip +\table{l 14c}{ + \rm source: & !uparrow & !Uparrow & !dowarrow & !Downarrow + & !updownarrow & !Updownarrow \cr + \rm output: & $\uparrow$ & $\Uparrow$ & $\downarrow$ & $\Downarrow$ + & $\updownarrow$ & $\Updownarrow$ +}} +\bigskip +\noindent \new Unicode +If you can produce the characters $\langle$, $\rangle$,\fnote + {Do not confuse $\string<, >$ and $\langle, \rangle$. The first pair are Rel atoms + with meaning \"less than" or \"greater than", but the second pair are special + types of brackets. They are not directly available at computer keyboards without + using a keyboard macro.} +$\lfloor$, $\rfloor$, ... $\updownarrow$, $\Updownarrow$ +directly in your text editor then you can use these Unicode characters in your source instead of control +sequences `\langle`, `\rangle`, `\lfloor`, `\rfloor` ... `\updownarrow`, `\Updownarrow`. +For many users (including me), there is more simple to type `\lfloor` than to find +how to create the $\lfloor$ character in my text editor. Note that there exist +text editors (Emacs, for example) +enabling you to type `\lfloor` and this control sequence is immediately +converted to the $\lfloor$ Unicode character. +Your source text looks pretty and you can use classical \TeX/ sequences. + +\new Unicode +There are more \ii delimiters delimiters, but it heavily depends on loaded Unicode Math +font. For example, this document is printed in `latinmodern-math` font and +there are six more delimiters `\lBrack`~$\lBrack$, `\rBrack`~$\rBrack$, +`\lAngle` $\lAngle$, `\rAngle` $\rAngle$, `\lgroup` $\lgroup$, `\rgroup` $\rgroup$. +See section~\ref[objects] for table of all Unicode symbols for math typesetting. + +Arbitrary tall formula can be surrounded by a pair of delimiters using +\x`\left` and \x`\right` \TeX/ primitives: `\left<delim> <formula> \right<delim>`. +The delimiters are scaled to the height and depth of the <formula> +and vertically centered to the {\em math axis}.\fnote +{Math axis is a horizontal line passing through the center of symbols $+$ + and $-$. All vertically scalable objects are vertically centered with + respect to this axis.} +Example: +$$ + `+ \left\{ \sum_{i=1}^\infty x_i \right)` \quad \hbox{ gives } + + \left\{ \sum_{i=1}^\infty x_i \right). +$$ +The pair `\left<delim> <formula> \right<delim>` creates the formula in a +\TeX/ group. Such group can be nested with another groups. +Each `\left` must have its `\right` counterpart at the same group level. +If you don't want to create visible delimiter, use dot instead <delim>. +Example: +$$ + `\left. \int``_0^t e^{x^2}\,dx\, \right|_{t=42}` \quad \hbox{ gives } + \left. \int_0^t e^{x^2} \,dx\, \right|_{t=42} +$$ + +\new e\TeX/ +You can use \x`\middle``<delim>` inside the <formula> which is surrounded by +`\left...\right`. Then the given <delim> is scaled to the same size like +their `\left` and `\right` counterparts. + +When a delimiter is used without `\left` nor `\right` prefix, then it is the +Open, Close, Ord or Bin atom by its natural meaning: +$(, [, \{, \ldots, \lfloor, \lceil$ are Open atoms, +$], ], \}, \ldots, \rfloor, \rceil$ are Close atoms, +$/, \backslash, |, \|$ are Ord atoms and +$\uparrow, \Uparrow, \ldots, \Updownarrow$ are Bin atoms. You can overwrite +this default setting, for example `\mathclose(`. If delimiters are used with +`\left` and `\right` prefixes then `\left<delim>` behaves like Open atom, +`\right<delim>` behaves like Close atom and the math list +`\left<delim><formula>\right<delim>` is encapsulated as a single Inner atom. +The `\middle<delim>` behaves like Open atom at its left side and like Close +atom at its right side. + +The sequence of increasing delimiters can be printed by the following +macros: +$$ + `(` \to (,\quad \x`\big``(` \to \big(,\quad \x`\Big``(` \to \Big(,\quad + \x`\bigg``(` \to \bigg(, \quad \x`\Bigg``(` \to \Bigg(. +$$ +The `\Bigg<delim>` is not the maximal size of the bracket. Try +`\left(\vbox to5cm{}\right.`, for example. You can see that the font +\"cheats" from certain sizes, because there are not all infinity number of +sizes of brackets drawn in the font, of course. + +The `\big<delim>` creates Ord atom. We need to create Open atom +for opening bracket and Close atom for closing bracket more often. +Then we can use macros +\x`\bigl``<delim>`, +\x`\Bigl``<delim>`, +\x`\biggl``<delim>`, +\x`\Biggl``<delim>` for creating Open atoms and +\x`\bigr``<delim>`, +\x`\Bigr``<delim>`, +\x`\biggr``<delim>`, +\x`\Biggr``<delim>` for creating Close atoms. Unfortunately, the source is not +too attractive when more sizes of brackets are used, but typographic +traditions say that we have to distinguish brackets by the size in math +mode if they are in equal types: +$$ + `\Bigl( f\bigl( 2(x+y) + z\bigr) \Bigr)'` \quad \hbox{gives } + \Bigl(f\bigl(2(x+y)+z\bigr)\Bigr)'. +$$ + +\secc Horizontally scalable objects: math accents + +Arbitrary wide formula can be covered by \ii math/accent,accent {\em scalable math accent}. +Example: +$$ + \x`\overrightarrow`` {a+b+c+d+e+f}` \quad \hbox{gives } \overrightarrow {a+b+c+d+e+f}. +$$ +The usage is: control sequence of selected math accent followed by `{<math list>}`. + +Standard scalable math accents are: +\x`\overline` $\overline{abc}$, +\x`\overbrace` $\overbrace{abc}$, +\x`\overrightarrow` $\overrightarrow{abc}$, +\x`\overleftarrow`~$\overleftarrow{abc}$, +\x`\underline` $\underline{abc}$, +\x`\underbrace` $\underbrace{abc}$. + +An Op atom is created. The exponents and subscripts are centered above +and below the nucleus of this atom (regardless of the current style). Example: +$$ + `\overbrace {b\cdot b\cdot b \cdots b}^{k\times}` \quad \hbox{gives } + \overbrace {b\cdot b\cdot b \cdots b}^{k\times} +$$ +There are scalable accents with a limited maximum width: +\x`\widehat` $\widehat{abc}$ and \x`\widetilde` $\widetilde{abc}$. If the +formula is wider than the font can cover then the widest variant from the +font is used and it is horizontally centered. + +\new Unicode +There are more scalable accents in Unicode math fonts: +\x`\overparen` $\overparen{abc}$, \x`\underparen` $\underparen{abc}$, +\x`\overbracket` $\overbracket{abc}$, \x`\underbracket` $\underbracket{abc}$, +\x`\overleftrightarrow` $\overleftrightarrow{abc}$, +\x`\overleftharpoon` $\overleftharpoon{abc}$, +\x`\overrightharpoon` $\overrightharpoon{abc}$, + + +\secc Fixed math accents + +Fixed \ii math/accent,accent math accents can be applied to single math object or to the `{<math list>}`. +The accent is centered (with respect of slanting axis) and the result is a +nucleus of Ord +atom. For example `\dot x` gives $\dot x$. The list of fixed math accents +follows: \x`\acute`` x` $\acute x$, \x`\bar`` x` $\bar x$, +\x`\breve`` x` $\breve x$, \x`\check`` x` $\check x$, +\x`\dot`` x` $\dot x$, \x`\ddot`` x` $\ddot x$, +\x`\grave`` x` $\grave x$, \x`\hat`` x` $\hat x$, +\x`\vec`` x` $\vec x$, \x`\tilde`` x` $\tilde x$. + +\new Unicode +The additional fixed accents depends on used Unicode math font. The +`latinmodern-math` supports: +\x`\ovhook`` x` $\ovhook x$, \x`\ocirc`` x` $\ocirc x$, +\x`\leftharpoonaccent`` x` $\leftharpoonaccent x$, \x`\rightharpoonaccent`` x` $\rightharpoonaccent x$, +\x`\dddot`` x` $\dddot x$, \x`\ddddot`` x` $\ddddot x$, +\x`\widebridgeabove`` x` $\widebridgeabove x$, \x`\asteraccent`` x` $\asteraccent x$. + +There exist one special math accent `'` (single quote, ASCII 39) +which can be appended after a symbol like this: `f'` +and it creates $f'$ (typical meaning is the +derivation of the given function). You can put more such accents, for +example `g'''` gives $g'''$. + +\secc Roots + +There is a macro \x`\sqrt``{<math list>}` to create \ii square/root square root. For example: +$$ + `\sqrt{\sqrt{\sqrt{x+1}+1}+1}` \quad \hbox{gives } + \sqrt{\sqrt{\sqrt{x+1}+1}+1} +$$ +The \ii root $n$-th root is created by the macro \x`\root`` <n>\of{<math list>}`. For +example `\root k+1\of x` gives $\root k+1\of x$. + +\secc Math alphabets + +Letters \ii math/alphabet $a\dots z$, $A\dots Z$ and $\alpha$\dots$\omega$ are printed in italic +in math mode. This follows the traditional typographic rule. +All other math symbols, digits, and uppercase Greek letters must be +upright.\fnote +{French typographic convention says that uppercase Greek letters have to be + in italic too. Use `\_itGreek` declaration in this case.} +These rules are independent of the current variant of surrounding text font. + +If we want to use the letters or digits +in another than this default shape, then we can use +\ii math/alphabet/selector {\em math alphabet selectors}: +\x`\mit`, \x`\rm`, \x`\it`, \x`\bf`, \x`\cal`. +\new \OpTeX/ +\OpTeX/ supports more such selectors \x`\script`, \x`\frak`, \x`\bbchar`, \x`\bi`, see +section 1.3.3 in the \OpTeX/ documentation. The math selectors have local +validity in the group. + +The control sequences \x`\rm`, \x`\it`, \x`\bf`, and \x`\bi` act as variant selectors +of fonts in non-math mode (text mode) and they act +as math alphabet selectors in math mode. This \"overlaying" concept +is given by Plain \TeX/. Example: math operators lim, sin, cos, +log, etc.\ must be printed unslanted. We are using `\lim`, `\sin`, `\cos`, +`\log` etc.\ in math mode in order to comply with this typographic convention. For +example `\sin` is defined as: +\begtt +\def\sin {\mathop{\rm sin}\nolimits} +\endtt +The `\rm` is used here as math alphabet selector, no variant selector of +text fonts. + +The list of all predefined `\rm`-like math operators follows: \x`\arccos`, +\x`\arcsin`, \x`\arctan`, \x`\arg`, \x`\cos`, \x`\cosh`, \x`\cot`, \x`\coth`, \x`\deg`. +\x`\det`, \x`\dim`, \x`\exp`, \x`\gcd`, \x`\hom`, \x`\inf`, \x`\ker`, \x`\lg`, \x`\lim`, +\x`\liminf`, \x`\limsup`, \x`\ln`, \x`\log`, \x`\max`, \x`\min`, \x`\Pr`, \x`\scs`, \x`\sin`, +\x`\sinh`, \x`\sup`, \x`\tan`, \x`\tanh`, You can define another such operator +analogically. + +\new Unicode +Unicode font can include the following math alphabets: +\begtt \typosize[9/11] +\_rmvariables % upright letters A-Z, a-z +\_bfvariables % bold letters A-Z, a-z +\_itvariables % italic letters A-Z, a-z +\_bivariables % bold italic letters A-Z, a-z +\_calvariables % calligraphic letters A-Z, a-z +\_bcalvariables % calligraphic letters A-Z, a-z +\_frakvariables % fraktur A-Z, a-z +\_bfrakvariables % bold fraktur A-Z, a-z +\_sansvaraibales % sans serif letters A-Z, a-z +\_bsansvaraibales % bold sans serif letters A-Z, a-z +\_isansvaraibales % slanted sans serif letters A-Z, a-z +\_bisansvaraibales % bold slanted sans serif letters A-Z, a-z +\_ttvariables % monospace, typewriter letters A-Z, a-z +\_bbvariables % double struck A-Z, a-z +\_rmdigits % upright digits 0..9 +\_bfdigits % bold digits 0..9 +\_sansdigits % sans serif digits 0..9 +\_bsansdigits % bold sans serif digits 0..9 +\_ttdigits % monospace typewriter digits 0..9 +\_bbdigits % double-struck digits 0..9 +\_rmgreek % upright Greek letters \alpha-\omega +\_itgreek % slanted Greek letters \alpha-\omega +\_bfgreek % bold Greek letters \alpha-\omega +\_bigreek % bold italic Greek letters \alpha-\omega +\_bsansgreek % bold sans serif Greek letters \alpha-\omega +\_bisansgreek % bold slanted snas serif Greek letters \alpha-\omega +\_itGreek % slanted Greek letters \Alpha-\Omega +\_bfGreek % bold Greek letters \Alpha-\Omega +\_biGreek % bold italic Greek letters \Alpha-\Omega +\_bsansGreek % bold sans serif Greek letters \Alpha-\Omega +\_bisansGreek % bold slanted snas serif Greek letters \Alpha-\Omega +\endtt +% +Not all Unicode math fonts include all math alphabets listed here. Typically, +the lowercase letters of calligraphic shape and all letters of +bold calligraphic shape are missing. + +\new \OpTeX/ +\OpTeX/ defines internal math alphabet selectors as mentioned in the +previous listing of math alphabets and sets as default: +\begtt \typosize[10/12] +\_itvariables \_rmdigits \_itgreek \_rmGreek +\endtt +% +Moreover, it defines the alphabet selectors at user level (see section 1.3.3 +of the \OpTeX/ manual). For example +\begtt \typosize[10/12] +\def\rm {\_tryload\_tenrm \_inmath{\_rmavariables \_rmdigits}} +\endtt +% +The first part +\new \OpTeX/ +`\_tryload\_tenrm` is applicable for text fonts and the +`\_inmath` part is processed only in math mode and sets the math alphabets. +You can see the file `unimath-codes.opm` where all user-level selectors are +defined. You can redefine them. For example, \OpTeX/ defines `\bf` as a math +alphabet selector that selects sans serif bold in math. This is the common +notation for vectors, tensors, and matrices. If you dislike this, then you can define: +\begtt \typosize[10/12] +\def\bf {\_tryloadbf\_tenbf \_inmath{\_bfvariables\_bfdigits\_bfgreek\_bfGreek}} +\endtt + + +\secc[objects] List of single math objects + +\new Unicode +All \ii single/math/object single math objects are listed in the `unimath-table.opm` or +`unicode-math-table.tex` file. You can +look into this file. The codes, \TeX/ sequences, classes, and comments +for all possible math codes are here. Maybe, your Unicode math font which is loaded +does not support all these codes. +\new \OpTeX/ +You can try all codes of the currently loaded font by +\begtt +\input print-unimath.opm +\endtt +The `unimath-table` is printed with characters available in the loaded font. +\new \OpTeX/ +If the character is unsupported by the font then the slot is empty and only +\TeX/ sequence and the class of the code is printed in the table. +For example, this document loads `latimodern-math.otf` font. +And the result from `\input print-unimath.opm` looks like the following ten +pages. + +Unsupported characters can be replaced by characters from other Unicode math +font, see +\ulink[http://petr.olsak.net/optex/optex-tricks.html\#addumathfont]{OpTeX trick 0030} +or section~\ref[newfam]. + + +\label[listA]\wlabel{} + +\bigskip +\input print-unimath.opm +\bigskip + +\label[listB]\wlabel{} + +It isn't very comfortable to find something in the previous table +if you know the shape. You can try the online web tool \ii Detexify +\ulink[https://detexify.kirelabs.org/classify.html]{Detexify}. +You can draw the symbol here and the suggestion of \TeX/ sequence is +printed. + +\def\g#1{{\tt\string#1}~$#1$} + +The generic \TeX/ sequences for the Greek letters \ii Greek/letters can be used: +\g\alpha, \g\beta, \g\gamma, \g\delta, \g\varepsilon, \g\zeta, \g\eta, +\g\theta, \g\iota, \g\kappa, \g\lambda, \g\mu, \g\nu, \g\xi, +\g\omicron, \g\pi, \g\rho, \g\varsigma, \g\sigma, \g\tau, \g\upsilon, +\g\varphi, \g\chi, \g\psi, \g\omega, \g\vardelta, \g\epsilon, \g\vartheta, +\g\varkappa, \g\phi, \g\varrho, \g\varpi\ +and +\g\Alpha, \g\Beta, \g\Gamma, \g\Delta, \g\Epsilon, \g\Zeta, \g\Eta, \g\Theta, +\g\Iota, \g\Kappa, \g\Lambda, \g\Mu, \g\Nu, \g\Xi, \g\Omicron, \g\Pi, \g\Rho, +\g\Sigma, \g\Tau, \g\Upsilon, \g\Phi, \g\Chi, \g\Psi, \g\Omega. + +\new \OpTeX/ +The variant of Greek letters in the output +(upright, italic, bold, bold sans serif, etc.) +written by the sequences `\alpha`, `\beta` etc. depends on the math alphabet +selected by `\_itgreek`, `\_rmgreek`, etc. selectors. The user-level +selectors `\bf` and `\bi` set `\_bsansgreek` and `\_bisansgreek`, so +`{\bi\delta}` produces $\bi\delta$. + +\new Unicode +All characters available in the math font can be accessed by \TeX/ control +sequence or by directly using the Unicode character in the document source. +Example: +\begtt \adef/{} +$$ + \sum/_{k=0}^\infty e^{(\alpha+i\beta/_k)} = + e^\alpha \sum/_{k=0}^\infty e^{i\beta/_k} = + e^\alpha \sum/_{k=0}^\infty (\cos\beta/_k + i\sin\beta/_k). +$$ +\endtt +or +\begtt \ttspec +$$ + ∑_{k=0}^∞ e^{(α + iβ_k)} = e^α ∑_{k=0}^∞ e^{iβ_k} + = e^α ∑_{k=0}^∞ (\cos β_k + i\sin β_k). +$$ +\endtt +both gives the same result: +$$ + ∑_{k=0}^∞ e^{(α + iβ_k)} = e^α ∑_{k=0}^∞ e^{iβ_k} + = e^α ∑_{k=0}^∞ (\cos β_k + i\sin β_k). +$$ +\medskip + + +\sec Other specialities + +\secc The `\not` prefix + +You can apply \x`\not` before a following math object. +The slash $/$ is overprinted such math object, for example +`$a \not= b$` gives $a \not= b$. + +\new \OpTeX/ +If there exists a direct Unicode character for the negation of a relation symbol +(for example `\ne` creates $\ne$ directly as a character U+2260) +then `\not<char>` expands to appropriate Unicode character. +For example `\not=` expands to `\ne` or `\not\in` expands to `\notin`. +If such character does not exist then +the centered $/$ is overprinted over the next character. + + +\secc The `\buildrel` macro: text over the relation + +The macro \x`\buildrel`` <text>\over <relation>` creates a new atom Rel with the +<relation> and with the smaller <text> above this <relation>. Example: +`$M \buildrel\rm def\over= X\cup Y$` gives $M\buildrel\rm def\over= X\cup Y$. + + +\secc Spaces + +Spaces between atoms are created automatically as were mentioned in +section~\ref[class]. But sometimes you have to help \TeX/ to create +appropriate space. You can use following macros: + +\begitems +* `\,` is \ii thin/space {\em thin space} used around Op atoms, after comma, etc.: \ss\,, +* `\!` is \ii negative/thin/space negative thin space, +* `\>` is \ii medium/space {\em medium space} used around Bin atoms: \ss\>, +* `\;` is \ii thick/space {\em thick space} used around Rel atoms: \ss\;, +* \x`\quad` is \ii em/space {\em em space}: \ss\quad, +* \x`\qquad` is \ii double/em/space {\em double em space}: \ss\qquad. +\enditems +% +Of course, you can use \ii direct/space {\em direct space} {\visiblesp`\ `} which is \TeX/ primitive +and gives interword space: \ss\ \ +or you can use \x`\hskip`` <value>` to put arbitrary space. + +The space size of `\,`, `\!` resp. `\>`, resp. `\;` is given by +`\thinmuskip`, resp. `\medmuskip`, resp. `\thickmuskip` values. You can see +in the `plain.tex` file that these default values differ very little in their basic +size but there is no stretchability/shrinkability in the `\,` space, there is small +stretchability in the `\>` space, and more stretchability in the `\;` space. + +The registers \x`\thinmuskip`, \x`\medmuskip`, and \x`\thickmuskip` store so-called +\ii mu/values {\em mu values} given by math unit `mu`. It is 1/18 em and this unit depends +on the current font size used in the math formula ($S$ or $SS$ styles use +smaller font size, the `mu` unit is smaller here). You can use \x`\muskip` +instead `\hskip` or \x`\mukern` instead `\kern` if you want to use this +special mu unit. It is allowed only in math mode. + +The \x`\quad` and \x`\qquad` spaces have fixed width and they can be used in text +mode too. (\OpTeX/ allows to use `\,` in text mode too). +Use `\quad` or `\qquad` if you want to separate more formulas created in +single math mode. Examples of typical usage of spaces: + +\begtt \adef/{} \typosize[10/12] +$$ \alpha\,(x+y), \qquad \int/_a^b \!\! f(x)\,{\rm d}x, \qquad \Gamma/_{\!i}. $$ +\endtt +$$ \alpha\,(x+y), \qquad \int_a^b \!\! f(x)\,{\rm d}x, \qquad \Gamma_{\!i}. $$ + + +\secc Texts in math mode + +If you write `$Hello world!$` (i.e.\ Hello world in math mode), then you get +$Hello world!$. It is interpreted as the product of variables $H$, and $e$, and +$l^2$, and $o$, etc., followed by the symbol ! used for factorial. +The non-ASCII letters (with accents) don't work at all because they are +never used as symbols for variables. Spaces are ignored. + +If you want to write a short text in the math mode, then you can use +`\hbox{<text>}`. The \x`\hbox` primitive initializes text mode regardless of +the \"outer mode". Example: + +\begtt \adef/{} \typosize[10/12] +$$ \sum/_{n=0}^\infty (-1)^n a_n \hbox{ converges, if $a_n\searrow 0$.} $$ +\endtt +$$ \sum_{n=0}^\infty (-1)^n a_n \hbox{ converges, if $a_n\searrow 0$.} $$ +% +Note the space before the word \"converges". The space before `\hbox` is +irrelevant. Second notice: the example shows the text mode inside math mode +and the in-line math mode inside this text mode. The same result can be +produced by: + +\begtt \adef/{} \typosize[10/12] +$$ \sum/_{n=0}^\infty (-1)^n a_n \hbox{ converges, if } a_n\searrow 0. $$ +\endtt +% +The difference can be visible if the formula $a_n\searrow 0$ includes a +fraction, for example ${1\over2}a_n\searrow 0$. The first example prints the +fraction in the text style and the second example prints it in the display style. + +The disadvantage of `\hbox` is that it starts in the text mode independently +of the current style, but we want to use smaller font in $S$ or $SS$ styles. +\new \OpTeX/ +You can use \x`\mathbox``{<text>}` in such situations. This macro behaves like +`\hbox` but the text is appropriately smaller in $S$ and $SS$ styles. +Example: +$$ + `{\mathbox{cena}\over\mathbox{výkon}}` \quad \hbox{gives } + {\mathbox{cena}\over\mathbox{výkon}} \hbox{ in $D$ style and } + \textstyle {\mathbox{cena}\over\mathbox{výkon}} \hbox{ in $T$ style.} +$$ +Note that $\mathbox{cena}\over\mathbox{výkon}$ means $\rm price\over performance$ +and you can write `$\rm price\over performance$` when you are using only +words without spaces and accented letters. But phrases with spaces or accented letters +should be printed in text mode using `\hbox` or `\mathbox`. + +\secc `\vcenter` + +The \x`\vcenter` primitive behaves like `\vbox`, but it can be used only in +math mode and its result is vertically centered to the math axis. +For example, matrices, are created by tables in `\vcenter`. + +All big objects in math formula are centered on the math axis and the baseline is +ignored. In the following example, we create a new big math operator by +`\vcenter`: +\begtt +$$ + \def\myop#1{\mathop{\vcenter{\frame{\vbox to2em{\vss\hbox{ $#1$ }\vss}}}}} + F(x) = \myop{x(i)}_{i=1}^\infty +$$ +\endtt +\vskip-2em +$$ + \def\myop#1{\mathop{\vcenter{\frame{\vbox to2em{\vss\hbox{ $#1$ }\vss}}}}} + F(x) = \myop{x(i)}_{i=1}^\infty +$$ + + +\secc Three dots + +You can write `$1,2,\dots,n$` to get $1,2,\dots,n$. The \x`\dots` macro puts +thin space between dots and after the last dot, so the five object: comma, +dots, comma are exactly equidistant. + +Typographic conventions say that you have to use the repeating symbol +before and after three dots (comma in the previous example) and the three dots +should be at baseline if the repeating symbol is at baseline. Or they should be +at the math axis if the repeating symbol is at the math axis. We have to use \x`\cdots` instead +`\dots` in the second case. Example: +$$ + `a_1, a_2, \dots, a_n, \quad a_1 + a_2 + \cdots + a_n` \qquad + a_1, a_2, \dots, a_n, \quad a_1 + a_2 + \cdots + a_n +$$ +\vskip-.7em +There are \x`\vdots` $\vdots$, \x`\ddots` $\ddots$ and \x`\adots` $\adots$ which +can be used in matrices. + +\new Unicode +Three dots like the output of the `\dots` macro are present as a single +character in fonts too. This character is called ellipsis. Font designers +typically suggest this character with smaller spaces between dots than we +need in math mode. So the rule about equidistant \"comma, three dots, comma" +is not met when this character is used. You can try `$1,2,\unicodeellipsis, n$` +and `$1+2+\unicodecdots + n$`. You get $1,2,\unicodeellipsis, n$ and +$1+2+\unicodecdots + n$. If you feel that this is better, then you can set: +`\let\dots=\unicodeellipsis \let\cdots=\unicodecdots`. + +The Unicode fonts includes compact variants `\unicodevdots` $\unicodevdots$, +`\unicodeddots` $\unicodeddots$ and `\unicodeadots` $\unicodeadots$ too. + + +\secc Phantoms and `\smash` + +The \x`\phantom``{<math list>}` macro creates an invisible subformula equal to +the formula generated by <math list>. It has its size, so it can +interfere with surrounding visible subformulas. This macro is very useful for +aligning with special requirements. Examples are shown in +sections~\ref[matrix] and~\ref[elines]. + +The \x`\vphantom``{<math list>}` has only its vertical size (i.e.\ its height +and depth), the width is zero. The \x`\hphantom``{<math list>}` has only its +width. + +The \x`\smash``{<math list>}` is the opposite of `\vphantom`. It creates visible +subformula but it has only its width. Its height and depth are zero. + +The result of these macros is the nucleus of an Ord atom. You can use `\mathop`, +`\mathbin`, etc. primitives to change this class. For example +`$a\mathrel{\phantom{=}}b$` creates the same formula as $a=b$ with the same +distance from $a$ to $b$ but without the equal sign: +$a\mathrel{\phantom{=}}b$. + +These macros work in the text mode too. Then their argument is +the <horizontal list>. + + +\sec Structured objects + +\secc[matrix] Matrices + +The macro \x`\matrix``{<data>}` creates a vertically centered table of items. +The <data> includes <items> separated by `&` and rows are separated by +`\cr`. The number of columns and rows are unlimited. Columns are printed centered +and separated by the `\quad` space. The vertically scalable +brackets around the table are not printed. You can use \x`\pmatrix``{<data>}` +instead `\matrix{<data>}`: the vertically scalable parentheses () are inserted +around the table. Examples: + +\begtt +$$ + {\bf A} = \pmatrix{a_{1,1} & a_{1,2} & \cdots & a_{1,n} \cr + a_{2,1} & a_{2,2} & \cdots & a_{2,n} \cr + \vdots & \vdots & \ddots & \vdots \cr + a_{m,1} & a_{m,2} & \cdots & a_{m,n} }, +$$ +\endtt +$$ + {\bf A} = \pmatrix{a_{1,1} & a_{1,2} & \cdots & a_{1,n} \cr + a_{2,1} & a_{2,2} & \cdots & a_{2,n} \cr + \vdots & \vdots & \ddots & \vdots \cr + a_{m,1} & a_{m,2} & \cdots & a_{m,n} }, +$$ +or: + +\begtt +\def\qmatrix[#1]{\left[\matrix{#1}\right]} +$$ + \qmatrix[a&b&c\cr d&e&f\cr g&h&i] \cdot \qmatrix[x_1\cr x_2\cr x_3] + = \qmatrix[b_1\cr b_2\cr b_3]. +$$ +\endtt +$$ + \def\qmatrix[#1]{\left[\matrix{#1}\right]} + \qmatrix[a&b&c\cr d&e&f\cr g&h&i] \cdot \qmatrix[x_1\cr x_2\cr x_3] + = \qmatrix[b_1\cr b_2\cr b_3]. +$$ + +If you need to align the columns by another way than to center, then you can +use the phantom. Compare: + +\begtt +$$ + \pmatrix{ 1 & -1 & 0 \cr + 0 & 2 & 13 \cr + -3 & 0 & 5 } \quad \hbox{or} \quad + \def\0{\phantom0} \def\+{\phantom+} + \pmatrix { \+1 & -1 & \00 \cr + \+0 & \+2 & 13 \cr + -3 & \+0 & \05 } +$$ +\endtt +$$ + \pmatrix{ 1 & -1 & 0 \cr + 0 & 2 & 13 \cr + -3 & 0 & 5 } \quad \hbox{or} \quad + \def\0{\phantom0} \def\+{\phantom+} + \pmatrix { \+1 & -1 & \00 \cr + \+0 & \+2 & 13 \cr + -3 & \+0 & \05 } +$$ + +\new\OpTeX/ +Another option to set the right aligned matrix is setting the \x`\lmfil`: +Its value is used on the left side in each `\matrix` item. The right side is +set directly to `\hfil`. +\begtt +$$ + \lmfil={\hfill} % left matrix filler = \hfill + \pmatrix{ 1 & -1 & 0 \cr 0 & 2 & 13 \cr -3 & 0 & 5 } +$$ +\endtt + +\new \OpTeX/ +If you want to draw a vertical line inside the matrix, you can use `\adef|` +as in the following example: +\begtt +$$ + \adef|{\kern-.2em&\strut\vrule&\kern-.2em} + \def\+{\phantom+} + \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \sim + \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} \sim + \pmatrix{1 & 2 & 3 | 0 \cr 0 & 1 & 2 | -1/3 \cr 0 & 0 & 0 | 1 } +$$ +\endtt +$$ + \adef|{\kern-.2em&\strut\vrule&\kern-.2em} + \def\+{\phantom+} + \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \sim + \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} \sim + \pmatrix{1 & 2 & 3 | 0 \cr 0 & 1 & 2 | -1/3 \cr 0 & 0 & 0 | 1 } +$$ + +If you want to put something before the opening bracket in the matrix, you can +use another `\matrix`. Example: + +\begtt +$$ + \adef|{\kern-.2em&\strut\vrule&\kern-.2em} + \def\+{\phantom+} + \def\r{{\bf r}} + \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \ \sim \ + \matrix{\cr 2.\r - 4\cdot 1.\r: \cr 3.\r -7\cdot 1.\r: } + \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} +$$ +\endtt +$$ + \adef|{\kern-.2em&\strut\vrule&\kern-.2em} + \def\+{\phantom+} + \def\r{{\bf r}} + \pmatrix{1 & 2 & 3 | 0 \cr 4 & 5 & 6 | 1 \cr 7 & 8 & 9 | 2 } \ \sim \ + \matrix{\cr 2.\r - 4\cdot 1.\r: \cr 3.\r -7\cdot 1.\r: } + \pmatrix{1 & \+2 & \+3 | 0 \cr 0 & -3 & -6 | 1 \cr 0 & -6 & -12 | 2} +$$ + +Plain \TeX/ defines the \x`\bordermatrix` macro which allows you to create a +top row above the brackets and left column before the opening bracket. +\TeX/book shows the following example: + +\begtt +$$ + M = \bordermatrix{ &C&I&C'\cr + C&1&0&0 \cr I&1-b&0 \cr C'&0&a&1-a } +$$ +\endtt +$$ + M = \bordermatrix{ &C&I&C'\cr + C&1&0&0 \cr I&1-b&0 \cr C'&0&a&1-a } +$$ + +The `\matrix` macro used in $D$ style creates all its items in $T$ style. +\new \OpTeX/ +If you are using the `\matrix` macro in $T$ style or $S$ style (but not in +fractions nor another matrices) then the resulting table is appropriately +smaller and all its items are processed in $S$ style. +If you are using `\matrix` in $SS$ style then the items are in $SS$ style too. +The following example shows one-column matrix in script style: +$$ + `\sum``_{\matrix{i\in M\cr j\in N\cr k\in P}} x_{i,j,k}` \ \hbox{ creates: } + \sum_{\matrix{i\in M\cr j\in N\cr k\in P}} x_{i,j,k} +$$ + + +\secc Cases + +The \x`\cases` macro can be used as in the following example: + +\begtt +$$ + f(x) = \cases{ 1 & for $x\le 0$, \cr + 100-x\over 100 & when $0 < x \le 100$, \cr + 0 & in other cases. } +$$ +\endtt +$$ + f(x) = \cases{ 1 & for $x\le 0$, \cr + 100-x\over 100 & when $0\string< x\le 100$, \cr + 0 & in other cases. } +$$ + +The `\cases` macro behaves like a special `\matrix` with two left-aligned +columns and with left vertically scaled brace $\{$. +The first column is processed in math mode and $T$ style, the second column +is processed in text mode. We have to use `$...$` in the second column if +there is math material. + + +\sec Lines in display mode + +\secc General principles + +The \ii display/math,display/math/mode +`$$<formula>$$` finalizes previous paragraph, prints centered <formula> on +single line with a vertical space above and below and opens next paragraph +with no indentation. + +From \TeX/'s point of view, the text above `$$<formula>$$` plus text +below is a single paragraph interrupted by display <formula>. If there is no +text above (i.e. the opening `$$` are in vertical mode), then the internal +`\noindent` is processed first and the empty line above <formula> is created. +Thus, it is definitely a bad idea to open display mode in vertical mode: never +put an empty line before `$$<formula>$$`. On the other hand, the empty line +just after `$$<formula>$$` says that the paragraph is finalized by the +<formula> and the next text (after the empty line) opens the next paragraph with +indentation. Summary: + +\begitems +* \"Text above `$$<formula>$$` text below": the <formula> interrupts the + paragraph with \"Text above" and \"text below". The \"text below" is + without indentation. +* \"Text above `$$<formula>$$` empty line Text below": the \"Text below" + opens new paragraph with indentation. +* \"Empty line `$$<formula>$$`" is bad practice. +\enditems + +In contrast with the paragraph breaking, there is no built-in algorithm for +breaking display <formula> to more lines. If the <formula> is too wide then +overfull `\hbox` occurs and human must decide about splitting the <formula> +to more lines. The macros `\displaylines` and `\eqalign` are intended to +such task, see sections~\ref[dlines] and~\ref[elines]. + +On the other hand, the in-line math <formula>, i.e.\ the `$<formula>$` in a +paragraph, can be broken after a Bin atom (with penalty `\binoppenalty`) or +after a Rel atom (with penalty `\relpenalty`). If you don't want to break +such a formula at a specific place then use `\nobreak`, for example +`$a+\nobreak b$`. If you want never to break such formulas then you can set +`\binoppenalty=10000`, `\relpenalty=10000`. (Default values are 700 and 500.) + + +\secc References to display lines + +The `$$<formula>`\x`\eqno``<mark>$$` \ii mark prints centered <formula> and the <mark> at +right margin. The `$$<formula>`\x`\leqno``<mark>$$` prints centered <formula> and +the <mark> at left margin. Examples: + +\begtt +$$ a^2 + b^2 = c^2 \eqno (1) $$ +\endtt +$$ + a^2 + b^2 = c^2 \eqno (1) +$$ +\begtt \aftergroup\nobreak +$$ a^2 + b^2 = c^2 \leqno \rm Py $$ +\endtt +$$\predisplaypenalty=10000 + a^2 + b^2 = c^2 \leqno \rm Py +$$ +The <mark> \ii mark is processed in math mode and $T$ style. If you want to put a +text here then you have to use `\rm <text>` or `\hbox{<text>}`. + +\new \OpTeX/ +The auto-generated <mark> can be created by `$$<formula>`\x`\eqmark``$$`. The +<label> can be used previously declared by \x`\label``[<label>]`. +Then it is associated to such +auto-generated <mark> and you can write a reference in the form +`see equation~\ref[<label>]`. You can write `\eqmark[<label>]` instead of +`\label[<label>]...\eqmark`. See the \OpTeX/ manual, section~1.4.3. + +\secc[dlines] The `\displaylines` macro + +This macro creates more horizontally centered formulas in one display mode. +The syntax is +\begtt \catcode`\<=13 +$$ \displaylines{ + <formula> \cr + <formula> \cr + ... \cr + <formula> +} $$ +\endtt +Usage of \x`\displaylines` is more +prefered than doing more display modes just behind each other. +Example: +\begtt +$$ \displaylines{ + (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr + = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. +} $$ +\endtt +$$ \displaylines{ + (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr + = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. +} $$ + +The output from `\displaylines` macro is breakable to more pages because +the lines are not encapsulated in one box. The macro uses a special feature of +`\halign` primitive. The disadvantage is that you cannot use `\eqno` nor +`\leqno` nor `\eqmark`. + +\new \OpTeX/ +\OpTeX/ provides alternative form: `\displaylines to<dimen> {<data>}`. +Then the centered formulas are encapsulated in a `\vcenter` box of width <dimen> and +usage of `\eqno` or `\leqno` or `\eqmark` is allowed. +The individual lines have the form `\hbox to<dimen>` and formulas are centered using +`\hss` from both sides. This means that you can set arbitrary <dimen> +without visual change of the formulas. Use smaller <dimen> value than +`\hsize` (or `\displaywidth`\fnote +{`\displaywith` = `\hsize` in most cases but it is +real display width when `\parshape` or `\hangindent` is used.}) +if you want to center formulas with `\eqno` appended. +The internal \TeX/ rule says: the formula with `\eqno` (or `\leqno`) is centered +if its width is less or equal `\displaywidth-4<mark-width>`. So +\begtt \catcode`\<=13 +$$ \displaylines to\hsize-8em {<formula>\cr<formula>}\eqno (1) $$ +\endtt +does global centering, because size of `(1)` is less than 2\,em. +You can do more experiments with this example, +for example `\diplaylines to\hsize{...}` +puts the `\eqno` mark to the next line in the display environment. Read +\TeX/book or \TeX/book naruby, where the precise explanation about such +positioning is. + +\new \OpTeX/ +You can use \"`\displaylines to<dimen>`" for more applications. For example, +you can put more +\"`\displaylines to<dimen>`" in single display mode, one next to second in order +to creating more centered columns with formulas; the width of such columns +are controlled by the <dimen> parameter. +Or, you can give an exception for several lines: + +\begtt \catcode`\<=13 +$$\displaylines to 10cm {<formula>\hfill \cr + <formula>\cr + <formula>\cr + \hfill <formula>} +$$ +\endtt +The example above gives similar result as the \LaTeX/ `multline` environment: +$$\displaylines to \hsize { + (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \hfill \cr + = 3x^9 + 3x^5 + 15x^3 + 4x^8 + 4x^4 + 20x^2 + 5x^7 + 5x^3 + 25x + + 6x^6 + 6x^2 + 30 = \cr + \hfill = 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. } +$$ + + +\secc[elines] The `\eqalign` macro + +The \ii .eqalign \iis .eqalign {{\code{\\eqalign}}} usage is: +\begtt \catcode`\<=13 +$$ \eqalign { <left-side> & <right-side> \cr + <left-side> & <right-side> \cr + ... \cr + <left-side> & <right-side> +} $$ +\endtt +The `\vcenter` box is created with two columns, left column is right aligned +and right column is left aligned. Example: + +\vbox{ +\begtt +$$ \eqalign{ + x + 2y + 3z &= 600 \cr + 12x + y - 3z &= 7 \cr + 4x - y + 5z &= -5 \cr +} $$ +\endtt +\vskip-5.7\baselineskip +{\hsize=1.35\hsize +$$ \eqalign{ + x + 2y + 3z &= 600 \cr + 12x + y - 3z &= 7 \cr + 4x - y + 5z &= -5 \cr +} $$}} + +\bigskip\noindent +The tab \"`&`" should be used just before a relation, i.e. `&=` is right, `=&` +is wrong. All lines are aligned to the used tab. + +Maybe you want more precise alignment in the example above. You can use +`\phantom`: + +\par\nobreak\vbox{ +\begtt +$$ \def\1{\phantom1} \def\+{\phantom+} + \eqalign{ + x + 2y + 3z &= 600 \cr + 12x + \1y - 3z &= \+7 \cr + 4x - \1y + 5z &= -5 \cr +} $$ +\endtt +\vskip-5.7\baselineskip +{\hsize=1.35\hsize +$$ \def\1{\phantom1} \def\+{\phantom+} + \eqalign{ + x + 2y + 3z &= 600 \cr + 12x + \1y - 3z &= \+7 \cr + 4x - \1y + 5z &= -5 +} $$}} +\bigskip +Another typical usage of the `\eqalign` macro: + +\begtt \typosize[10/12] +$$ \eqalign{ + p(x)\,q(x) &= (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr + &= 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. +} $$ +\endtt +$$ \eqalign{ + p(x)\,q(x) &= (3x^3 + 4x^2 + 5x + 6) \cdot (x^6 + x^2 + 5) = \cr + &= 3x^9 + 4x^8 + 5x^7 + 6x^6 + 3x^5 + 4x^4 + 20x^3 + 26x^2 + 25x + 30. +} $$ + +In \OpTeX/, \new\OpTeX/ +the `\eqalign` macro is more flexible. You can set the +`\baselineskip` value by the \x`\eqlines` parameter and math style +by the \x`\eqstyle` parameter. +For example, you need to put the system of \"equations" as a subscript of a sum +operator: +\begtt \typosize[10/12] \adef/{} +$$ + \sum/_{\eqlines{\baselineskip=.7\baselineskip}\eqstyle{\scriptstyle}\eqalign{ + i &\in A \cr + \quad j &\in B\cup C \cr + m &\in C }} + i + j + m +$$ +\endtt +$$ + \sum_{\eqlines{\baselineskip=.7\baselineskip}\eqstyle{\scriptstyle}\eqalign{ + i &\in A \cr + \quad j &\in B\cup C \cr + m &\in C }} + i + j + m +$$ + +\indent \new\OpTeX/ +You can write more equation systems one next second: +\begtt +$$\eqalign{ + x + y + z &= 1 && a + b + c &= -1 \cr + u + v &= 20 && f + g &= -20 \cr + i &= j +}$$ +\endtt +You can use the third column for centered equations +without aligning point. For example: +\begtt \catcode`\<=13 +$$ \left( \eqspace=0pt \eqalign{&& <first equation>\cr + && <second equation>} \right) $$ +\endtt +The \x`\eqspace` is additional space used in the third column to separate +equation systems one next second. + +\new \OpTeX/ +\OpTeX/ extensions summary: +\begitems +* `\eqlines` and `\eqstyle` set baselineskip and math style of the formulas. +* `\eqalign` allows more than two columns: + The first column is right-aligned (no space). The second is left-aligned (no space). + The third column (if used) + is centered with `\eqspace/2` at the left and right boundary of the column. + The fourth is the same as the first. The fifth is the same as second etc. The number + of columns that can be used in `\eqalign` is unlimited. +\enditems + +\secc The `\eqalign` macro with references + +You can give common mark to whole equation system by +`$$\eqalign{<data>}\eqno <mark>$$`. If you want to give marks to individual +lines of the equation system, then you can use another macro: +\x`\eqalignno`. The usage is similar as `\eqalign` but the +third column (if used) is intended to the equation mark. Example: + +\begtt +$$ \eqalignno{ + x + 2y + 3z &= 600 & \rm(A) \cr + 12x + y - 3z &= 7 & \rm(B) \cr + 4x - y + 5z &= -5 & \rm(C) \cr +} $$ +\endtt +\vskip-\baselineskip +$$ \eqalignno{ + x + 2y + 3z &= 600 & \rm(A) \cr + 12x + y - 3z &= 7 & \rm(B) \cr + 4x - y + 5z &= -5 & \rm(C) \cr +} $$ + +The `\leqalignno` macro is similar to `\eqalignno` but the marks are at the left +margin. The \OpTeX/ extensions of `\eqalign` are not available in +`\eqalignno` nor `\leqalignno` macros. + +\new \OpTeX/ +You can use auto-generated marks by `\eqmark` macro: +`$$\eqalign{<data>}\eqmark$$` or: +\begtt +$$ \eqalignno{ + x + 2y + 3z &= 600 & \eqmark[A] \cr + 12x + y - 3z &= 7 & \eqmark[B] \cr + 4x - y + 5z &= -5 & \eqmark[C] \cr +} $$ +\endtt + + +\sec Concept of loading math fonts + +\secc[fams] Math families + +\TeX/ can use more than one math font in math mode. This was a +necessity in the old days when only 128-characters fonts existed. +Each math font used in math mode has its \ii math/family {\em math family} represented by a number. +Math family is a collection of three (almost) equal fonts in three sizes: +first for `\textstyle` and `\displaystyle`, second for `\scriptstyle` +and third for `\scriptscriptstyle`. + +\new Unicode +When Unicode math font is loaded then it includes all three optical sizes and +all characters needed for typesetting math formula. +Theoretically, we can use only one math family with this single font. But more math families +(i.e.\ more fonts in math mode) is still possible. You can combine +characters from more fonts (Unicode fonts and old TFM fonts together) in one math formula. + +\new \OpTeX/ +\OpTeX/ loads the main Unicode math font into math family 1. The math +families 2 and 3 are reserved for specific \TeX/nical reasons, family 4 is +used for `\script` font and families 5, 6, 7, etc. can be used by user for +loading more fonts. The default macro for loading math fonts looks like: + +\begtt \typosize[10/12] +\_def\_normalunimath{% + \_loadumathfamily 1 {\_unimathfont}{} % Main Unicode math font + \_loadmathfamily 4 rsfs % \script (old TFM font) + \_setunimathdimens % set dimen parameters used in math formulas internally +}% +\let\_normalmath=\_normalunimath % this is done when Unicode math is initialized +\endtt +% +Whenever \OpTeX/ needs to resize math fonts (for example in footnotes or +titles), it calls the `\_normalmath` macro to reload all math +families to the desired size. If you want to add the next font, you can add +`\_loadunimathfamily <family> {<Unicode-font>}{<features>}` or +`\_loadmathfamily <family> <TFM-font>` into the `\_normalmath` macro. +The example in section~\ref[newfam] shows how to do it. + +\secc Two variants of math fonts: normal and bold + +All math formulas in the whole document need only one Unicode font (or only one collection +of math fonts as mentioned in section~\ref[fams]). But this +is not really true if titles are in bold font. If a math formula is present in +such a bold title then all characters of this formula must be bolder. +For example \"normal" variables must be in bold italic in titles, symbols +like `+` `=` must be bold and \"normal bold" letters +(e.g., indicating vectors in math formula) must be extra bold in titles. +It means that all fonts from the collection of math fonts must be bolder. +We need a second collection of math fonts with bolder +shape. Unfortunately, it is not always available. + +\new \OpTeX/ +If you have bold variant of used Unicode math font, then you can use +\ii .loadmath \iis .loadmath {{\code{\\loadmath}}} \x`\loadboldmath` command, for example: +\begtt +\loadmath {[xitsmath-regular]} +\loadboldmath {[xitsmath-bold]} \to {[xitsmath-regular]} +\endtt +% +\OpTeX/ uses `\_normalmath` macro for loading collection of math fonts in +\"normal" cases and `\_boldmath` macro for bold titles. The font declared by +\x`\loadboldmath` is used in second case. But if the bold variant of the font is +not available (this is unfortunately more typical), then \OpTeX/ uses faked +bold of main Unicode math font (the `embolden` internal font feature is +used). So, the default `\_boldmath` macro defined by \OpTeX/ looks like: + +\begtt \typosize[10/12] +\_def\_boldunimath{% + \_ifx\_unimathboldfont \_undefined + \_loadumathfamily 1 {\_unimathfont}{embolden=1.7;} % Main faked bold + \_else + \_loadumathfamily 1 {\_unimathboldfont}{} % Main real bold font + \_fi + \_loadmathfamily 4 rsfs % rsfs in not in bold, unfortunately + \_setunimathdimens +}% +\let\_boldmath=\_boldunimath % this is done when Unicode math is initialized +\endtt + +\secc[newfam] Example of using additional math font + +The font `bbold10.tfm` includes double stroked characters, for example, +double stroked plus, double stroked Greek letters and digits. +Try to run `pdftex testfont`, then answer the question about the name of the +font: `bbold10` and then type command `\table\end`. The `testfont.pdf` is +printed with the table of characters of this font. +Most of these characters cannot be found in Unicode math fonts. + +\new \OpTeX/ +We show an example of how to add this font to the collection of used math fonts. +We can re-define the `\_normalmath` macro by: +\begtt \typosize[10/12] +\addto\_normalmath {\_loadmathfamily 5 bbold } + +\_regtfm bbold 0 bbold5 5.5 bbold6 6.5 bbold7 7.5 bbold8 8.5 bbold9 + 9.5 bbold10 11.1 bbold12 15 bbold17 * % using all bbold*.tfm +\_normalmath % reload the math fonts collection +\endtt +% +The string \"`bbold`" is declared by `\_regtfm` as a collection of all +`bbold*.tfm` fonts, the optical sizes are supported. + +\addto\_normalmath {\_loadmathfamily 5 bbold } +\_regtfm bbold 0 bbold5 5.5 bbold6 6.5 bbold7 7.5 bbold8 8.5 bbold9 + 9.5 bbold10 11.1 bbold12 15 bbold17 * % using all bbold*.tfm +\_normalmath +\Umathchardef \bbplus 2 5 "2B +\Umathchardef \bble 3 5 "3C +\Umathchardef \bbge 3 5 "3E + +Finally, we must to declare new \TeX/ sequences for accessing the characters +from the new font, for example: + +\begtt \typosize[10/12] +\Umathchardef \bbplus 2 5 "2B +\Umathchardef \bble 3 5 "3C +\Umathchardef \bbge 3 5 "3E +\endtt +% +The \x`\Umathchardef` \TeX/ primitive declares new \TeX/ sequence used in math +typesetting. The first parameter is a class number (2 means Bin, 3 means Rel, +see the table in the section~\ref[class]). The second parameter is a math +family number. It is 5, see the redefinition of the `\_normalmath` macro above. +The third parameter is a slot in the font. Now you can try to use these characters: +$$ + `a \bbplus b \bbge c` \quad \hbox{gives} \quad a \bbplus b \bbge c. +$$ +% +Maybe, you want to declare a special math selector which can be used as +`$\bball a+b>c$` in order to get $\bbchar a \bbplus b \bbge c$. +Then you can define: + +\begtt \typosize[10/12] +\def\bball {\bbchar \Umathcodenum `+ \bbplus + \Umathcodenum `> \bbge + \Umathcodenum `< \bble } +\endtt + +If you want to add all double stroked Greek letters into `\bball` +selector, then you can do something like this: + +\begtt \typosize[10/12] +\def\setbbgreek #1 {\tmpnum=#1\xargs\setbbgreekA} +\def\setbbgreekA #1{\Umathcode \_ea`#1 0 5 \tmpnum \advance\tmpnum by1 } + +\addto\bball {% + \setbbgreek "0B \alpha \beta \gamma \delta \epsilon \zeta \eta + \theta \iota \kappa \lambda \mu \nu \xi \pi \rho \sigma + \tau \upsilon \phi \chi ; + \setbbgreek "7F \omega ; + \setbbgreek "00 \Gamma \Delta \Theta \Lambda \Xi \Pi \Sigma \Upsilon + \Phi \Psi \Omega ; } +\endtt +% +The \x`\Umathcode`` <input-code> <class> <family> <font-slot>` primitive is used +here. The control sequences `\alpha`, `\beta`, `\gamma` etc. are macros which expand +to the Unicode character of appropriate (non-math) Greek letter. We set the +Umathcode to such character, for example +\code{\\Umathcode `}$\_rmgreek\alpha$` 0 5 "0B` is processed. + +The bold variant of the font `bbold*.tfm` is not available, unfortunately. +We have to settle for normal version of the font in the `\_boldmath` macro: + +\begtt \typosize[10/12] + \addto \_boldmath {\_loadmathfamily 5 bbold } +\endtt + +Another approach of using more Unicode math fonts in a single formula is +shown in +\ulink[http://petr.olsak.net/optex/optex-tricks.html\#addumathfont]{OpTeX trick 0030}. + +\sec Index + +Control sequences listed at pages \pgref[listA]--\pgref[listB] are not +mentioned here again. + +\begmulti 3 +\makeindex +\endmulti + +\bye diff --git a/Master/texmf-dist/doc/optex/optex-techdoc.tex b/Master/texmf-dist/doc/optex/optex-techdoc.tex new file mode 100644 index 00000000000..4ae25a9c7ec --- /dev/null +++ b/Master/texmf-dist/doc/optex/optex-techdoc.tex @@ -0,0 +1,290 @@ +%% This is part of the OpTeX project, see http://petr.olsak.net/optex + +% This file is read from optex-doc.tex +% Use: optex optex-doc +% (three times) to create whole documentation including all references and the index. + +\load [doc.opm] + +\thisoutline {TECHNICAL DOCUMENTATION} + +\chap Technical documentation + +This documentation is written in the source files `*.opm` between +the `\_doc` and `\_cod` pairs or after the `\_endcode` command. +When the format is generated by +\begtt +luatex -ini optex.ini +\endtt +then the text of the documentation is ignored and the format `optex.fmt` is +generated. On the other hand, if you run +\begtt +optex optex-doc.tex +\endtt +then the same `*.opm` files are read when the second chapter of this +documentation is printed. + +A knowledge about \TeX/ is expected from the reader. +You can see a short document +\ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]{\TeX/ in a Nutshell} +or more detail +\ulink[https://eijkhout.net/texbytopic/texbytopic.html]{\TeX/ by topic}. + +Notices about hyperlinks. +If a control sequence is printed in red color in this documentation then +this denotes its \"main documentation point". Typically, the listing where +the control sequence is declared follows immediately. If a control sequence is +printed in the blue color in the listing or in the text +then it is an active link that points (usually) to the main documentation point. +The main documentation point can be an active link that points to a previous +text where the control sequence was +mentioned. Such occurrences are active links to the main documentation point. + +\sec[init] The main initialization file + +The `optex.ini` file is read as the main file when the format is generated. + +{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip} + \def\docfile{optex.ini} + +\verbinput (-4) optex.ini +% +Category codes are set first. Note that the `_` is set to category code +\"letter", it can be used as a part of control sequence names. +Other category codes are set as in the plain \TeX/. + +\verbinput (6-20) optex.ini +% +The \`\optexversion` and \`\fmtname` are defined. + +\verbinput (22-25) optex.ini +% +We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character +is set as `\newlinechar`. + +\verbinput (27-36) optex.ini +% +The basic macros for macro file syntax is defined, i.\,e.\ +`\_endcode`, `\_doc` and `\_cod`. +The `\_codedecl` will be re-defined later. + +\verbinput (38-42) optex.ini +% +Individual `*.opm` macro files are read. + +\verbinput (44-87) optex.ini +% +The file `optex.lua` is embedded into the format as byte-code. +It is documented in section~\ref[lua]. + +\verbinput (89-92) optex.ini + +The `\everyjob` register is initialized and the format is saved by +the `\dump` command. + +\verbinput (94-102) optex.ini + +} + +\printdoctail prefixed.opm +\secc The implementation of the namespaces +\printdoc prefixed.opm + +\sec pdf\TeX/ initialization +\printdoctail luatex-ini.opm +\printdoc luatex-ini.opm + +\sec Basic macros +We define first bundle of basic macros. +\printdoc basic-macros.opm + +\sec Allocators for \TeX/ registers +\printdoctail alloc.opm +\printdoc alloc.opm + +\sec If-macros, loops, is-macros +\printdoc if-macros.opm + +\sec Setting parameters +\printdoctail parameters.opm +\printdoc parameters.opm + +\sec More \OpTeX/ macros +The second bundle of \OpTeX/ macros is here. +\printdoc more-macros.opm + +\sec Using key=value format in parameters +\printdoctail keyval.opm +\printdoc keyval.opm + +\sec Plain \TeX/ macros +All macros from plain \TeX/ are rewritten here. +Differences are mentioned in the documentation below. +\printdoc plain-macros.opm + +\sec Preloaded fonts for text mode +\printdoctail fonts-preload.opm +\printdoc fonts-preload.opm + +\printdoctail fonts-resize.opm +\printdoc fonts-resize.opm + +\printdoctail fonts-select.opm +\secc Implementation of the Font Selection System +\printdoc fonts-select.opm + +\sec [math-preload] Preloaded fonts for math mode +\printdoctail math-preload.opm +\printdoc math-preload.opm + +\sec[math-macros] Math macros +\printdoc math-macros.opm + +\sec Unicode-math fonts +\printdoctail math-unicode.opm + +\sec[opmac-fonts] Scaling fonts in document (high-level macros) +These macros are documented in section~\ref[sizes] from the user point of view. +\printdoc fonts-opmac.opm + +\sec[output] Output routine +\printdoctail output.opm +\printdoc output.opm + +\sec Margins +The `\margins` macro is documented in the section~\ref[marg]. +\printdoc margins.opm + +\sec[colors] Colors +\printdoctail colors.opm +\printdoc colors.opm + +\sec[ref-file] The \code{.ref} file +\printdoctail ref-file.opm +\printdoc ref-file.opm + +\sec[references] References +\printdoctail references.opm +\printdoc references.opm + +\sec Hyperlinks +\printdoctail hyperlinks.opm +\printdoc hyperlinks.opm + +\sec[maketoc] Making table of contents +\printdoc maketoc.opm + +\sec PDF outlines +\secc Nesting PDF outlines +\printdoctail outlines.opm +\printdoc outlines.opm +\secc Strings in PDF outlines +\printdoctail pdfuni-string.opm +\printdoc pdfuni-string.opm + +\sec[sections] Chapters, sections, subsections +\printdoc sections.opm + +\sec[lists] Lists, items +\printdoc lists.opm + +\sec Verbatim, listings +\secc[verb] Inline and \"display" verbatim +\printdoc verbatim.opm +\secc[hisyntax] Listings with syntax highlighting +\printdoctail hi-syntax.opm +\printdoc hi-syntax.opm + +\sec Graphics +\printdoctail graphics.opm +\printdoc graphics.opm + +\sec[table] The \code{\\table} macro, tables and rules +\printdoctail table.opm +\secc[table.impl] Implemetation of the \code{\\table} macro and friends +\printdoc table.opm + +\sec Balanced multi-columns +\printdoc multicolumns.opm + +\sec Citations, bibliography +\secc[bib] Macros for citations and bibliography preloaded in the format +\printdoc cite-bib.opm +\secc[usebib] The \code{\\usebib} command +\printdoctail usebib.opm +\secc The \code{usebib.opm} macro file loaded when \code{\\usebib} is used +\printdoc usebib.opm + +\secc[isobib] Usage of the \code{bib-iso690} style +{\everyintt={\catcode`\<=13 \visiblesp} +\printdoctail bib-iso690.opm } + +\secc Implementation of the \code{bib-iso690} style +\printdoc bib-iso690.opm + +\sec[makeindex] Sorting and making Index +\printdoc makeindex.opm + +\sec[fnotes] Footnotes and marginal notes +\printdoc fnotes.opm + +\sec Styles + \OpTeX/ provides three styles: `\report`, `\letter` and `\slides`. + Their behavior is documented in user part of the manual in the section + \ref[styles] and `\slides` style (for presentations) is documented in + `op-slides.pdf` which is an example of the presentation. +\secc \code{\\report} and \code{\\letter} styles +\printdoc styles.opm +\secc[slides] \code{\\slides} style for presentations +\printdoc slides.opm + +\sec Logos +\printdoc logos.opm + +\sec Multilingual support +\secc Lowercase, uppercase codes +\printdoctail uni-lcuc.opm +\secc Hyphenations +\printdoc hyphen-lan.opm +\printdoctail hyphen-lan.opm +\secc[langphrases] Multilingual phrases and quotation marks +\printdoc languages.opm + +\sec Other macros +Miscellaneous macros are here. +\printdoc others.opm + +\sec[lua] Lua code embedded to the format + +The file `optex.lua` is loaded into the format in `optex.ini` as byte-code +and initialized by `\everyjob`, see section~\ref[init]. + +The file implements part of the functionality from `luatexbase` namespace, +nowadays defined by \LaTeX/ kernel. `luatexbase` deals with modules, +allocators, and callback management. Callback management is a nice extension +and is actually used in \OpTeX/. Other functions are defined more or less just +to suit luaotfload's use. + +\newtoks \_hisyntaxlua +\_hisyntaxlua={% + \_hicolor C \Green + \_replfromto {--}{^^J} {\z C{--#1}^^J}% +} + +{\everytt={\typosize[8/10]\_let\_printverbline=\_printcodeline \medskip} + \commentchars-- \def\docfile{optex.lua} \ttline=-1 + \_def\_printcomments{\_medskip + {\_catcodetable0 \_typosize[10/12]\_everypar={}\_scantextokens\_ea{\_vcomments}\par}% + \_bigskip + } + +\verbinput \hisyntax{lua} (4-) optex.lua +} + + +\sec Printing documentation +\printdoctail doc.opm +\printdoc doc.opm + +\enddocument + diff --git a/Master/texmf-dist/doc/optex/optex-userdoc.tex b/Master/texmf-dist/doc/optex/optex-userdoc.tex new file mode 100644 index 00000000000..a70cedcf4d8 --- /dev/null +++ b/Master/texmf-dist/doc/optex/optex-userdoc.tex @@ -0,0 +1,2019 @@ +%% This is part of the OpTeX project, see http://petr.olsak.net/optex + +% This file is read from optex-doc.tex +% Use: optex optex-doc (three times) to create whole documentation. + +\let\new=\relax + +\sec Starting with \OpTeX/ +%%%%%%%%%%%%%%%%%%%%%%%%% + +\new +\OpTeX/ is compiled as a format for \LuaTeX/. Maybe there is a command +`optex` in your \TeX/ distribution. Then you can write into the command line + +\begtt +optex document +\endtt +% +You can try to process `optex op-demo` or `optex optex-doc`. + +If there is no `optex` command, see more information about installation +\OpTeX/ at \url{http://petr.olsak.net/optex}. + +A minimal document should be + +\begtt +\fontfam[LMfonts] +Hello World! \bye +\endtt + +The first line \~`\fontfam[LMfonts]` tells that Unicode Latin Modern +fonts (derived from Computer Modern) are used. If you omit this line then +preloaded Latin Modern fonts are used but preloaded fonts cannot be in +Unicode\fnote +{This is a technical limitation of \LuaTeX/ for fonts downloaded in formats: +only 8bit fonts can be preloaded.}. +So the sentence `Hello World` will be OK without the first line, but you +cannot print such sentence in other languages (for example `Ahoj světe!`) +where Unicode fonts are needed +because the characters like `ě` are not mapped correctly in preloaded +fonts. + +A somewhat larger example with common settings should be: + +\begtt \catcode`!=0 +\fontfam[Termes] % selecting Unicode font family Termes (section !ref[fontfam]) +\typosize[11/13] % setting default font size and baselineskip (sec. !ref[sizes]) +\margins/1 a4 (1,1,1,1)in % setting A4 paper, 1 in margins (section !ref[marg]) +\cslang % Czech hyphenation patterns (section !ref[lang]) + +Tady je zkušební textík v českém jazyce. +\bye +\endtt +% +You can look at `op-demo.tex` file for a more complex, but still simple example. + +\sec Page layout +%%%%%%%%%%%%%%%% + +\secc[marg] Setting the margins +%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The \^`\margins` command declares margins of the document. This command have +the following parameters: + +\begtt \catcode`\<=13 +\margins/<pg> <fmt> (<left>,<right>,<top>,<bot>)<unit> + example: +\margins/1 a4 (2.5,2.5,2,2)cm +\endtt + +Parameters are: + +\begitems +* <pg> \dots\ `1` or `2` specifies one-page or two-pages design. +* <fmt> \dots\ paper format (a4, a4l, a5, letter, etc. or user defined). +* <left>, <right>, <top>, <bot> \dots\ gives the amount of left, right, + top and bottom margins. +* <unit> \dots\ unit used for values <left>, <right>, <top>, <bot>. +\enditems + +Each of the parameters <left>, <right>, <top>, <bot> can be empty. +If both <left> and <right> are nonempty then `\hsize` is set. Else `\hsize` +is unchanged. If both <left> and <right> are empty then typesetting area is +centered in the paper format. The analogical rule works when <top> or <bot> +parameter is empty (`\vsize` instead `\hsize` is used). Examples: + +\begtt +\margins/1 a4 (,,,)mm % \hsize, \vsize untouched, + % typesetting area centered +\margins/1 a4 (,2,,)cm % right margin set to 2cm + % \hsize, \vsize untouched, vertically centered +\endtt + +If `<pg>=1` then all pages have the same margins. If `<pg>=2` then the +declared margins are true for odd pages. The margins at the even pages are +automatically mirrored in such case, it means that <left> is replaced by +<right> and vice versa. + +\OpTeX/ declares following paper formats: a4, a4l (landscape~a4), +a5, a5l, a3, a3l, b5, letter and user can declare another own format by \~`\sdef`: + +\begtt +\sdef{_pgs:b5l}{(250,176)mm} +\sdef{_pgs:letterl}{(11,8.5)in} +\endtt + +The `<fmt>` can be also in the form `(<width>,<height>)<unit>` where `<unit>` is +optional. If it is missing then `<unit>` after margins specification is +used. For example: + +\begtt +\margins/1 (100,200) (7,7,7,7)mm +\endtt +% +declares the paper 100$\times$200\,mm with all four margins 7\,mm. The spaces +before and after <fmt> parameter are necessary. + +The command \^`\magscale[<factor>]` scales the whole typesetting area. +\new The fixed point of such scaling is the upper left corner of the paper sheet. +Typesetting (breakpoints etc.) is unchanged. All units are relative after +such scaling. Only paper format's dimensions stay unscaled. Example: + +\begtt +\margins/2 a5 (22,17,19,21)mm +\magscale[1414] \margins/1 a4 (,,,)mm +\endtt +% +The first line sets the `\hsize` and `\vsize` and margins for final +printing at a5 format. The setting on the second line centers the scaled +typesetting area to the true a4 paper while breaking points for paragraphs +and pages are unchanged. It may be usable for +review printing. After the review is done, the second line can be commented out. + +\secc Concept of the default page +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\OpTeX/ uses \"output routine" for page design. +It is very similar to the Plain \TeX/ output routine. +There is \^`\headline` followed by \"page body" followed by +\^`\footline`. The \^`\headline` is empty by default and it can be used +for running headers repeated on each page. The \^`\footline` prints +centered page number by default. You can set the \^`\footline` to empty +using \^`\nopagenumbers` macro. + +The margins declared by \^`\margins` macro (documented in the previous +section~\ref[marg]) is concerned to the page body, +i.e.\ the \^`\headline` and \^`\footline` are placed to the top and bottom +margins. + +The distance between the \^`\headline` and the top of the page body is given by +the \^`\headlinedist` register. The distance between bottom of the page body and +the \^`\footline` is given by \^`\footlinedist`. The default values are: + +\begtt +\headline = {} +\footline = {\_hss\_rmfixed \_folio \_hss} % \folio expands to page number +\headlinedist = 14pt % from baseline of \headline to top of page body +\footlinedist = 24pt % from last line in pagebody to baseline of footline +\endtt + +The page body should be divided into top insertions (floating tables and +figures) followed by a real text and followed by footnotes. +Typically, the only real text is here. + +The \^`\pgbackground` tokens list is empty by default but it can be used for +creating a background of each page (colors, picture, watermark for example). +The macro \^`\draft` uses this register and puts big text DRAFT as a watermark +to each page. You can try it. + +More about the page layout is documented in sections~\ref[oparams] and~\ref[output]. + +\secc Footnotes and marginal notes +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The Plain \TeX/'s macro \^`\footnote` can be used as usual. But a new macro +\^`\fnote{<text>}` is defined. The footnote mark is added automatically and it +is numbered +\new +on each chapter from one\fnote +{You can declare \^`\fnotenumglobal` if you want footnotes numbered in whole +document from one or \^`\fnotenumpages` if you want footnotes numbered at each +page from one. Default setting is \^`\fnotenumchapters`}. +The <text> is scaled to 80 \%. +User can redefine footnote mark or scaling, as shown in the section~\ref[fnotes]. + +The \^`\fnote` macro is fully applicable only in \"normal outer" paragraph. +It doesn't work inside boxes (tables, for example). If you are solving such +a case then you can use the command \^`\fnotemark``<numeric-label>` inside the box: only the +footnote mark is generated here. When the box is finished you can use +\^`\fnotetext{<text>}`. This macro puts the <text> to the footnote. +The <numeric-label> has to be `1` if only one such command is in the box. +Second \^`\fnotemark` inside the same box has to have the parameter `2` etc. +The same number of \^`\fnotetext`s have to be written +after the box as the number of \^`\fnotemark`s inserted inside the box. +Example: + +\begtt +Text in a paragraph\fnote{First notice}... % a "normal" footnote +\table{...}{...\fnotemark1...\fnotemark2...} % two footnotes in a box +\fnotetext{Second notice} +\fnotetext{Third notice} +... +\table{...}{...\fnotemark1...} % one footnote in a box +\fnotetext{Fourth notice} +\endtt + +The marginal note can be printed by the \^`\mnote{<text>}` macro. The <text> +is placed to the right margin on the odd pages and it is placed to the left +margin on the even pages. This is done after second \TeX{} run because the +relevant information is stored in an external file and read from it again. +If you need to place the notes only to the fixed margin write +\^`\fixmnotes\right` or \^`\fixmnotes\left`. + +The <text> is formatted as a little paragraph with the maximal width +\^`\mnotesize` ragged left on the left margins or ragged right on the right +margins. The first line of this little paragraph has its vertical position +given by the position of \^`\mnote` in the text. The exceptions are possible +by using the `up` keyword: \~`\mnote`` up<dimen>{<text>}`. +You can set such <dimen> to each \^`\mnote` manually in final printing +in order to margin notes do not overlap. The positive value of <dimen> +shifts the note up and negative value shifts it down. For example +\^`\mnote`` up 2\baselineskip{<text>}` shifts this marginal note two lines up. + +\sec Fonts +%%%%%%%%%% + +\secc[fontfam] Font families +%%%%%%%%%%%%%%%%%%%%%%% + +You can select the font family by \^`\fontfam[<Family-name>]`. +The argument <Family-name> is case insensitive and spaces are ignored in it. For +example, \^`\fontfam[LM Fonts]` is equal to \^`\fontfam[LMfonts]` and it is equal +to \^`\fontfam[lmfonts]`. Several aliases are prepared, thus +\^`\fontfam[Latin Modern]` can be used for loading Latin Modern family too. + +If you write \^`\fontfam[?]` then all font families registered in \OpTeX/ +are listed on the terminal and in the log file. +If you write \^`\fontfam[catalog]` then a catalog of all fonts registered in +\OpTeX/ and available in your \TeX/ system is printed. The instructions +on how to register your own font family are appended in the catalog. + +If the family is loaded then {\em font modifiers} applicable in such font family +are listed on the terminal: (`\caps`, `\cond` for example). +And there are four basic {\em variant selectors} (\^`\rm`, \^`\bf`, \^`\it`, \^`\bi`). +The usage of variant selectors is the same as in Plain \TeX: +`{\it italics text}`, `{\bf bold text}` etc. + +The font modifiers (`\caps`, `\cond` for example) can +be used before a variant selector and they +can be (independently) combined: `\caps\it` or `\cond\caps\bf`. The +modifiers keep their internal setting until the group ends or until another +modifier that negates the previous feature is used. So +`{\caps \rm First text \it Second text}` +gives {\caps \rm First text \it Second text}. + +The font modifier without following variant selector does not change the font +actually, it only prepares data used by next variant selectors. +There is one special variant selector \^`\currvar` which does not change the +selected variant but reloads the font due to (maybe newly +specified) font modifier(s). + +The context between variants \^`\rm` $\leftrightarrow$ \^`\it` and +\^`\bf` $\leftrightarrow$ \^`\bi` is kept by the \^`\em` +macro (emphasize text). +It switches from current \^`\rm` to \^`\it`, from current \^`\it` to \^`\rm`, from +current \^`\bf` to \^`\bi` and from current \^`\bi` to \^`\bf`. +The italics correction `\/` is inserted automatically, if needed. Example: + +\begtt +This is {\em important} text. % = This is {\it important\/} text. +\it This is {\em important} text. % = This is\/ {\rm important} text. +\bf This is {\em important} text. % = This is {\bi important\/} text. +\bi This is {\em important} text. % = This is\/ {\bf important} text. +\endtt + +\new +More about the \OpTeX/ Font Selection System is written in the technical +documentation in the section~\ref[fontsystem]. +You can mix more font families in your document, you can +declare your own variant selectors or modifiers, etc. + +\secc[sizes] Font sizes +%%%%%%%%%%%%%%%%%%%%% + +The command \^`\typosize[<fontsize>/<baselineskip>]` sets the font size of text and +math fonts and baselineskip. If one of these two parameters is empty, the +corresponding feature stays unchanged. Don't write the unit of these +parameters. The unit is internally set to \^`\ptunit` which is 1pt by default. +You can change the unit by the command \^`\ptunit=<something-else>`, +for instance \^`\ptunit=1mm` enlarges all font sizes declared by \^`\typosize`. +Examples: + +\begtt +\typosize[10/12] % default of Plain TeX +\typosize[11/12.5] % font 11pt, baseline 12.5pt +\typosize[8/] % font 8pt, baseline unchanged +\endtt + +The commands for font size setting described in this section +have local validity. If you put them into a group, +the settings are lost when the group is finished. If you set +something relevant with paragraph shape (baselineskip given by +\^`\typosize` for example) then you must first finalize the +paragraph before closing the group: +`{\typosize[12/14] ...<text of paragraph>... \par}`. + +The command \^`\typoscale[<font-factor>/<baselineskip-factor>]` +sets the text and math fonts +size and baselineskip as a multiple of the current fonts size and +baselineskip. The factor is written in \"scaled"-like way, it means that 1000 +means factor one. The empty parameter is equal to the parameter 1000, +i.e. the value stays unchanged. Examples: + +\begtt +\typoscale[800/800] % fonts and baselineskip re-size to 80 % +\typoscale[\magstep2/] % fonts bigger 1,44times (\magstep2 expands to 1440) +\endtt + +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 +saved in registers \^`\mainfosize` and \^`\mainbaselineskip`. + +\new +The \^`\typoscale` command does scaling with respect to current values by default. +If you want to do it with respect to the main values, type \^`\scalemain` immediately +before \^`\typoscale` command. + +\begtt +\typosize[12/14.4] % first usage in document, sets main values internally +\typosize[15/18] % bigger font +\scalemain \typoscale[800/800] % reduces from main values, no from current. +\endtt + +The \^`\typosize` and \^`\typoscale` macros initialize the font family by `\rm`. +You can re-size only the current font by the command +\^`\thefontsize[<font-size>]` or the font can be rescaled by +\^`\thefontscale[<factor>]`. These macros don't change math fonts sizes nor +baselineskip. + +\new +There is \"low level" \^`\setfontsize{<size-spec>}` command which behaves like +a font modifier and sets given font size used by next variant selectors. +It doesn't change the font size immediately, but the following variant selector +does it. For example \^`\setfontsize{at15pt}`\^`\currvar` sets current variant to 15pt. + +If you are using a font family with \"optical sizes feature" (i.\,e.\ there +are more recommended sizes of the same font which are not scaled +linearly; a good example is Computer Modern aka Latin Modern fonts) +then the recommended size is selected by all mentioned commands automatically. + +More information about resizing of fonts is documented in the +section~\ref[setfontsize]. + +\secc Typesetting math +%%%%%%%%%%%%%%%%%%%%% + +See the additional document +\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf] +{Typesetting Math with \OpTeX/} for more details about this issue. + +\OpTeX/ preloads a collection of 7bit Computer Modern math fonts +and AMS fonts in its format for math typesetting. +You can use them in any size and in the \^`\boldmath` variant. +% +\new +Most declared text font families (see \^`\fontfam` in the section~\ref[fontfam]) +are configured with a recommended Unicode +math font. This font is automatically loaded unless you specify +\^`\noloadmath` before first \^`\fontfam` command. See log file for more +information about loading text font family and Unicode math fonts. If you +prefer another Unicode math font, specify it by \^`\loadmath{[<font-file>]}` +or \^`\loadmath{<font-name>}` before first \^`\fontfam` command. + +Hundreds math symbols and operators like in AMS\TeX/ are accessible. +For example `\alpha` $\alpha$, `\geq`~$\geq$, `\sum` $\sum$, +`\sphericalangle` $\sphericalangle$, `\bumpeq`, $\bumpeq$. See AMS\TeX/ +manual or +\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-math.pdf] +{Typesetting Math with \OpTeX/} for complete list of math symbols. + +The following math alphabets are available: + +\begtt \catcode`\$=3 \catcode`/=0 \medmuskip=0mu \adef{ }{ } +\mit % mathematical variables $abc-xyz,ABC-XYZ$ +\it % text italics $/it abc-xyz,ABC-XYZ$ +\rm % text roman $/rm abc-xyz,ABC-XYZ$ +\cal % normal calligraphics $/cal ABC-XYZ$ +\script % script $/script ABC-XYZ$ +\frak % fracture $/frak abc-xyz,ABC-XYZ$ +\bbchar % double stroked letters $/bbchar ABC-XYZ$ +\bf % sans serif bold $/bf abc-xyz,ABC-XYZ$ +\bi % sans serif bold slanted $/bi abc-xyz,ABC-XYZ$ +\endtt + +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 +matrices. You can re-declare them, see section~\ref[unimath-codes] where +definitions of Unicode math variants of \^`\bf` and \^`\bi` selectors are documented. + +The math fonts can be scaled by \^`\typosize` and \^`\typoscale` macros. +Two math fonts collections are prepared: \^`\normalmath` for normal weight +and \^`\boldmath` for bold. The first one is set by default, the second one +is usable for math formulae in titles typeset in bold, for example. + +\new +You can use \^`\mathbox{<text>}` inside math mode. It behaves as `{\hbox{<text>}}` +(i.e. the <text> is printed in horizontal non-math mode) +but the size of the <text> is adapted to the context of math size (text or script or +scriptscript). + +\sec Typical elements of the document +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\secc[chap] Chapters and sections +%%%%%%%%%%%%%%%%%%%%%%%%%% + +The documents can be divided into chapters (\^`\chap`), +sections (\^`\sec`), subsections (\^`\secc`) and they can be titled +by \^`\tit` command. The parameters are separated by the end of current line (no +braces are used): + +\begtt \catcode`\<=13 +\tit Document title <end of line> +\chap Chapter title <end of line> +\sec Section title <end of line> +\secc Subsection title <end of line> +\endtt + +The chapters are automatically numbered by one number, sections by two numbers +(chapter.section), and subsections by three numbers. If there are no chapters +then sections have only one number and subsections two. + +The implicit design of the titles of chapter etc.\ is implemented in the +macros \^`\_printchap`, \^`\_printsec` and \^`\_printsecc`. A designer can simply change +these macros if he/she needs another behavior. + +The first paragraph after the title of chapter, section, and subsection is +not indented but you can type `\let`\^`\_firstnoindent=\relax` if you need all +paragraphs indented. + +If a title is so long then it breaks into more lines in the output. It is better to hint at the +breakpoints because \TeX/ does not interpret the meaning of the title. +Users can put the \^`\nl` (means newline) to the breakpoints. + +If you want to arrange a title to more lines in your source file then you can +use `^^J` at the end of each line (except the last one). +When `^^J` is used, then the reading of the title continues at the next line. +The \"normal" comment character `%` doesn't work in titles. +You can use \^`\nl`{\visiblesp` ^^J`} if you want to have corresponding lines in the source +and the output. + +The chapter, section, or subsection isn't numbered if the \^`\nonum` precedes. +And the chapter, section, or subsection isn't delivered to the table of +contents if \^`\notoc` precedes. You can combine both prefixes. + +\secc[cap] Another numbered objects +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Apart from chapters, sections, and subsections, there are another +automatically numbered objects: equations, captions for tables and +figures. The user can declare more numbered objects. + +If the user writes the \^`\eqmark` as the last element of the display mode then +this equation is numbered. The equation number is printed in brackets. This number +is reset in each section by default. + +If the \^`\eqalignno` is used, then user can put \^`\eqmark` to the last column +before `\cr`. For example: + +\begtt +\eqalignno{ + a^2+b^2 &= c^2 \cr + c &= \sqrt{a^2+b^2} & \eqmark \cr} +\endtt + +Another automatically numbered object is a caption which is tagged by \^`\caption/t` for +tables and \^`\caption/f` for figures. The caption text follows. +The \^`\cskip` can be used between \^`\caption` text and the real object (table +or figure). You can use two orders: `<caption>\cskip <object>` or +`<object>\cskip <caption>`. +The \^`\cskip` creates appropriate vertical space between them. Example: + +\begtt +\caption/t The dependency of the computer-dependency on the age. +\cskip +\noindent\hfil\table{rl}{ + age & value \crl\noalign{\smallskip} + 0--1 & unmeasured \cr + 1--6 & observable \cr + 6--12 & significant \cr + 12--20 & extremal \cr + 20--40 & normal \cr + 40--60 & various \cr + 60--$\infty$ & moderate} +\endtt + +This example produces: + +\medskip +\caption/t The dependency of the computer-dependency on the age. +\cskip +\noindent\hfil\table{rl}{ + age & value \crl\noalign{\smallskip} + 0--1 & unmeasured \cr + 1--6 & observable \cr + 6--12 & significant \cr + 12--20 & extremal \cr + 20--40 & normal \cr + 40--60 & various \cr + 60--$\infty$ & moderate} +\medskip + +You can see that the word \"Table" followed by a number is added by the macro +`\caption/t`. +The caption text is centered. If it occupies more lines then the +last line is centered. + +The macro \^`\caption/f` behaves like \^`\caption/t` but it is intended for +figure captions with independent numbering. +The word (Table, Figure) depends on the selected language (see +section~\ref[lang] about languages). + +If you wish to make the table or figure as a floating object, you need to use +Plain \TeX/ macros \^`\midinsert` or \^`\topinsert` terminated by \^`\endinsert`. +Example: + +\begtt +\topinsert % table and its caption printed at the top of the current page + <caption and table> +\endinsert +\endtt +% +The pair \^`\midinsert`...\^`\endinsert` prefers to put the enclosed object +to the current place. Only if this is unable due to page breaking, it +behaves like \^`\topinsert`...\^`\endinsert`. + +\new +There are five prepared counters `A`, `B`, `C`, `D` and `E`. +They are reset in each chapter and section\fnote +{This feature can be changed, see the section~\ref[sections] in the technical documentation.}. +They can be used in context of \^`\numberedpar` `<letter>{<text>}` +macro. For example: +\begtt +\def\theorem {\numberedpar A{Theorem}} +\def\corollary {\numberedpar A{Corollary}} +\def\definition {\numberedpar B{Definition}} +\def\example {\numberedpar C{Example}} +\endtt +% +Three independent numbers are used in this example. One for Theorems and Corollaries +second for Definitions and third for Examples. The user can write +`\theorem Let $M$ be...` and the new paragraph is started with the text: +{\bf Theorem 1.4.1.} Let $M$ be... +You can add an optional parameter in brackets. For example, +`\theorem [(L'Hôpital's rule)] Let $f$, $g$ be...` +is printed like {\bf Theorem 1.4.2 (L'Hôpital's rule).} Let $f$, $g$ be... + +\secc References +%%%%%%%%%%%%%%% + +Each automatically numbered object documented in +sections \ref[chap] and \ref[cap] can be referenced +\new +if optional parameter +`[<label>]` is appended to \^`\chap`, \^`\sec`, +\^`\secc`, \^`\caption/t`, \^`\caption/f` or \^`\eqmark`. The alternative syntax is +to use \^`\label[<label>]` before mentioned commands (not necessarily directly +before). The reference is realized by \^`\ref[<label>]` or \^`\pgref[<label>]`. +Example: + +\begtt +\sec[beatle] About Beatles + +\noindent\hfil\table{rl}{...} % the table +\cskip +\caption/t [comp-depend] The dependency of the comp-dependency on the age. + +\label[pythagoras] +$$ a^2 + b^2 = c^2 \eqmark $$ + +Now we can point to the section~\ref[beatle] on the page~\pgref[beatle] +or write something about the equation~\ref[pythagoras]. Finally there +is an interesting Table~\ref[comp-depend]. +\endtt + +If there are forward referenced objects then users have to run \TeX{} twice. +During each pass, the working `*.ref` file (with references data) is created +and this file is used (if it exists) at the beginning of the document. + +You can use the \^`\label[<label>]` before the `\theorem`, `\definition` etc.\ +(macros defined with `\numberedpar`) if you want to reference these numbered objects. +You can't use `\theorem[<label>]` because the optional parameter +is reserved to another purpose here. + +You can create a reference to whatever else by commands +\^`\label[<label>]`\^`\wlabel{<text>}`. The connection between <label> and +<text> is established. The \^`\ref[<label>]` will print <text>. + +By default, labels are not printed, of course. But if you are preparing a +draft version of your document then you can declare \^`\showlabels`. The labels +are printed at their destination places after such a declaration. + +\secc Hyperlinks, outlines +%%%%%%%%%%%%%%%%%%%%%%%%% + +If the command \^`\hyperlinks` `<color-in> <color-out>` is used at the beginning of +the document, then the following objects are hyperlinked in the PDF output: + +\begitems +* numbers and texts generated by \^`\ref` or \^`\pgref`, +* numbers of chapters, sections, subsections, and page numbers in the table of contents, +* numbers or marks generated by \~`\cite` command (bibliography references), +* texts printed by \~`\url` or \~`\ulink` commands. +\enditems + +The last object is an external link and it is colored by +<color-out>. Other links are internal and they are colored by +<color-in>. Example: + +\begtt +\hyperlinks \Blue \Green % internal links blue, URLs green. +\endtt + +You can use another marking of active links: by frames which are visible in +the PDF viewer but invisible when the document is printed. The way to do it +is to define the macros \^`\_pgborder`, \^`\_tocborder`, \^`\_citeborder`, +\^`\_refborder` and \^`\_urlborder` as the triple of RGB components of the used +color. Example: + +\begtt +\def\_tocborder {1 0 0} % links in table of contents: red frame +\def\_pgborder {0 1 0} % links to pages: green frame +\def\_citeborder {0 0 1} % links to references: blue frame +\endtt + +By default, these macros are not defined. It means that no frames are created. + +The hyperlinked footnotes can be activated by \^`\fnotelinks` `<color-fnt> <color-fnf>` +where footnote marks in the text have `<color-fnt>` and the same footnote marks +in footnotes have <color-fnf>. You can define relevant borders +\^`\_fntborder` and \^`\_fnfborder` analogically as \^`\_pgborder` (for example). + +There are \"low level" commands to create the links. You can specify the +destination of the internal link by \^`\dest[<type>:<label>]`. The +active text linked to the \^`\dest` can be created by +\^`\ilink[<type>:<label>]{<text>}`. The `<type>` parameter is one of +the `toc`, `pg`, `cite`, `ref`, or another special for your purpose. +These commands create internal links only when \^`\hyperlinks` is declared. + +The \^`\url` macro prints its parameter in \~`\tt` font and creates a potential +breakpoints in it (after slash or dot, for example). If the \^`\hyperlinks` +declaration is used then the parameter of \^`\url` is treated as an external URL link. +An example: `\url{http://www.olsak.net}` creates \url{http://www.olsak.net}. +The characters \code{\%}, `\`, `#`, `{`, and `}` have to be protected by +backslash in the \^`\url` argument, the other special characters `~`, +`^`, `&` can be written as single character\fnote +{More exactly, there are the same rules as for `\code` command, see +section~\ref[verbatim].}. +You can insert the `\|` command +in the `\url` argument as a potential breakpoint. + +If the linked text have to be different than the URL, you can use +\^`\ulink[<url>]{<text>}` macro. For example: +`\ulink[http://petr.olsak.net/optex]{\OpTeX/ page}` +outputs to the text +\ulink[http://petr.olsak.net/optex]{\OpTeX/ page}. +The characters \code{\%}, `\`, `#`, `{`, and `}` must by escaped in +the <url> parameter. + +The PDF format provides {\em outlines} which are notes placed in the special frame of +the PDF viewer. These notes can be managed as a structured and hyperlinked +table of contents of the document. The command \^`\outlines{<level>}` creates +such outlines from data used for the table of contents in the document. The +<level> parameter gives the level of opened sub-outlines +in the default view. The deeper levels can be opened by mouse click on the +triangle symbol after that. + +\new +If you are using a special unprotected macro in section titles then \^`\outlines` macro +may crash. You must declare a variant of the macro for outlines case which is +expandable. Use \~`\regmacro` in this case. See the section \ref[toc] for more information +about \~`\regmacro`. + +The command \^`\insertoutline{<text>}` inserts a next entry into PDF outlines at +the main level~0. These entries can be placed before the table of contents (created +by \^`\outlines`) or after it. Their hyperlink destination is in the place +where the \^`\insertoutline` macro is used. + +The command \^`\thisoutline{<text>}` uses <text> in the outline instead of default +title text for the first following `\chap`, `\sec`, or `\secc`. +Special case: \^`\thisoutline{\relax}` doesn't create any outline for the following +`\chap`, `\sec`, or `\secc`. + +\secc Lists +%%%%%%%%%% + +The list of items is surrounded by \^`\begitems` and \^`\enditems` commands. +The asterisk (`*`) is active within this environment and it starts one item. +The item style can be chosen by the \^`\style` parameter written after \^`\begitems`: + +\begtt +\style o % small bullet +\style O % big bullet (default) +\style - % hyphen char +\style n % numbered items 1., 2., 3., ... +\style N % numbered items 1), 2), 3), ... +\style i % numbered items (i), (ii), (iii), ... +\style I % numbered items I, II, III, IV, ... +\style a % items of type a), b), c), ... +\style A % items of type A), B), C), ... +\style x % small rectangle +\style X % big rectangle +\endtt + +For example: + +\begtt +\begitems +* First idea +* Second idea in subitems: + \begitems \style i + * First sub-idea + * Second sub-idea + * Last sub-idea + \enditems +* Finito +\enditems +\endtt +% +produces: + +\begitems +* First idea +* Second idea in subitems: + \begitems \style i + * First sub-idea + * Second sub-idea + * Last sub-idea + \enditems +* Finito +\enditems + +Another style can be defined by the command \~`\sdef{_item:<style>}{<text>}`. +Default item can be set by \^`\defaultitem={<text>}`. +The list environments can be nested. Each new level of items is indented by +next multiple of \^`\iindent` value which is set to `\parindent` by default. +The \^`\ilevel` register says what level of items is currently processed. +Each \^`\begitems` starts \^`\everylist` tokens register. You can set, for +example: +\begtt +\everylist={\ifcase\ilevel\or \style X \or \style x \else \style - \fi} +\endtt + +You can say \^`\begitems` \^`\novspaces` if you don't want vertical spaces above +and below the list. The nested item list is without vertical spaces +automatically. More information about the design of lists of items should be +found in the section~\ref[lists]. + +A \"selected block of text" can be surrounded by +\^`\begblock`\dots\^`\endblock`. The default design of blocks of text is +indented text in smaller font. The blocks of text can be nested. + +\secc Tables +%%%%%%%%%%% + +The macro \^`\table{<declaration>}{<data>}` provides similar <declaration> +of tables as in \LaTeX: you can use letters `l`, `r`, `c`, each letter declares +one column (aligned to left, right, center, respectively). +These letters can be combined by the `|` character (vertical line). Example + +\begtt +\table{||lc|r||}{ \crl + Month & commodity & price \crli \tskip2pt + January & notebook & \$ 700 \cr + February & skateboard & \$ 100 \cr + July & yacht & k\$ 170 \crl} +\endtt +% +generates the result: + +\vskip-\medskipamount +\noindent\hfil\table{||lc|r||}{ \crl + Month & commodity & price \crli \tskip2pt + January & notebook & \$ 700 \cr + February & skateboard & \$ 100 \cr + July & yacht & k\$ 170 \crl} +\medskip + +Apart from `l`, `r`, `c` declarators, you can use the `p{<size>}` declarator +which declares the column with paragraphs of given width. More precisely, +a long text in the table cell is printed as a multiline paragraph with given width. +By default, the paragraph is left-right justified. But there are +alternatives: + +\begitems +* `p{<size>`\^`\fL}` fit left, i.e.\ left justified, ragged right, +* `p{<size>`\^`\fR}` fit right, i.e.\ right justified, ragged left, +* `p{<size>`\^`\fC}` fit center, i.e.\ ragged left plus right, +* `p{<size>`\^`\fS}` fit special, short one-line pararaph centered, + long paragraph normal, +* `p{<size>`\^`\fX}` fit extra, left-right justified but last line centered. +\enditems + +You can use `(<text>)` in the <declaration>. Then this text is applied in +each line of the table. For example `r(\kern10pt)l` adds more 10\,pt space +between `r` and `l` rows. + +An arbitrary part of the <declaration> can be repeated by a <number> +prefixed. For example `3c` means `ccc` or `c 3{|c}` means +`c|c|c|c`. Note that spaces in the <declaration> are ignored and you +can use them in order to more legibility. + +The command `\cr` used in the <data> part of the table +is generally known from Plain \TeX. It marks the end of each row in the table. +Moreover \OpTeX/ defines following similar commands: + +\begitems +* \^`\crl` \dots\ the end of the row with a horizontal line after it. +* \^`\crll` \dots\ the end of the row with a double horizontal line after it. +* \^`\crli` \dots\ like \^`\crl` but the horizontal line doesn't intersect the + vertical double lines. +* \^`\crlli` \dots\ like \^`\crli` but horizontal line is doubled. +* \^`\crlp{<list>}` \dots\ like \^`\crli` but the lines are drawn only in the + columns mentioned in comma-separated `<list>` of their numbers. + The <list> can include `<from>-<to>` declarators, for example + \^`\crlp{1-3,5}` is equal to \^`\crlp{1,2,3,5}`. +\enditems + +The \^`\tskip``<dimen>` command works like the `\noalign{\vskip<dimen>}` +immediately after `\cr*` commands but it doesn't interrupt the vertical lines. + +\new +You can use the following parameters for the \^`\table` macro. Default values are listed +too. + +\begtt +\everytable={} % code used in \vbox before table processing +\thistable={} % code used in \vbox, it is removed after using it +\tabiteml={\enspace} % left material in each column +\tabitemr={\enspace} % right material in each column +\tabstrut={\strut} % strut which declares lines distance in the table +\tablinespace=2pt % additional vert. space before/after horizontal lines +\vvkern=1pt % space between lines in double vertical line +\hhkern=1pt % space between lines in double horizontal line +\tabskip=0pt % space between columns +\tabskipl=0pt \tabskipr=0pt % space before first and after last column +\endtt + +Example: if you do \^`\tabiteml={$\enspace}`\^`\tabitemr={\enspace$}` then +the \^`\table` acts like \LaTeX's array environment. + +If there is an item that spans to more than one column in the table then +the macro \^`\multispan{<number>}` (from Plain \TeX) can help you. Another +alternative is +the command \^`\mspan``<number>[<declaration>]{<text>}` +which spans <number> columns and formats the <text> by the +<declaration>. The <declaration> must include a declaration of only one column +with the same syntax as common \^`\table` <declaration>. +If your table includes vertical rules and you want to +create continuous vertical rules by \^`\mspan`, then use rule declarators `|` +after `c`, `l` or `r` letter in \^`\mspan` <declaration>. The +exception is only in the case when \^`\mspan` includes the first +column and the table have rules on the left side. The example of \^`\mspan` +usage is below. + +The \^`\frame{<text>}` makes a frame around <text>. You can put the whole \^`\table` +into \^`\frame` if you need double-ruled border of the table. Example: + +\begtt +\frame{\table{|c||l||r|}{ \crl + \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli + first & second & third \crlli + seven & eight & nine \crli}} +\endtt +% +creates the following result: + +\hfil\frame{\table{|c||l||r|}{\crl + \mspan3[|c|]{\bf Title} \crl \noalign{\kern\hhkern}\crli + first & second & third \crlli + seven & eight & nine \crli}} +\bigskip + +The \^`\vspan``<number>{<text>}` shifts the <text> down in order it looks +like to be in the center of the <number> lines (current line is first). +You can use this for creating tables like in the following example: + +\begtt \typosize[8.7/11] +\thistable{\tabstrut={\vrule height 20pt depth10pt width0pt} + \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt} +\table{|8{c|}}{\crlp{3-8} + \mspan2[c|]{} & \mspan3[c|]{Singular} & \mspan3[c|]{Plural} \crlp{3-8} + \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl + \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} & \mspan3[c|]{X} \crlp{2,6-8} + & Exclusive & \mspan3[c|]{} & \mspan3[c|]{X} \crl + \vspan2{II} & Informal & \mspan3[c|]{X} & \mspan3[c|]{X} \crlp{2-8} + & Formal & \mspan6[c|]{X} \crl + \vspan2{III} & Informal & \vspan2{O} & X & X & \mspan2[c|]{X} &\vspan2{O} \crlp{2,4-7} + & Formal & & \mspan4[c|]{X} & \crl +} +\endtt + +\puttext 8.9cm -4cm {\pdfsave\pdfscale{.5}{.5}\rlap{% +\thistable{\tabstrut={\vrule height 20pt depth10pt width0pt} + \baselineskip=20pt \tablinespace=0pt \rulewidth=.8pt} +\table{|8{c|}}{\crlp{3-8} + \mspan2[c|]{} &\mspan3[c|]{Singular} &\mspan3[c|]{Plural} \crlp{3-8} + \mspan2[c|]{} & Neuter & Masculine & Feminine & Masculine & Feminine & Neuter \crl + \vspan2{I} & Inclusive & \mspan3[c|]{\vspan2{O}} &\mspan3[c|] X \crlp{2,6-8} + & Exclusive & \mspan3[c|]{} &\mspan3[c|] X \crl + \vspan2{II} & Informal & \mspan3[c|] X &\mspan3[c|] X \crlp{2-8} + & Formal & \mspan6[c|] X \crl + \vspan2{III} & Informal & \vspan2{O} & X & X &\mspan2[c|] X & \vspan2{O} \crlp{2,4-7} + & Formal & &\mspan4[c|] X & \crl +}}\pdfrestore} + +\hangindent=-7.5cm \hangafter=0 +You can use \^`\vspan` with non-integer parameter too if you feel that the +result looks better, for example \^`\vspan2.1{text}`. + +\hangindent=-7.5cm \hangafter=0 +The rule width of tables and implicit width of all `\vrule`s and `\hrule`s +can be set by the command \^`\rulewidth=<dimen>`. The default value given +by \TeX/ is 0.4\,pt. + +\hangindent=-7.5cm \hangafter=-2 +The `c`, `l`, `r` and `p` are default \"declaration letters" but you can define +more such letters by `\def\_tabdeclare<letter>{<left>##<right>}`. +More about it is in technical documentation in section~\ref[table.impl]. +See the definition of the \^`\_tabdeclarec` macro, for example. + +The `:` columns boundary declarator is described in section~\ref[table.bound]. +The tables with given width can be declared by `to<size>` or `pxto<size>`. +More about it is in section~\ref[table.w]. +Many tips about tables can be seen on the site +\url{http://petr.olsak.net/optex/optex-tricks.html}. + +\label[verbatim]\secc Verbatim +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The display verbatim text have to be surrounded by the \^`\begtt` and +\^`\endtt` couple. +The in-line verbatim have to be tagged (before and after) +by a character which is declared by +\^`\verbchar``<char>`. For example \code{\\verbchar`} +declares the character \code{`} +for in-line verbatim markup. +And you can use \code{`\\relax`} for +verbatim `\relax` (for example). +\new +Another alternative of printing in-line +verbatim text is \~`\code{<text>}` (see below). + +If the numerical register \^`\ttline` is set to the non-negative value then +display verbatim will number the lines. The first line has the number +\^`\ttline+1` and when the verbatim ends then the \^`\ttline` value is equal to the +number of the last line printed. Next \^`\begtt...`\^`\endtt` environment will follow +the line numbering. \OpTeX/ sets \^`\ttline=-1` by default. + +The indentation of each line in display verbatim is controlled by +\^`\ttindent` register. This register is set to the `\parindent` by default. +Users can change the values of the `\parindent` and \^`\ttindent` independently. + +The \^`\begtt` command starts the internal group in which the catcodes are changed. +\new +Then the \^`\everytt` tokens register is run. It is empty by default and the user can +control fine behavior by it. For example, the catcodes can be re-declared here. If +you need to define an active character in the \^`\everytt`, use \~`\adef` as in the +following example: + +\begtt \adef@{\string\endtt} +\everytt={\adef!{?}\adef?{!}} +\begtt +Each occurrence of the exclamation mark will be changed to +the question mark and vice versa. Really? You can try it! +@ +\endtt +% +The \~`\adef` command sets its parameter as active {\it after\/} +the parameter of \^`\everytt` is read. So you don't have to worry about active +categories in this parameter. + +There is an alternative to \^`\everytt` named \^`\everyintt` which is used for +in-line verbatim surrounded by an \^`\verbchar` or processed by the \~`\code` +command. + +The \^`\everytt` is applied to all \^`\begtt...`\^`\endtt` environments (if it is not +declared in a group). There are tips for such global `\everytt` definitions here: + +\begtt \adef!{\char9251 } +\everytt={\typosize[9/11]} % setting font size for verbatim +\everytt={\ttline=0} % each listing will be numbered from one +\everytt={\visiblesp} % visualization!of!spaces +\endtt + +\new +If you want to apply a special code only for one \^`\begtt...`\^`\endtt` +environment then don't set any \^`\everytt` but put desired material at the +same line where \^`\begtt` is. For example: + +\begtt \adef@{\string\endtt} +\begtt \adef!{?}\adef?{!} +Each occurrence of ? will be changed to ! and vice versa. +@ +\endtt + +The in-line verbatim surrounded by a \^`\verbchar` doesn't work in +parameter of macros and macro definitions. (It works in titles declared by +\~`\chap`, \~`\sec` etc. and in \~`\fnote`s, because these macros are +specially defined in \OpTeX/). +\new +You can use more robust command \^`\code{<text>}` in problematic +situations, but you have to escape the following characters in the <text>: +`\`, `#`, `%`, braces (if the braces are unmatched in the <text>), +and space or `^` (if there are more than one subsequent spaces or `^` in +the <text>). Examples: + +\begtt +\code{\\text, \%\#} ... prints \text, %# +\code{@{..}*&^$ $} ... prints @{..}*&^$ $ without escaping, but you can + escape these characters too, if you want. +\code{a \ b} ... two spaces between a b, the second must be escaped +\code{xy\{z} ... xy{z ... unbalanced brace must be escaped +\code{^\^M} ... prints ^^M, the second ^ must be escaped +\endtt + +You can print verbatim listing from external files by the \^`\verbinput` command. +Examples: + +\begtt +\verbinput (12-42) program.c % listing from program.c, only lines 12-42 +\verbinput (-60) program.c % print from begin to the line 60 +\verbinput (61-) program.c % from line 61 to the end +\verbinput (-) program.c % whole file is printed +\verbinput (70+10) program.c % from line 70, only 10 lines printed +\verbinput (+10) program.c % from the last line read, print 10 lines +\verbinput (-5+7) program.c % from the last line read, skip 5, print 7 +\verbinput (+) program.c % from the last line read to the end +\endtt + +\new +You can insert additional commands for \^`\verbinput` before +the first opening bracket. They are processed in the local group. +For example, `\verbinput \hsize=20cm (-) program.c`. + +The \~`\ttline` influences the line numbering by the same way as in +\~`\begtt...`\~`\endtt` environment. If \~`\ttline=-1` then real line numbers are +printed (this is the default). If \code{\\ttline<-1} then no line +numbers are printed. + +The \^`\verbinput` can be controlled by \^`\everytt`, \^`\ttindent` just like +in \~`\begtt...`\~`\endtt`. + +The \~`\begtt`...\~`\endtt` pair or \~`\verbinput` can be used for listings of +codes. Automatic syntax highlighting is possible, for example +`\begtt` \^`\hisyntax{C}` activates colors for C programs. Or +`\verbinput` \^`\hisyntax{HTML} (-) file.html` can be used for HTML or XML codes. +\OpTeX/ implements C, Python, \TeX/, HTML and XML syntax highlighting. +More languages can be declared, see the section~\ref[hisyntax]. + +If the code is read by \^`\verbinput` and there are comment lines prefixed +by two characters then +you can set them by \~`\commentchars``<first><second>`. Such comments are +fully interpreted by \TeX/ (i.e. not verbatim). +Section~\ref[verb] (page \pgref[commentchars]) says more about this feature. + +\sec Autogenerated lists +%%%%%%%%%%%%%%%%%%%%%%%% + +\secc[toc] Table of contents +%%%%%%%%%%%%%%%%%%%%%% + +The \^`\maketoc` command prints the table of contents of all \~`\chap`, \~`\sec` +and \~`\secc` used in the document. These data are read from the external `*.ref` file, so +you have to run \TeX/ more than once (typically three times if the table of +contents is at the beginning of the document). + +Typically, we don't want to repeat the name of the section \"Table of contents" +in the table of contents again. The direct usage +of \~`\chap` or \~`\sec` isn't recommended here because the table of contents +is typically not referenced to itself. You can print the unnumbered and unreferenced +title of the section like this: + +\begtt +\nonum\notoc\sec Table of Contents +\endtt +If you need a customization of the design of the TOC, read the +section~\ref[maketoc]. + +\new +If you are using a special macro in section or chapter titles +and you need different behavior of such macro in other cases then use +\^`\regmacro{<case-toc>}{<case-mark>}{<case-outline>}`. +The parameters are applied locally in given cases. The \^`\regmacro` can be +used repeatedly: then its parameters are accumulated (for more macros). +If a parameter is empty then original definition is used in given case. +For example: + +\begtt +% default value of \mylogo macro used in text and in the titles: +\def\mylogo{\leavevmode\hbox{{\Red\it My}{\setfontsize{mag1.5}\rm Lo}Go}} +% another variants: +\regmacro {\def\mylogo{\hbox{\Red My\Black LoGo}}} % used in TOC + {\def\mylogo{\hbox{{\it My}\/LoGo}}} % used in running heads + {\def\mylogo{MyLoGo}} % used in PDF outlines +\endtt + +\secc Making the index +%%%%%%%%%%%%%%%%%%%%% + +The index can be included in the document by the \^`\makeindex` macro. No external +program is needed, the alphabetical sorting is done inside \TeX/ at macro +level. + +The \^`\ii` command (insert to index) declares the word separated by the space +as the index item. This declaration is represented as an invisible item on the +page connected to the next visible word. The page number of the page where +this item occurs is listed in the index entry. So you can type: + +\begtt +The \ii resistor resistor is a passive electrical component ... +\endtt + +You cannot double the word if you use the \^`\iid` instead of \^`\ii`: + +\begtt +The \iid resistor is a passive electrical component ... +or: +Now we'll deal with the \iid resistor . +\endtt + +Note that the dot or comma has to be separated by space when \^`\iid` is +used. This space (before dot or comma) is removed by the macro in +the current text. + +The multiple-words entries are commonly arranged in the index as follows: + +\medskip + +linear~dependency 11, 40--50 + +--- independency 12, 42--53 + +--- space 57, 76 + +--- subspace 58 + +\medskip + +To do this you have to declare the parts of the index entries by the `/` separator. +Example: + +\begtt +{\bf Definition.} +\ii linear/space,vector/space +{\em Linear space} (or {\em vector space}) is a nonempty set of... +\endtt + +The number of the parts of one index entry (separated by `/`) is unlimited. Note, that you can +spare your typing by the comma in the \~`\ii` parameter. The previous example +is equivalent to `\ii linear/space \ii vector/space`~. + +Maybe you need to propagate to the index the similar entry to the +linear/space in the form of space/linear. You can do this by the shorthand `,@` +at the end of the \~`\ii` parameter. Example: + +\begtt +\ii linear/space,vector/space,@ +is equivalent to: +\ii linear/space,vector/space \ii space/linear,space/vector +\endtt + +If you really need to insert the space into the index entry, write `~`. + +The \~`\ii` or \~`\iid` commands can be preceded by \^`\iitype` `<letter>`, then such +reference (or more references generated by one \~`\ii`) has the specified type. +The page numbers of such references should be formatted +specially in the index. \OpTeX/ implements only \^`\iitype` `b`, +\^`\iitype` `i` and \^`\iitype` `u`: +the page number in bold or in italics or underlined is printed +in the index when these types are used. The default index type is empty, which +prints page numbers in normal font. The \TeX/book index is a good example. + +The \^`\makeindex` creates the list of alphabetically sorted index entries +without the title of the section and without creating more columns. \OpTeX/ +provides other macros \^`\begmulti` and \^`\endmulti` for more columns: + +\begtt \catcode`\<=13 +\begmulti <number of columns> +<text> +\endmulti +\endtt +The columns will be balanced. The Index can be printed by the following +code: + +\begtt +\sec Index +\begmulti 3 \makeindex \endmulti +\endtt + +Only \"pure words" can be propagated to the index by the \~`\ii` command. It +means that there cannot be any macro, \TeX/ primitive, math selector, etc. +But there is another possibility to create such a complex index entry. Use +\"pure equivalent" in the \~`\ii` parameter and map this equivalent to a +real word that is printed in the index. Such mapping is done by +\^`\iis` command. Example: + +\begtt +The \ii chiquadrat $\chi$-quadrat method is ... +If the \ii relax `\relax` command is used then \TeX/ is relaxing. +... +\iis chiquadrat {$\chi$-quadrat} +\iis relax {\code{\\relax}} +\endtt +% +The \^`\iis` `<equivalent> {<text>}` creates one entry in the \"dictionary +of the exceptions". The sorting is done by the <equivalent> but the +<text> is printed in the index entry list. + +The sorting rules when \^`\makeindex` runs depends on the current language. +See section~\ref[lang] about languages selection. + +\secc Bib\TeX/ing +%%%%%%%%%%%%%%%% + +The command \^`\cite[<label>]` (or +\hbox{\^`\cite[<label-1>,<label-2>,...,<label-n>]`}) +creates the citation in the form [42] (or [15,~19,~26]). +If \^`\shortcitations` is declared at the beginning of the document then +continuous sequences of numbers are re-printed like this: +\hbox{[3--5,~7,~9--11]}. If +\^`\sortcitations` is declared then numbers generated by one \^`\cite` command +are sorted upward. + +If \^`\nonumcitations` is declared then the marks instead of numbers are generated +depending on the used bib-style. For example, the citations look like +[Now08] or [Nowak, 2008]. + +The \^`\rcite[<labels>]` creates the same list as \^`\cite[<labels>]` but without +the outer brackets. Example: `[\rcite[tbn], pg.~13]` creates [4,~pg.~13]. + +The \^`\ecite[<label>]{<text>}` prints the `<text>` only, but the entry labeled +<label> is decided as to be cited. If \~`\hyperlinks` is used then <text> +is linked to the references list. + +You can define alternative formating of \^`\cite` command. Example: + +\begtt \catcode`\<=13 +\def\cite[#1]{(\rcite[#1])} % \cite[<label>] creates (27) +\def\cite[#1]{$^{\rcite[#1]}$} % \cite[<label>] creates^{27} +\endtt + +The numbers printed by \^`\cite` correspond to the same numbers generated in +the list of references. There are two possibilities to generate this +references list: + +\begitems +* Manually using \~`\bib[<label>]` commands. +* By \~`\usebib/<type> (<style>) <bib-base>` command which reads `*.bib` + files directly. +\enditems + +\new +Note that another two possibilities documented in OPmac (using external +Bib\TeX/ program) isn't supported because Bib\TeX/ is an old program that does not +support Unicode. And Biber seems to be not compliant with Plain \TeX. + +\medskip\noindent +{\bf References created manually using \^`\bib[<label>]` command.} + +\begtt +\bib [tbn] P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 1997. +\bib [tst] P. Olšák. {\it Typografický systém \TeX.} + 269~s. Praha: CSTUG, 1995. +\endtt + +If you are using \~`\nonumcitations` then you need to declare the <marks> +used by \~`\cite` command. To do it you must use long form of the \^`\bib` +command in the format \^`\bib[<label>] = {<mark>}`. The spaces around +equal sign are mandatory. Example: + +\begtt +\bib [tbn] = {Olšák, 2001} + P. Olšák. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 2001. +\endtt + +\noindent +{\bf Direct reading of `.bib` files} is possible by \^`\usebib` macro. +This macro reads and uses macro package `librarian.tex` by Paul Isambert. +The usage is: + +\begtt \catcode`\<=13 +\usebib/c (<style>) <bib-base> % sorted by \cite-order (c=cite), +\usebib/s (<style>) <bib-base> % sorted by style (s=style). +% example: +\nocite[*] \usebib/s (simple) op-biblist % prints all from op-biblist.bib +\endtt + +The <bib-base> is one or more `*.bib` database source files (separated by +spaces and without extension) and the <style> is the part of the filename +`bib-<style>.opm` where the formatting of the references list is +defined. \OpTeX/ supports `simple` or `iso690` styles. The features of +the `iso690` style is documented in the section~\ref[isobib] in detail. +The \^`\usebib` command is more documented in section~\ref[usebib]. + +Not all records are printed from <bib-base> files: the command \^`\usebib` +selects only such bib-records which were used in \~`\cite` or \^`\nocite` +commands in your document. The \^`\nocite` behaves as \~`\cite` but prints +nothing. It tells only that the mentioned bib-record should be printed in the +reference list. If \^`\nocite[*]` is used then all records from <bib-base> +are printed. + +\sec Graphics +%%%%%%%%%%%%% + +\secc Colors +%%%%%%%%%%% + +\OpTeX/ provides a small number of color selectors: +{\Blue `\Blue`}, +{\Red `\Red`}, +{\Brown `\Brown`}, +{\Green `\Green`}, +{\Yellow `\Yellow`}, +{\Cyan `\Cyan`}, +{\Magenta `\Magenta`}, +{`\White`}, +{\Grey `\Grey`}, +{\LightGrey `\LightGrey`} and +`\Black`. User can define more +such selectors by setting four CMYK components +\new +or three RGB components. For example + +\begtt +\def \Orange {\setcmykcolor{0 0.5 1 0}} +\def \Purple {\setrgbcolor{1 0 1}} +\endtt + +\new +The command \^`\morecolors` reads more definitions of color selectors from +the \LaTeX/ file `x11nam.def`. +There are about 300 color names like +`\DeepPink`, `\Chocolate` etc. If there are numbered variants of the same +name, then the letters B, C, etc. are appended to the name in \OpTeX/. For example +`\Chocolate` is Chocolate1, `\ChocolateB` is Chocolate2 etc. + +\new +The color selectors work locally in groups by default but with limitations. See +the technical documentation, section~\ref[colors] for more information. + +The basic colors \^`\Blue`, \^`\Red`, \^`\Cyan`, \^`\Yellow` etc.\ are defined +with CMYK components using \^`\setcmykcolor`. +On the other hand, you can define a color with three +RGB components and \^`\morecolors` defines such RGB colors. +By default, the color model isn't converted but only stored to +PDF output for each used color. Thus, there may be a mix of color +models in the PDF output which is not a good idea. You can overcome this +problem by declaration \^`\onlyrgb` or \^`\onlycmyk`. Then only the selected color +model is used for PDF output and if a used color is declared by another color +model then it is converted. +The \^`\onlyrgb` creates colors more bright (usable for computer +presentations). On the other hand, CMYK makes colors more true\fnote +{Printed output is more equal to the monitor preview especially if you are +using ICC profile for your printer.} +for printing. + +\new +You can define your color by a linear combination of previously defined colors using +\^`\colordef`. For example: + +\begtt +\colordef \myCyan {.3\Green + .5\Blue} % 30 % green, 50 % blue, 20% white +\colordef \DarkBlue {\Blue + .4\Black} % Blue mixed with 40 % of black +\colordef \myGreen{\Cyan+\Yellow} % exact the same as \Green +\colordef \MyColor {.3\Orange+.5\Green+.2\Yellow} +\endtt +% +The linear combination is done in CMYK subtractive color space by default +(RGB colors used in \^`\colordef` argument are converted first). +If the resulting component is greater than 1 then it is truncated to 1. +If a convex linear combination (as in the last example above) is used then it +emulates color behavior on a painter's palette. +You can use \^`\rgbcolordef` instead of \^`\colordef` if you want to mix colors +in the additive RGB color space. + +\def\coloron#1#2#3{% + \setbox0=\hbox{{#2#3}}\leavevmode + \localcolor \rlap{#1\strut \vrule width\wd0}\box0 +} +The following example defines the macro for the +\coloron\Yellow\Brown{colored text on the colored background}. Usage: +`\coloron<background><foreground>{<text>}` + +The `\coloron` can be defined as follows: + +\begtt +\def\coloron#1#2#3{% + \setbox0=\hbox{{#2#3}}% + \leavevmode \rlap{#1\strut \vrule width\wd0}\box0 +} +\coloron\Yellow\Brown{The brown text on the yellow background} +\endtt + +\secc Images +%%%%%%%%%%% + +The \^`\inspic` `{<filename>.<extension>}` or +\^`\inspic` `<filename>.<extension><space>` +inserts the picture stored in +the graphics file with the name `<filename>.<extension>` to the document. +You can set the picture width by \^`\picw=<dimen>` +before \^`\inspic` command which declares the width of the picture. +The image files can be in the PNG, JPG, JBIG2 or PDF format. + +The \^`\picwidth` is an equivalent register to `\picw`. Moreover, there is an +\^`\picheight` register which denotes the height of the picture. If both +registers are set then the picture will be (probably) deformed. + +The image files are searched in \^`\picdir`. This token list is empty +by default, this means that the image files are searched in the +current directory. Example: \^`\picdir={img/}` supposes that image files are +in `img` subdirectory. Note: the directory name must end by `/` in +the \^`\picdir` declaration. + +Inkscape\fnote +{A powerful and free Wysiwyg editor for creating vector graphics.} +is able to save a picture to PDF and labels of the picture to another +file\fnote +{Chose \"Omit text in PDF and create LaTeX file" option.}. +This second file should be read by \TeX/to print labels +in the same font as document font. \OpTeX/ supports this feature by +\^`\inkinspic` `{<filename>.pdf}` command. It reads and displays +both: PDF image and labels generated by Inkscape. + +If you want to create vector graphics (diagrams, schema, geometry +skicing) then you can do it by Wysiwyg graphics editor (Inkscape, Geogebra for +example), export the result to PDF and include it by \^`\inspic`. +If you want to \"program" such pictures then Tikz package is recommended. +It works in Plain \TeX/ and \OpTeX. + +\secc PDF transformations +%%%%%%%%%%%%%%%%%%%%%%%% + +All typesetting elements are transformed by linear +transformation given by the current transformation matrix. The +`\pdfsetmatrix` `{<a> <b> <c> <d>}` command makes the internal multiplication +with the current matrix so linear transformations can be composed. +One linear transformation given by the `\pdfsetmatrix` above transforms +the vector $[0,1]$ to [<a>,\,<b>] and $[1,0]$ to [<c>,\,<d>]. +The stack-oriented commands `\pdfsave` and `\pdfrestore` gives a possibility of +storing and restoring the current transformation matrix and the position of the current point. +This position has to be the same from \TeX{}'s point of +view as from the transformation point of view when `\pdfrestore` is processed. +Due to this fact the `\pdfsave\rlap{<transformed text>}\pdfrestore` +or something similar is recommended. + +\OpTeX/ provides two special transformation macros +\^`\pdfscale` and \^`\pdfrotate`: + +\begtt \catcode`\<=13 +\pdfscale{<horizontal-factor>}{<vertical-factor>} +\pdfrotate{<angle-in-degrees>} +\endtt + +These macros simply call the properly `\pdfsetmatrix` command. + +It is known that the composition of transformations is not commutative. It +means that the order is important. You have to read the transformation +matrices from right to left. Example: + +\begtt +First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore + % text1 is scaled two times and it is reflected about vertical axis + % and next it is rotated by 30 degrees left. +second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore + % text2 is rotated by 30 degrees left then it is scaled two times + % and reflected about vertical axis. +third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}% + \pdfrestore % first slanted, then rotated by 15.3 degrees right +\endtt +% +\par\nobreak\bigskip\smallskip +This gives the following result. +First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore +second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore +third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}\pdfrestore +\par\nobreak\bigskip\penalty0%\bigskip + +You can see that \TeX/ knows nothing about dimensions of transformed material, +it treats it as with a zero dimension object. +\new +The \^`\transformbox{<transformation>}{<text>}` +macro solves the problem. This macro puts the transformed +material into a box with relevant dimensions. The <transfromation> parameter +includes one or more transformation commands `\pdfsetmatrix`, `\pdfscale`, +`\pdfrotate` with their parameters. The <text> is transformed text. + +Example: \~`\frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}` +creates \frame{\transformbox{\pdfscale{1}{1.5}\pdfrotate{-10}}{moj}}. + +The \^`\rotbox{<deg>}{<text>}` is shortcut for +\^`\transformbox{\pdfrotate{<deg>}}{<text>}`. + +\secc Ovals, circles +%%%%%%%%%%%%%%%%%%%% + +\new +The \^`\inoval{<text>}` creates a box like this: \inoval{text}. +Multiline text can be put in an oval by the command \^`\inoval{\vbox{<text>}}`. +Local settings can be set by +\^`\inoval[<settings>]{<text>}` or you can re-declare global settings by +\^`\ovalparams={<settings>}`. The default settings are: + +\begtt +\ovalparams={\roundness=2pt % diameter of circles in the corners + \fcolor=\Yellow % color used for filling oval + \lcolor=\Red % line color used in the border + \lwidth=0.5bp % line width in the border + \shadow=N % use a shadow effect + \overlapmargins=N % ignore margins by surrounding text + \hhkern=0pt \vvkern=0pt} % left-righ margin, top-bottom margin +\endtt +The total distance from text to oval boundary is `\hhkern+\roundness` at the left and right +sides and +`\vvkern+\roundness` at the top and bottom sides of the text. + +If you need to set a parameters for the <text> (color, size, font etc.), +put such setting right in front of the <text>: +\^`\inoval{<text settings><text>}`. + +\new +The \^`\incircle[\ratio=1.8]{<text>}` creates a box like this \incircle[\ratio=1.8]{text}. +The \^`\ratio` parameter means width/height. The usage is analogical like for oval. +The default parameters are + +\begtt +\circleparams={\ratio=1 \fcolor=\Yellow \lcolor=\Red \lwidth=0.5bp + \shadow=N \ignoremargins=N \hhkern=2pt \vvkern=2pt} +\endtt + +\new +The macros \^`\clipinoval` `<x> <y> <width> <height> {<text>}` +and \^`\clipincircle` (with the same parameters) +print the `<text>` when a clipping path (oval or cirle with given +`<with>` and `<height>` shifted its center by `<x>` to right and by `<y>` to up) +is used. +The `\roundness=5mm` is default for \^`\clipinoval` and user can change it. +Example: + +\begtt +\clipincircle 3cm 3.5cm 6cm 7cm {\picw=6cm \inspic{myphoto.jpg}} +\endtt + +\secc Putting images and texts wherever + +\new +The \^`\puttext` `<x> <y> {<text>}` puts the `<text>` shifted by `<x>` right and by +`<y>` up from the current point of typesetting and does not change the +position of the current point. Assume a coordinate system with origin in the +current point. Then \^`\puttext` `<x> <y> {<text>}` puts the text at the +coordinates `<x>`, `<y>`. More exactly the left edge of its baseline is at that +position. + +\new +The \^`\putpic` `<x> <y> <width> <height> {<image-file>}` puts an image +given by `<image-file>` (including extension) of given +`<width>` and `<height>` at given position (its left-bottom corner). +You can write \^`\nospec` instead `<width>` or `<height>` if this parameter +is not specified. + +\sec Others +%%%%%%%%%%% + +\secc[lang] Using more languages +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\OpTeX/ prepares hyphenation patterns for all languages if such patterns are +available in your \TeX/ system. +\new +Only USenglish patterns (original from Plain \TeX/) are preloaded. +Hyphenation patterns of all other languages are loaded on demand when you first use +the `\<iso-code>lang` command in your document. +For example \^`\delang` for German, \^`\cslang` for +Czech, \^`\pllang` for Polish. The <iso-code> is a shortcut +of the language (mostly from ISO 639-1). +You can list all available languages by \^`\langlist` +macro. This macro prints now: + +\medskip +{\typosize[8.5/11.5]\emergencystretch=4em \hbadness=4000 +\noindent \langlist +\par} +\medskip + +\new +For compatibility with e-plain macros, there is the command +\^`\uselanguage{<language>}`. The parameter <language> is long-form of +language name, i.e.\ \^`\uselanguage{Czech}` works the same as \^`\cslang`. +The \^`\uselanguage` parameter is case insensitive. + +For compatibility with \csplain/, there are macros \^`\ehyph`, \^`\chyph`, +\^`\shyph` which are equivalent to \^`\enlang`, \^`\cslang` and \^`\sklang`. + +You can switch between language patterns by `\<iso-code>lang` commands mentioned +above. Default is \^`\enlang`. + +\OpTeX/ generates three phrases used for captions and titles in technical +articles or books: \"Chapter", \"Table" and \"Figure". These phrases need to be known +in used language and it depends on the previously used language selectors +`\<iso-code>lang`. \OpTeX/ declares these words only for few languages: +\new +Czech, German, Spanish, French, Greek, Italian, Polish, Russian, Slovak and +English, If you need to use these words in other languages or you want to +auto-generate more words in your macros, then you can declare it by +\~`\sdef` or \^`\_langw` commands as shown in section~\ref[langphrases]. + +The \~`\makeindex` command needs to know the sorting rules used in your language. +\OpTeX/ defines only a few language rules for sorting: Czech, +Slovak and English. How to declare sorting rules for more languages are +described in the section~\ref[makeindex]. + +If you declare `\<iso-code>quotes`, then the control sequences `\"` and `\'` +should be used like this: `\"<quoted text>"` or `\'<quoted text>'` +(note that the terminating character is the same but it isn't escaped). +This prints language-dependent normal or alternative quotes around +<quoted text>. The language is specified by <iso-code>. \OpTeX/ declares +quotes only for Czech, German, Spanish, French, Greek, Italian, Polish, +Russian, Slovak and English (\^`\csquotes`, \^`\dequotes`, \dots, \^`\enquotes`). +You can simply define your own quotes as shown in section~\ref[langphrases]. +The `\"` is used for quotes visually more similar to the `"` character which +can be primary quotes or secondary quotes depending on the language rules. +Maybe you want to alternate the meaning of these two types of quotes. Use +`\<isocode>quotes\altquotes` in such case. + +\secc[styles] Pre-defined styles +%%%%%%%%%%%%%%%%%%%%%%% + +\OpTeX/ defines three style-declaration macros \~`\report`, \~`\letter` and +\~`\slides`. You can use them at the beginning of your document if you are +preparing these types of documents and you don't need to create your own +macros. + +The \^`\report` declaration is intended to create reports. It +sets default font size to 11\,pt and `\parindent` (paragraph indentation) to 1.2\,em. +The `\tit` macro uses smaller font because we assume that \"chapter level" +will be not used in reports. The first page has no page number, but the next pages +are numbered (from number~2). Footnotes are numbered from one in the whole +document. The macro `\author <authors><end-line>` can be used when +\^`\report` is declared. It prints `<authors>` in italics at the center of the +line. You can separate authors by `\nl` to more lines. + +The \^`\letter` declaration is intended to create letters. +See the files `op-letter-*.tex` for examples. +The \^`\letter` style sets default +font size to 11\,pt and `\parindent` to 0\,pt. It sets half-line space +between paragraphs. The page numbers are not printed. The \^`\subject` macro +can be used, it prints the word \"Subject:" or \"Věc" (or something else +depending on current language) in bold. Moreover, the \^`\address` macro +can be used when \^`\letter` is declared. The usage of the \^`\address` macro +looks like: + +\begtt \catcode`\<=13 +\address + <first line of address> + <second line of address> + <etc.> + <empty line> +\endtt + +It means that you need not use any special mark at the end of lines: the ends +of lines in the source file are the same as in printed output. The +\^`\address` macro creates `\vtop` with address lines. The width of such +`\vtop` is equal to the widest line used in it. So, you can use +`\hfill\address...` to put the address box to the right side of the +document. Or you can use `<prefixed text>\address...` to put +`<prefixed text>` before the first line of the address. + +The \^`\slides` style creates a simple presentation slides. See an example +in the file `op-slides.tex`. Run `optex op-slides.tex` and see the documentation of +\^`\slides` style in the file `op-slides.pdf`. + +Analogical declaration macro `\book` is not prepared. Each book needs +individual typographical care. You need to create specific macros for +design. + +\secc Loading other macro packages +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +You can load more macro packages by `\input{<file-name>}` or by +\^`\load[<file-names>]`. The first case (`\input`) is \TeX/ primitive command, it can be +used in the alternative old syntax `\input <filename><space>` too. The +second case (\^`\load`) allows specifying a comma-separated list of included files. +Moreover, it loads each macro file only once, it sets +temporarily standard category codes during loading and it tries to +load `<filename>.opm` or `<filename>.tex` or `<filename>`, the first occurence +wins. Example: +\begtt +\load [qrcode, tikz] +\endtt +% +does `\input qrcode.opm` \,and `\input tikz.tex` \,and it saves +local information about the fact that these file names +`qrcode` and `tikz` were already used, i.\,e. next \^`\load` will skip them. + +It is strongly recommended to use the `\load` macro for loading external +macros if you need them. On the other hand, if your source document is structured +to more files (with individual chapters or sections), use simply the `\input` primitive. + +The macro packages intended to \OpTeX/ have the name `*.opm`. +The following packages are distributed as part of \OpTeX/: +\begitems +* `qrcode.opm` enables to create QR codes. +* `vlna.opm` enables to protect of one-letter prepositions and more things automatically. +* `emoji.opm` defines `\emoji{<name>}` command for colored emoticons. +* `plain-at.opm` defines the old names from plain \TeX/. +\enditems +See the directory `optex/pkg/` and these files for more information about +them. + +\secc Lorem ipsum dolor sit +%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\new +A designer needs to concentrate on the design of the output and maybe he/she +needs material for testing macros. There is the possibility to generate a +neutral text for such experiments. Use \^`\lorem[<number>]` or +\^`\lorem[<from>-<to>]`. It prints a paragraph (or paragraphs) with neutral +text. The numbers <number> or <from>, <to> must be in the range 1 to 150 +because there are 150 paragraphs with neutral text prepared for you. +The \^`\lipsum` macro is equivalent to \^`\lorem`. Example: \^`\lipsum[1-150]` +prints all prepared paragraphs. + +\secc Logos +%%%%%%%%%% + +\new +The control sequences for typical logos can be terminated by optional `/` +which is ignored when printing. This makes logos more legible in the source file: + +\begtt +We are using \TeX/ because it is cool. \OpTeX/ is better than \LaTeX. +\endtt + +\secc The last page +%%%%%%%%%%%%%%%%%%% + +The number of the last page (it may be different from the number of pages) is +expanded by \^`\lastpage` macro. It expands to `?` in first \TeX/ run and to +the last page in next \TeX/ runs. + +There is an example for footlines in the format \"current page / last page": + +\begtt +\footline={\hss \fixedrm \folio/\lastpage \hss} +\endtt + +\new +The \^`\lastpage` expands to the last \^`\folio` which is a decimal +number or Roman numeral (when \^`\pageno` is negative). If you need to know +the total pages used in the document, use \^`\totalpages` macro. It expands to +zero (in first \TeX/ run) or to the number of all pages in the document +(in next \TeX/ runs). + +\secc Use \OpTeX/ +%%%%%%%%%%%%%%%%% + +\new +The command \^`\useOpTeX` (or \^`\useoptex`) does nothing in \OpTeX/ but it causes +an error (undefined control sequence) when another format is used. You can +put it as the first command in your document: + +\begtt +\useOpTeX % we are using OpTeX format, no LaTeX :) +\endtt + +\sec Summary +%%%%%%%%%%%% + +\def\ttref#1'{\ea\~\ea`\csname#1\endcsname`} + +\begtt \typosize[9/11]\adef&{\kern.25em}\adef~#1'{\ea\~\ea`\csname#1\endcsname`} +~tit' Title (terminated by end of line) +~chap' Chapter Title (terminated by end of line) +~sec' Section Title (terminated by end of line) +~secc' Subsection Title (terminated by end of line) + +~maketoc' % table of contents generation +~ii' item1,item2 % insertion the items to the index +~makeindex' % the index is generated + +~label' [labname] % link target location +~ref' [labname] % link to the chapter, section, subsection, equation +~pgref' [labname] % link to the page of the chapter, section, ... + +~caption'/t % a numbered table caption +~caption'/f % a numbered caption for the picture +~eqmark' % a numbered equation + +~begitems' % start a list of the items +~enditems' % end of list of the items +~begblock' % start a block of text +~endblock' % end of block of text +~begtt' % start a verbatim text +~endtt' % end verbatim text +~verbchar' X % initialization character X for in-text verbatim +~code' % another alternative for in-text verbatim +~verbinput' % verbatim extract from the external file +~begmulti' num % start multicolumn text (num columns) +~endmulti' % end multicolumn text + +~cite' [labnames] % refers to the item in the lits of references +~rcite' [labnames] % similar to \cite but [] are not printed. +~sortcitations' ~shortcitations' ~nonumcitations' % cite format +~bib' [labname] % an item in the list of references +~usebib'/? (style) bib-base % direct using of .bib file, ? in {s,c} + +~load' [filenames] % loadaing macro files +~fontfam' [FamilyName] % selection of font family +~typosize' [font-size/baselineskip] % size setting of typesetting +~typoscale' [factor-font/factor-baselineskip] % size scaling +~thefontsize' [size] ~thefontscale' [factor] % current font size + +~inspic' file.ext % insert a picture, extensions: jpg, png, pdf +~table' {rule}{data} % macro for the tables like in LaTeX + +~fnote' {text} % footnote (local numbering on each page) +~mnote' {text} % note in the margin (left or right by page number) + +~hyperlinks' {color-in}{color-out} % PDF links activate as clickable +~outlines' {level} % PDF will have a table of contents in the left tab + +~magscale'[factor] % resize typesetting, line/page breaking unchanged +~margins'/pg format (left, right, top, bottom)unit % margins setting + +~report' ~letter' ~slides' % style declaration macros +\endtt + +\sec API for macro writers +%%%%%%%%%%%%%%%%%%%%%%%%%% + +All \TeX/ primitives and almost all \OpTeX/ macros are accesible by two +names: `\foo` (public or user name space) and `\_foo` (private name space). +For example `\hbox` and `\_hbox` means the same \TeX/ primitive. More about +it is documented in section~\ref[prefixed]. + +If this manual refers `\foo` then `\_foo` equivalent exists too. For example, +we mention the `\addto` macro below. The `\_addto` equivalent exists too, but it +is not explicitly mentioned here. If we refer only `\_foo` then its public +equivalent does not exist. For example, we mention the `\_codedecl` macro below, so +this macro is not available as `\codedecl`. + +If you are writing a document or macros specific for the document, then use +simply user namespace (`\foo`). If you are writing more general macros, +then use private namespace (`\_foo`), but you should declare your own namespace +by \~`\_namespace` macro and you have to follow the naming discipline described in +section~\ref[pkg-namespace]. + +The alphabetically sorted list of macros typically usable for macro writers follows. +More information about such macros can be found in the technical documentation. +You can use hyperlinks here in order to go to the appropriate place of the technical +documentation. + +\medskip \noindent +\^`\addto`` \macro{<text>}` adds <text> at the end of `\macro` body.\nl +\^`\adef` `<char>{<body>}` defines <char> active character with meaning <body>.\nl +\^`\afterfi` `{<text>}<ignored>\fi` expands to `\fi<text>`.\nl +\^`\bp`` {<dimen expression>}` expands \TeX/ dimension to decimal number in `bp` without unit.\nl +\~`\_codedecl`` <sequence> {<info>}` is used at beginning of macro files.\nl +\~`\colordef`` \macro {<mix of colors>}` declares `\macro` as color switch.\nl +\^`\cs` `{<string>}` expands `\<string>`.\nl +\~`\_doc` `...` \~`\_cod` encloses documenation text in the macro code.\nl +\^`\eoldef`` \macro #1{<body>}` defines `\macro` with parameter separated to end of line.\nl +\~`\_endcode` closes the part of macro code in macro files.\nl +\~`\_endnamespace` closes name space declared by \~`\_namespace`.\nl +\~`\eqbox`` [<label>]{<text>}` creates `\hbox{<text>}` with common width across whole document.\nl +\^`\expr`` {<expression>}` expands to result of the <expression> with decimal numbers.\nl +\~`\fontdef`` \f {<font spec.>}` declares `\f` as font switch.\nl +\~`\fontlet` `\fa=\fb <sizespec.>` declares `\fa` as the same font switch + like `\fb` at given <sizespec.>.\nl +\^`\foreach` `<list>\do <parameters>{<what>}` is exapandable loop over <list>.\nl +\^`\foreachdef` `\macro <parameters>{<what>}` declares expandable `\macro` as loop over <list>.\nl +\^`\fornum` `<from>..<to>\do {<what>}` is expanadable loop with numeric variable.\nl +\^`\incr` `<counter>` increases and \^`\decr` `<counter>` decreases `<counter>` by one globally.\nl +\^`\ignoreit` `<one>`, \^`\ignoresecond` `<one><two>` ignores given parameter.\nl +`\expandafter` \^`\ignorept` `\the<dimen>` expands to decimal number <dimen> without `pt`.\nl +\~`\isempty`, \~`\istoksempty`, \~`\isequal`, \~`\ismacro`, \~`\isdefined`, \~`\isinlist` +\~`\isfile`, \~`\isfont` do various tests. Example: \~`\isinlist\list{<text>}\iftrue` does + `\iftrue` if <text> is in `\list`.\nl +\^`\isnextchar`` <char>{<text1>}{<text2>}` performs <text1> if next + character is <char>, else <text2>.\nl +\~`\kv` `{<key>}` expands to value when key-value parameters are used.\nl +\^`\loop` `...` \^`\repeat` is classical Plain \TeX/ loop.\nl +\^`\mathstyles`` {<math list>}` enables to create macros dependent on current math style.\nl +\~`\_namespace`` {<pkg>}` declares name space used by package writers.\nl +\^`\newcount`, \^`\newdimen` etc. are classical Plain \TeX/ allocators.\nl +\^`\newif` `\iffoo` declares boolean `\iffoo` as in Plain \TeX/.\nl +\^`\_newifi` `\_iffoo` declares boolean `\_iffoo`.\nl +\^`\opinput`` {<filename>}` reads file like `\input` but with standard catcodes.\nl +\^`\optdef`` \macro [<opt-default>] <parameters>{<body>}` defines `\macro` with [opt.parameter].\nl +\^`\opwarning` `{<text>}` prints <text> to the terminal and .log file as warning.\nl +\~`\private`` <sequence> <sequence> ... ;` declares <sequence>s for private name space.\nl +\~`\public`` <sequence> <sequence> ... ;` declares <sequence>s for public name space.\nl +\~`\readkv` `\macro` reads parameters from `\macro` in key-value format.\nl +\^`\replstring`` \macro{<stringA>}{<stringB>}` replaces all <stringA> to <stringB> in `\macro`.\nl +\^`\sdef` `{<string>}<parameters>{<body>}` behaves like `\def\<string><parameters>{<body>}`.\nl +\^`\setctable` and \^`\restorectable` manipulate with stack of catcode tables.\nl +\^`\slet` `{<stringA>}{<stringB>}` behaves like `\let\<stringA>=\<stringB>`\nl +\^`\sxdef` `{<string>}<parameters>{<body>}` behaves like `\xdef\<string><parameters>{<body>}`.\nl +\^`\trycs`` {<string>}{<text>}` expands `\<string>` if it is defined else expands <text>.\nl +\^`\useit` `<one>`, \^`\usesecond` `<one><two>` uses given parameter.\nl +\^`\wlog`` {<text>}` writes <text> to .log file.\nl +\^`\wterm`` {<text>}` writes <text> to the terminal and .log file.\nl +\^`\xargs`` <what> <token> <token> ... ;` repeats <what><token> for each <token>.\nl +\unpenalty\unskip + +\sec Compatibility with Plain \TeX/ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +All macros of Plain \TeX/ are re-written in \OpTeX/. Common macros should +work in the same sense as in original Plain \TeX. Internal control sequences +like `\p@` or `\f@@t` are removed and mostly replaced by control sequences +prefixed by `_` (like `\_this`). If you need to use the basic set of old Plain +\TeX/ control sequences like `\p@` (for example you are reading an old macro file), +use `\load[plain-at]`. + +All primitives and common macros have two +control sequences with the same meaning: in prefixed and unprefixed form. +For example `\hbox` is equal to `\_hbox`. +Internal macros of \OpTeX/ have and use only prefixed form. User should use +unprefixed forms, but prefixed forms are accessible too because the `_` is +set as a letter category code globally (in macro files and users document too). User +should re-define unprefixed forms of control sequences without worries that +something internal will be broken (only the sequence `\par` cannot be +re-defined without change of internal \TeX/ behavior because it is +hard-coded in \TeX/, unfortunately). + +\new +The Latin Modern 8bit fonts instead Computer Modern 7bit fonts are +preloaded in the format, but only a few ones. The full family set is ready to +use after the command \~`\fontfam[LMfonts]` which reads the fonts in OTF +format. + +\new +Plain \TeX/ defines `\newcount`, `\bye` etc. as `\outer` macros. \OpTeX/ +doesn't set any macro as `\outer`. Macros like `\TeX`, `\rm` are defined as +`\protected`. + +\new +The text accents macros `\"`, `\'`, `\v`, `\u`, `\=`, `\^`, `\.`, `\H`, +`\~`, \code{\\`}, `\t` are undefined\fnote +{The math accents macros like `\acute`, `\bar`, `\dot`, `\hat` still work.} +in \OpTeX/. Use real +letters like á, ř, ž in your source document instead of these old accents macros. +If you really want to use them, you can initialize them by the \^`\oldaccents` +command. But we don't recommend it. + +\new +The default paper size is not set as the letter with 1\,in margins but as A4 with +2.5\,cm margins. You can change it, for example by +\^`\margins/1 letter (1,1,1,1)in`. This example sets the classical Plain \TeX/ +page layout. + +\new +The origin for the typographical area is not at the top left 1\,in 1\,in coordinates +but at the top left paper corner exactly. For example, `\hoffset` includes directly left +margin. + +The tabbing macros `\settabs`\iindex{settabs} and `\+` (from Plain \TeX/) +are not defined in \OpTeX/ because they are obsolete. But you can use the +\ulink[http://petr.olsak.net/optex/optex-tricks.html\#tabs]{\OpTeX/ trick 0021} +if you really need such feature. + +The `\sec` macro is reserved for sections but original Plain \TeX/ declares this +control sequence for math secans. + +\enddocument + + +\sec Dependencies +%%%%%%%%%%%%%%%%% + +When `optex.fmt` is created then the following must be installed + +\begitems +* The `\luatex` program. +* Latin moder font metrics + `ec-lmr10.tfm`, `ec-lmbx10.tfm`, `ec-lmri10.tfm`, + `ec-lmbxi10.tfm`, `ec-lmtt10.tfm` (for basic text font initializing). +* Computer rmodern font metrics + `cmr10.tfm`, `cmmi10.tfm`, `cmsy10.tfm`, `cmex10.tfm` (for basic math + initializing). If there are more Computer Modern fonts then they are read + too. +* The file `hyphen.tex` form plain \TeX. +\enditems + +When `\fontfam` is used then the ability of Unicode fonts reading +is initialized using Lua scripts: `ltluatex.lua` (from \LaTeX/ package), +`luaotfload-main.lua` and more 20 similar `.lua` files (from `luaotfload` +package). + +When a font family is needed using `\fontfam` then such font family must be +installed in the OTF format otherwise, the `\fontfam` command is ignored +(only warning about no-existent font family is printed). + +When `\cslang`, `\delang` etc. commands are used in the document +then the hyphenation patterns of relevant languages must be installed. +Moreover the Lua script `luatex-hyphen.lua` (from `hyph-utf8` package) +and data file `language-dat.lua` (from `hyphen-base` package) +must be installed. + +When `\usebib` command is used then `librarian.tex` file +(from the `librarian` macro package) must be installed. + +When `\morecolors` command is used then `x11nam.def` file +(from the `xcolor` package) must be installed. + +When `\lorem` command is used then `lipsum.ltd.tex` file +(from the `lipsum` package) must be installed. + -- cgit v1.2.3