From aeb7b734f147a5da64140d20aabf275f98398d4a Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 14 May 2021 21:30:55 +0000 Subject: optex/base vs. optex/pdfextra git-svn-id: svn://tug.org/texlive/trunk@59201 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/optex/README | 131 -- Master/texmf-dist/doc/optex/base/README | 131 ++ Master/texmf-dist/doc/optex/base/omls.tex | 832 ++++++++ Master/texmf-dist/doc/optex/base/optex-doc.pdf | Bin 0 -> 1405606 bytes Master/texmf-dist/doc/optex/base/optex-doc.tex | 114 ++ Master/texmf-dist/doc/optex/base/optex-math.tex | 1665 ++++++++++++++++ Master/texmf-dist/doc/optex/base/optex-techdoc.tex | 290 +++ Master/texmf-dist/doc/optex/base/optex-userdoc.tex | 2042 ++++++++++++++++++++ Master/texmf-dist/doc/optex/omls.tex | 832 -------- Master/texmf-dist/doc/optex/optex-doc.pdf | Bin 1405606 -> 0 bytes Master/texmf-dist/doc/optex/optex-doc.tex | 114 -- Master/texmf-dist/doc/optex/optex-math.tex | 1665 ---------------- Master/texmf-dist/doc/optex/optex-techdoc.tex | 290 --- Master/texmf-dist/doc/optex/optex-userdoc.tex | 2042 -------------------- Master/texmf-dist/doc/optex/pdfextra/LICENSE | 12 + Master/texmf-dist/doc/optex/pdfextra/README.md | 35 + .../pdfextra/examples/pdfextra-example-part.prc | Bin 0 -> 58592 bytes .../optex/pdfextra/examples/pdfextra-example.pdf | Bin 0 -> 385845 bytes .../optex/pdfextra/examples/pdfextra-example.tex | 341 ++++ .../texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf | Bin 0 -> 230095 bytes .../texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex | 684 +++++++ 21 files changed, 6146 insertions(+), 5074 deletions(-) delete mode 100644 Master/texmf-dist/doc/optex/README create mode 100644 Master/texmf-dist/doc/optex/base/README create mode 100644 Master/texmf-dist/doc/optex/base/omls.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-doc.pdf create mode 100644 Master/texmf-dist/doc/optex/base/optex-doc.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-math.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-techdoc.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-userdoc.tex delete mode 100644 Master/texmf-dist/doc/optex/omls.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-doc.pdf delete mode 100644 Master/texmf-dist/doc/optex/optex-doc.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-math.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-techdoc.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-userdoc.tex create mode 100644 Master/texmf-dist/doc/optex/pdfextra/LICENSE create mode 100644 Master/texmf-dist/doc/optex/pdfextra/README.md create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example-part.prc create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.pdf create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.tex create mode 100644 Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf create mode 100644 Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex (limited to 'Master/texmf-dist/doc/optex') diff --git a/Master/texmf-dist/doc/optex/README b/Master/texmf-dist/doc/optex/README deleted file mode 100644 index d3a5becec45..00000000000 --- a/Master/texmf-dist/doc/optex/README +++ /dev/null @@ -1,131 +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.02> Apr. 2021 - Location CTAN:macros/luatex/optex moved to CTAN:macros/optex (similarly for TDS). - NewComputerModern font support added. - Microtypography support added. - Various colors for links can be declared by \def\_linkolor. - unimath-codes: \nabla math-code set similar as \Delta. - Actual version of UnicodeData.txt read during format generation. - Reading mathclacss.opm improved. - slides: hyperlink destinations allowed in \slideshow mode too. - \bibpart allows to create independent bib-lists in single document. - \setwordspace: format of the parameter improved. -<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/base/README b/Master/texmf-dist/doc/optex/base/README new file mode 100644 index 00000000000..d3a5becec45 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/README @@ -0,0 +1,131 @@ +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.02> Apr. 2021 + Location CTAN:macros/luatex/optex moved to CTAN:macros/optex (similarly for TDS). + NewComputerModern font support added. + Microtypography support added. + Various colors for links can be declared by \def\_linkolor. + unimath-codes: \nabla math-code set similar as \Delta. + Actual version of UnicodeData.txt read during format generation. + Reading mathclacss.opm improved. + slides: hyperlink destinations allowed in \slideshow mode too. + \bibpart allows to create independent bib-lists in single document. + \setwordspace: format of the parameter improved. +<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/base/omls.tex b/Master/texmf-dist/doc/optex/base/omls.tex new file mode 100644 index 00000000000..0f42e4b3c03 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/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 \: \~``.\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><eol>` should be a title of the document. +* \.`\chap <title><eol>` or `\chap [<label>] <title><eof>` is the title of + first level. +* \.`\sec <title><eol>` or `\sec [<label>] <title><eof>` is the title of + second level. +* \.`\secc <title><eol>` or `\secc [<label>] <title><eof>` is the title of + third level. +* \.`\secl<level> <title><eol>` 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/base/optex-doc.pdf b/Master/texmf-dist/doc/optex/base/optex-doc.pdf new file mode 100644 index 00000000000..ba31f2ad238 Binary files /dev/null and b/Master/texmf-dist/doc/optex/base/optex-doc.pdf differ diff --git a/Master/texmf-dist/doc/optex/base/optex-doc.tex b/Master/texmf-dist/doc/optex/base/optex-doc.tex new file mode 100644 index 00000000000..e14d95c2303 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/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.02 + +\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/base/optex-math.tex b/Master/texmf-dist/doc/optex/base/optex-math.tex new file mode 100644 index 00000000000..57afd223346 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/optex-math.tex @@ -0,0 +1,1665 @@ +%% 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 + +More examples of alignments in display math mode (including comparison with +\LaTeX/ code) are shown in the document +\ulink[http://petr.olsak.net/ftp/olsak/optex/op-mathalign.pdf]{op-mathalign.pdf}. + +\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/base/optex-techdoc.tex b/Master/texmf-dist/doc/optex/base/optex-techdoc.tex new file mode 100644 index 00000000000..525fdb94770 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/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 plain \TeX/. + +\verbinput (6-20) optex.ini +% +The \`\optexversion` and \`\fmtname` are defined. + +\verbinput (22-26) optex.ini +% +We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character +is set as `\newlinechar`. + +\verbinput (28-37) 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 (39-43) optex.ini +% +Individual `*.opm` macro files are read. + +\verbinput (45-89) optex.ini +% +The file `optex.lua` is embedded into the format as byte-code. +It is documented in section~\ref[lua]. + +\verbinput (91-94) optex.ini + +The `\everyjob` register is initialized and the format is saved by +the `\dump` command. + +\verbinput (96-104) 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/base/optex-userdoc.tex b/Master/texmf-dist/doc/optex/base/optex-userdoc.tex new file mode 100644 index 00000000000..9bcec7db1e0 --- /dev/null +++ b/Master/texmf-dist/doc/optex/base/optex-userdoc.tex @@ -0,0 +1,2042 @@ +%% 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\#ref:objects] +{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. + +You can create more independent lists of references (you are creating proceedings, +for example). Use \^`\bibpart` `{<name>}` to set the scope where \~`\cite`s +and references list are printed (and interconnected) independent of another +parts of your document. The \~`\cite` labels used in different parts can be +the same and they are not affected. References lists can be created manualy +by \^`\bib` or from a database by `\usebib`. +Example: + +\begtt \typosize[10/12] +\bibpart {AA} +...\cite[labelX] ... \cite[labelY] ... % They belong to AA bib-list +\usebib/c (simple) file.bib % generates AA bib-list numbered 1, 2, ... + % \cite prints [1], [2], ... by bib-list AA +\bibpart {BB} +...\cite[labelZ] ... \cite[labelX] ... % They belong to BB bib-list +\bibnum=0 \usebib/c (simple) my.bib % generates BB bib-list numbered 1, 2, ... + % \cite prints [1], [2], ... by bib-list BB +\endtt +% +By default, \^`\bibpart` is empty. So \~`\cite`s and the references list are conneted +using this empty internal name. + + +\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/omls.tex b/Master/texmf-dist/doc/optex/omls.tex deleted file mode 100644 index 0f42e4b3c03..00000000000 --- a/Master/texmf-dist/doc/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 \: \~`<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><eol>` should be a title of the document. -* \.`\chap <title><eol>` or `\chap [<label>] <title><eof>` is the title of - first level. -* \.`\sec <title><eol>` or `\sec [<label>] <title><eof>` is the title of - second level. -* \.`\secc <title><eol>` or `\secc [<label>] <title><eof>` is the title of - third level. -* \.`\secl<level> <title><eol>` 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 deleted file mode 100644 index ba31f2ad238..00000000000 Binary files a/Master/texmf-dist/doc/optex/optex-doc.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/optex/optex-doc.tex b/Master/texmf-dist/doc/optex/optex-doc.tex deleted file mode 100644 index e14d95c2303..00000000000 --- a/Master/texmf-dist/doc/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.02 - -\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 deleted file mode 100644 index 57afd223346..00000000000 --- a/Master/texmf-dist/doc/optex/optex-math.tex +++ /dev/null @@ -1,1665 +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 - -More examples of alignments in display math mode (including comparison with -\LaTeX/ code) are shown in the document -\ulink[http://petr.olsak.net/ftp/olsak/optex/op-mathalign.pdf]{op-mathalign.pdf}. - -\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 deleted file mode 100644 index 525fdb94770..00000000000 --- a/Master/texmf-dist/doc/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 plain \TeX/. - -\verbinput (6-20) optex.ini -% -The \`\optexversion` and \`\fmtname` are defined. - -\verbinput (22-26) optex.ini -% -We check if \LuaTeX/ engine is used at `-ini` state. And the `^^J` character -is set as `\newlinechar`. - -\verbinput (28-37) 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 (39-43) optex.ini -% -Individual `*.opm` macro files are read. - -\verbinput (45-89) optex.ini -% -The file `optex.lua` is embedded into the format as byte-code. -It is documented in section~\ref[lua]. - -\verbinput (91-94) optex.ini - -The `\everyjob` register is initialized and the format is saved by -the `\dump` command. - -\verbinput (96-104) 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 deleted file mode 100644 index 9bcec7db1e0..00000000000 --- a/Master/texmf-dist/doc/optex/optex-userdoc.tex +++ /dev/null @@ -1,2042 +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\#ref:objects] -{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. - -You can create more independent lists of references (you are creating proceedings, -for example). Use \^`\bibpart` `{<name>}` to set the scope where \~`\cite`s -and references list are printed (and interconnected) independent of another -parts of your document. The \~`\cite` labels used in different parts can be -the same and they are not affected. References lists can be created manualy -by \^`\bib` or from a database by `\usebib`. -Example: - -\begtt \typosize[10/12] -\bibpart {AA} -...\cite[labelX] ... \cite[labelY] ... % They belong to AA bib-list -\usebib/c (simple) file.bib % generates AA bib-list numbered 1, 2, ... - % \cite prints [1], [2], ... by bib-list AA -\bibpart {BB} -...\cite[labelZ] ... \cite[labelX] ... % They belong to BB bib-list -\bibnum=0 \usebib/c (simple) my.bib % generates BB bib-list numbered 1, 2, ... - % \cite prints [1], [2], ... by bib-list BB -\endtt -% -By default, \^`\bibpart` is empty. So \~`\cite`s and the references list are conneted -using this empty internal name. - - -\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/pdfextra/LICENSE b/Master/texmf-dist/doc/optex/pdfextra/LICENSE new file mode 100644 index 00000000000..7468558136b --- /dev/null +++ b/Master/texmf-dist/doc/optex/pdfextra/LICENSE @@ -0,0 +1,12 @@ +Copyright (C) 2021 Michal Vlasák <lahcim8@gmail.com> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. diff --git a/Master/texmf-dist/doc/optex/pdfextra/README.md b/Master/texmf-dist/doc/optex/pdfextra/README.md new file mode 100644 index 00000000000..c47262b1f58 --- /dev/null +++ b/Master/texmf-dist/doc/optex/pdfextra/README.md @@ -0,0 +1,35 @@ +# PDF Extra + +PDF Extra provides extra PDF features for OpTeX. + +As a minimalistic package OpTeX doesn't support "advanced" features of PDF file +format in the base. This third party package aims to provide them. Summary of +supported features: + + - insertion of multimedia (audio, video, 3D); + - hyperlinks and other actions, + - trigger events; + - transitions; + - attachments. + +The repository of PDF Extra is at https://github.com/vlasakm/pdfextra. + +# Documentation + +See `pdfextra-doc.pdf` for documentation. It contains user documentation as +well as technical documentation interleaved with source code. + +# Installation instructions + +Put `pdfextra.opm` where `optex` can find it. + +Or just copy paste anything you want. + +# Usage + +In OpTex do: `\load [pdfextra]`. + +# License + +This package is available under the Zero-Clause BSD license. See `LICENSE` for +more information. diff --git a/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example-part.prc b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example-part.prc new file mode 100644 index 00000000000..812479dcbb0 Binary files /dev/null and b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example-part.prc differ diff --git a/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.pdf b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.pdf new file mode 100644 index 00000000000..abb2e9c4c5a Binary files /dev/null and b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.pdf differ diff --git a/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.tex b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.tex new file mode 100644 index 00000000000..6093bf7def5 --- /dev/null +++ b/Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.tex @@ -0,0 +1,341 @@ +% PDFextra example file. +% This file, apart from other topics, shows how to port 3D examples from media9 +% (https://ctan.org/pkg/media9) documentation. You probably have to adjust path +% searching to succesfully compile this example, e.g.: +% +% \begtt +% env TEXMFDOTDIR=.:~/src/texlive/texmf-dist/source/latex/media9/files/ optex pdfextra-example.tex +% \endtt + +% basic \OpTeX/ settings +\enlang\enquotes +\fontfam[lm] + +%\pdfobjcompresslevel=0 +%\pdfcompresslevel=0 + +% load the package from standard search path +\load[pdfextra] + +% Before using \hlink we must activate hyperlinks +\hyperlinks\Blue\Green + +% Maybe we want to greet the user and jump to page 2 right at the start? +\openaction[ + js:{% + app.alert("Javascript alert, open action"); + console.println("printing to console from openaction");}, + pg:2, +] + + + +% Using document level JavaScript we can run initialization code right at the +% start (this is more flexible than \openaction). +\dljavascript[random]{ + function getRandomNumber() { + return 4; % chosen by fair dice roll, ![https://xkcd.com/221/] + } + console.println("initialized with seed " + getRandomNumber()); +} + + + +% For external references we need to `\filedef` "external" and "url" files beforehand: +\filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf} +\filedef/x[doc-local]{optex-doc.pdf} + +% We then try to reference them using external references: +\hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation, section \"Multilingual phrases and quotation marks".} +\hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.} + + + +% Insert a video twice with different settings: +\filedef/e[video]{example-movie.mp4} +% insert video into page using Renditions mechanism with controls and autoplay +\render[video][ + controls=true, + aactions=\renditionautoplay, +]{\picwidth=\hsize \inspic{example-image.pdf}} + +% Maybe add action buttons? +\hlink[rendition::play]{play} \hlink[rendition::pause]{pause} +\hlink[rendition::stop]{stop} \hlink[rendition::resume]{resume} + +% Render the same file again, but with different dimensions, no controls +% and explicit activation. +\render[video]{\inspic{example-image.pdf}} +% This one can't have buttons, because it doesn't have its own name ("video") is used by the previous one. + + + +% Add already embedded video to the list of attachments shown in user +% interface. +\attach[video] + + +% We are done for this page, who not go to the next one? +% +% \hlink typesets in group, so we locally disable lining links (our button is +% bigger than normal line) +\hlink[named:NextPage]{\nolininglinks\typoscale[2000/2000]\inoval{NEXT PAGE}} + + + +\vfil\break + + + +% deliver fresh random number to everyone who sees this page using "page open" +% trigger event of page's actions +\pageactions[ + {O} {js:{app.alert("Random number for you is " + getRandomNumber());}} +] + +% "previous page" link with "Split" transition +\hlink[pg:1, transition:Split]{Go to previous page (with transition).} + + + +\vfil\break + +% A 3D Rich Media annotation with a custom view and script follows: + +% First we define the 3D file, so we can use same name for the view and have it auto included. +\filedef/e[example]{pdfextra-example-part.prc} + +% Then a simplistic "front" view. +\DDDview[example][ + projection=ortho, + roo=400, +] + +% A 3D JavaScript script that will define function to use with action button. +% (we write the script only now, so we don't have to carry around an extra file in the package) +\newwrite\js +\immediate\openout\js=turn.js +% rotate every node by angle degrees along $x$ axis +\immediate\write\js{\detokenize{ +function turn(angle) { + angle = angle * Math.PI / 180; + for (var i = 0; i < scene.nodes.count; i++) { + var node = scene.nodes.getByIndex(i); + node.transform.rotateAboutXInPlace(angle); + } +} +}} +\closeout\js + +% The annotation itself, with our script above. +\RM[example][ + activation=auto, + scripts=turn.js, +]{{\White\vrule width\hsize height\hsize}} + +\hlink[js:\DDDcontext{example}.turn(10);]{Turn by 10 degrees along $x$ axis.}\par +\hlink[js:\DDDcontext{example}.turn(30);]{Turn by 30 degrees along $x$ axis.}\par +\hlink[js:\DDDcontext{example}.turn(90);]{Turn by 90 degrees along $x$ axis.} + + + +\vfil\break + + +% Here is the "epix" 3D model example from media9 documentation ported to pdfextra +% +% First we define a view with the same name as the future Rich Media +% annotation. This view will then automatically be used if no `views` is +% specified. No need to be excessive with decimal numbers. +\DDDview[epix][ + FOV=30, + c2c=4 2 3, + coo=4.41 2.19 0, + roo=430, +] + +% 3Dmenu is used often, lets use shortcut instead. +\filedef/e[3dmenu]{3Dmenu.js} +% We want to use the nice "epix" name for the view and annotation. +\filedef/e[epix]{epix.prc} + +% Just to spice things up, we diverge a bit from media9 and define custom background color. +\colordef\GreyBG{0.1\Black} + +% Define the 3D Rich Media annotation. One view is automatically detected from +% name ("epix"). Scripts will run in turn at initialization time. +\RM[epix][ + scripts={ + asylabels.js, + 3Dspintool.js, + 3dmenu, + }, + background=\GreyBG, +]{\picwidth=0.8\hsize \picheight=0.8\hsize \inspic{epixposter.pdf}} + + + +\vfil\break + + + +% Second media9 example is "dice" it has a lot of views, but they are simple. +% This time we can't use the deduction with same name. +\DDDview[Front][roo=27] +\DDDview[Back][roo=27, c2c=0 1 0] +\DDDview[Left][roo=27, c2c=-1 0 0] +\DDDview[Right][roo=27, c2c=1 0 0] +\DDDview[Top][roo=27, c2c=0 0 1] +\DDDview[Bottom][roo=27, c2c=0 0 -1] +\DDDview[Fish Eye at Centre][fov=120] + +% We want to use all the defined views, as well as autoactivate the annotation. +% This means that the previews mostly sets dimensions, because it will not be +% shown much. (Except in viewers that don't support 3D Rich Media -- all except +% Acrobat). +\RM[dice.u3d][ + views={Front, Back, Left, Right, Top, Bottom, Fish Eye at Centre}, + activation=auto, + scripts=3dmenu, +]{{\Red \vrule height.5\hsize width.5\hsize}} + +% A few buttons for switching views. +\hlink[goto3dview::/N]{\frame{Next view}} +\hlink[goto3dview::(Back)]{\frame{View \"Back"}} +\hlink[goto3dview::5]{\frame{6th view in the list}} + +% And define the action buttons using this new custom action. +\hlink[diceview:/N]{Next view} +\hlink[diceview:(Back)]{View \"Back"} +\hlink[diceview:5]{6th view in the list} + + +\vfil\break + + +% Last media9 example ported. It has its own JavaScript file for animation, +% which can be customized at runtime using JavaScript actions that access 3D +% conotext. +\filedef/e[malte]{malte.u3d} +\DDDview[malte][c2c=1 1 1, roo=0.25] +\RM[malte][ + activation=auto, + scripts={3dmenu, malte.js}, +]{{\Blue \vrule height.5\hsize width0.5\hsize}} + +{\picheight=1.44em +% Normal JavaScript actions, but we access functions defined globaly in the 3D +% JavaScript context of "malte" Rich Media annotation. +\hlink[js:\DDDcontext{malte}.cntrClockWise();]{\inspic{boutona.pdf}} +\hlink[js:\DDDcontext{malte}.pause();]{\inspic{boutonb.pdf}} +\hlink[js:\DDDcontext{malte}.clockWise();]{\inspic{boutonc.pdf}} +\hlink[js:\DDDcontext{malte}.scaleSpeed(1/1.1);]{\inspic{boutond.pdf}} +\hlink[js:\DDDcontext{malte}.origSpeed();]{\inspic{boutone.pdf}} +\hlink[js:\DDDcontext{malte}.scaleSpeed(1.1);]{\inspic{boutonf.pdf}} +} + + +\vfil\break + + +% Lastly a showcase of transitions / page durations in \OpTeX/ slideshow. +% Because transitions are displayed only in fullscreen mode, we could request +% it by using "\fullscreen". But we have more pages before this, so we didn't. + +% We just turn the rest of the document into slideshow. +\slides +\slideshow +% To see the transitions better, we color each page with a background color. +\global\pgbackground={\bgcolor \hrule height\pdfpageheight width\pdfpagewidth} +\glet\bgcolor=\Yellow + +% Transitions on all pages where it is not said otherwise will be of type +% "Wipe" and be 1 second long. +\transitions[Wipe:1] + +% The slides will by default be shown for 3 seconds before advancing to the next one. +\defaultpageduration[3] +% But the first slide has override to only be shown for 1 second. +\pageduration[1] + +\tit Presentation + +\subtit Transistions and durations + +\pg; +\glet\bgcolor=\Red +% All transitions are defined on the page object and they are shown when we go +% to that page. That means that we probably didn't see the "Wipe:1" animation +% of the first slide, because we already were there. However, this second slide +% with "Fade" is now shown correctly. (The first one also will, when we go +% back.) +\transition[Fade] + +\sec First slide + +Some\pg+ +% In a slideshow, by using \pg+ we are on a new PDF page with independently set +% transition/duration. We can use this to disable page durations -- we have +% seen the "single page override" in action on previous page, and the default +% duration on this "page". +\defaultpageduration[] + +% Also apply a long transition on this "page"/"slide"/"subslide". +\transition[Dissolve:4] + +% More uses of currently set default values follow. +text\pg+ + +to\pg+ + +test\pg+ + +slideshow + +\pg; +% Now show different transitions on differently colored pages: +\glet\bgcolor=\Green +\transition[Split:3:/Dm /V /M /I] + +\sec Second slide + +\transitions[Blinds:2] + +more\pg+ + +text + +\transitions[Wipe] + +\pg; +\glet\bgcolor=\Brown +\transition[Dissolve] + +\sec Third slide + +\pg; +\glet\bgcolor=\Red +\transition[Box] + +\sec More + +\pg; +\glet\bgcolor=\Yellow + +\sec slides + +\pg; +\glet\bgcolor=\Red + +\sec using + +\pg; +\glet\bgcolor=\Yellow + +\sec default transition + +bye\pg+ + +bye + +\bye diff --git a/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf b/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf new file mode 100644 index 00000000000..e5a6b8e30de Binary files /dev/null and b/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf differ diff --git a/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex b/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex new file mode 100644 index 00000000000..38f6cd97952 --- /dev/null +++ b/Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex @@ -0,0 +1,684 @@ +% vim: tw=80 +\load [doc, pdfextra] +\catcode`\.=11 + +\hyperlinks\Green\Green + +% table notes (http://petr.olsak.net/optex/optex-tricks.html#tnote) +\newcount\tnotenum +\def\tnotelist{} +\def\tnote#1{\incr\tnotenum $^{\rm\_romannumeral\tnotenum}$\global\addto\tnotelist{{#1}}} +\def\tnoteprint{\typoscale[920/920]\par \tnotenum=0 + \ea\foreach\tnotelist + \do{\advance\tnotenum by1 \par $^{\rm\_romannumeral\tnotenum}$##1 }\par + \global\tnotenum=0 \gdef\tnotelist{}% +} + +% use `\hlink` instead of OpTeX `\*link` s +\protected\def\_link[#1]#2#3{\hlink[#1]{#3}} +\protected\def\_ilink[#1]#2{\hlink[#1]{#2}} +\protected\def\_ulink[#1]#2{\hlink[url:#1]{#2}} +\public \link \ilink \ulink ; + +\let\_cslinkcolor\Blue + +% allow hyperlinking of \OpTeX's control sequences (see doc.opm) +\let\_pdfextra_opdocaction\_pdfextra_urlaction +\let\_pdfextra_opdoclinkcolor\Blue +\def\_Xindex#1#2{\sdef{,#1}{}\slet{el:#1}{optexdoclink}} +\def\optexdoclink{\hlink[opdoc:\optexdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}} +\def\optexdocurl{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf} +\isfile{optex-doc.eref}\iftrue \input{optex-doc.eref}\fi + +\insertoutline{PDF extra} +\tit PDF extra -- extra PDF features for \OpTeX/ + +\hfill Version \_pdfextra_version + +\centerline{\it Michal Vlasák, 2021} +\bigskip + +\noindent +`PDFextra` is a third party package for \OpTeX/. It aims to provide access to +more advanced PDF features, which are currently not supported in \OpTeX/ -- +especially interactive and multimedia features. The development is hosted at +\url{https://github.com/vlasakm/pdfextra}. + +In the spirit of \OpTeX/ you may use these macros in any form you want. Either +by installing this package and doing `\load[pdfextra]` in \OpTeX/, or just by +copying some useful parts of this package into your documents / packages. +\OpTeX/ namespacing is used, but it can be easily stripped, if you wish to +incorporate these macros into other macro packages. The code currently depends +on \LuaTeX/, but mostly uses only pdf\TeX/ primitives and a few simple macros +from \OpTeX/. + +User documentation (`pdfextra-doc.tex`) and technical documentation interleaved +with source code (`pdfextra.opm`) are all typeset in this PDF file. Some +examples of usage are in the user documentation, but file +`pdfextra-example.tex` contains more examples. + +\insertoutline{Contents}\outlines{0} +\notoc\nonum \sec Contents +\maketoc + +\vfil\break + +\chap User documentation + +\sec Defining files + +Many commands provided by this package require you to supply a file <name>. This +is because many commands either work directly (like inserting attachments or +multimedia) or can optionally use files (like inserting JavaScript). +The \"right" way to use <name> is to first define the <name> with:\nl\indent +\^`\filedef``/<type>[<name>]{<path or URL>}`. + +Where <name> is the name you will use to refer to this file. It is currently +limited to ASCII only (as all \"<name>s" required by this package). +Interpretation of <path or URL> +depends on the type, which may be: + +\begitems + * `e`, \"embedded file". The file with path <path> will be embedded to the PDF + file. A file that is embedded this once, can later be used many times in + different contexts, e.g. you may use it to attach a video as an attachment but + also have it play on page 1 and even other pages. This is the best way, because + the resulting PDF file is self contained. + * `x`, \"external file". <path> can only be a path to the current directory. + To refer to the file only <path> is used, sort of like a reference. This way + the file you want to refer to {\em has} to be present in the same directory as + the PDF file when it is {\em viewed}! + * `u`, \"URL file". <URL> is the URL of the file you want to refer to. +\enditems + +All these create the same type of object, which ideally could be used +interchangibly everywhere a {\em file specification} is required in PDF. This is +sadly not always true. The limitations to only certain types of `\filedef`'s +will be mentioned in due sections. But as a rule of thumb, most of the time you +want to embed the files into PDF. The external/URL references are good for +refering to external files, although other methods are also possible there. + +Because most of the times you want <name> to be embedded file, you may omit the +prior definition and instead use the <path> itself. The file will be +autoembedded. + +Examples: + +\begtt +\filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf} +\filedef/x[doc-local]{optex-doc.pdf} +\filedef/e[doc-embedded]{optex-doc.pdf} +\endtt + +\label[user:multimedia] +\sec Multimedia + +It is possible to insert video, audio and 3D files for playback/display inside +a PDF file (on a page). There are several different PDF mechanisms for +inserting multimedia. For audio/video this package uses the so called +\"Renditions", which currently have the best support in PDF viewers (fully +works in Acrobat and Foxit, partly in Evince and Okular). Rich Media +annotations are used for 3D art (works only in Acrobat Reader), although it is +possible to also insert audio/video using this mechanism it is very restricting +and Renditions are recommended. + +Use command \^`\render``[<name>][<optional key-value parameters>]{<appearance>}` for +inserting audio/video with Renditions or +\^`\RM``[<name>][<optional key-value parameters>]{<appearance>}` for inserting +audio/video/3D as Rich Media annnotation. +The result of this command is similiar to what `\inspic` +produces\fnote{But because annotations are involved, transformations using PDF +literals will not work as expected.}. Both commands expect <name> to be +\~`\filedef`'d name of the file to play/display. As usual, fallback for +interpreting <name> as path (and embedding it) is in place. It is recommended +to only use embedded files with both mechanisms (Rich Media requires it, +Renditions with other than embedded files do not work in Acrobat). Optional +key-value parameters may be used to customize default values. They may be left +out enitrely (including brackets). Last parameter, <appearance>, defines so +called \"normal apperance", which is shown before the annotation is activated +(audio/video starts playing or 3D scene is displayed). The dimensions of +resulting multimedia annotation will be taken from <appearance>. Most likely +you want to use a \"poster" picture (inserted with `\inspic`) as appearance -- +the dimensions will be taken from it and e.g. aspect ratio will be nicely +preserved. + +Customization of Renditions is possible using key-value parameters, but beware +that it mostly doesn't work in Evince and Okular (Acrobat and Foxit are fine in +this regard). The available parameters are in Table~\ref[tab:kv-renditions]. +Most customizations of Rich Media concern 3D art. Available parameters are +listed in Table~\ref[tab:kv-rm]. + +\midinsert +\label[tab:kv-renditions] +\caption/t Key value parameters available for Renditions (\~`\render`) +\cskip +\centerline{\table{lllp{72mm\fL}}{ +Key & Possible values & Default & Description \crll +`controls` & `true` or `false` & `false` & Whether to display audio/video player controls. \crl +`volume` & decimal betwen 0 and 100 & 100 & Audio volume. \crl +`repeat` & integer $\geq$ 0 & 1 & Number of repetitions (0 means loop forever). \crl +`background` & \OpTeX/ color & `\White` & Color used for part of the annotation not covered by video player (for wrong aspect ratios). \crl +`opacity` & decimal between 0 and 1 & 1 & Opacity of `background`. \crl +`aactions` & `\renditionautoplay` & (none) & Can be used for autoplay on page open. \crl +`name` & ascii string & `<name>` & Name for use with actions and scripts. \crll +}} +\endinsert + +\midinsert +\label[tab:kv-rm] +\caption/t Key value parameters available for Rich Media (\~`\RM`) +\cskip +\centerline{\table{lp{31mm\fL}lp{75mm\fL}}{ +Key & Possible values & Default & Description \crll +`activation` & `explicit` or `auto` & `explicit` & Whether to automatically activate the annotation on page open or display normal apperance until user clicks. \crl +`deactivation` & `explicit` or `auto` & `explicit` & Whether to automatically deactivate the annotation on page close or require explicit deactivation by user (from right click menu). \crl +`toolbar` & `true` or `false` & `true` & Whether to show 3D toolbar (with view and other options). \crl +`views` & comma separated list of view <name>s & `<name>` & List of names of 3D views to be used. The default is to try a view of same <name>. Beware that unknown views are silently ignored. \crl +`scripts` & comma separated list of script <name>s & (none) & List of names of JavaScript script file <name>s to be used. \crl +`name` & ascii string & `<name>` & Name for use with actions and scripts. \crll +}} +\endinsert + +The weird `name` key is only required if one media file is used +more than once and control using actions or JavaScript scripts is needed. + +Examples of video insertion: + +\begtt +% embed file under name "video" +\filedef/e[video]{example-movie.mp4} +% insert video into page using Renditions mechanism with controls and autoplay +\render[video][ + name=bigvideo, + controls=true, + aactions=\renditionautoplay, +]{\picwidth=\hsize \inspic{example-image.pdf}} + +% render the same file again, but with different dimensions, no controls +% and explicit activation +\render[video]{\inspic{example-image.pdf}} +\endtt + +When displaying 3D there are more things involved. First, only U3D and PRC can +be included in PDF files. The simplest way to show the 3D scene on page is without +any optional parameters: +\par\nobreak\begtt +\RM[part.prc]{\picwidth=\hsize \inspic{part.png}} +\endtt + +The resulting view will be what is defined in the 3D file. But it is possible +to customize it, by creating custom view. Or even more of them -- they will be +available in the user interface for easy switching, first one is considered +default. Parameters not defined in a custom view often take what is in the 3D +file as default value. \^`\DDDview``[<view name>][<key-value parameters>]` is +the command for defining 3D views. The brackets surrounding key-value +parameters have to be included even if no key-value parameters are used. The +available parameters are explained in Table~\ref[tab:kv-3dview]. + +\midinsert +\label[tab:kv-3dview] +\caption/t Key value parameters available for 3D views (\~`\DDDview`) +\cskip +\centerline{\table{lp{38mm\fL}lp{55mm\fL}}{ +Key & Possible values & Default & Description \crll +`projection` & `perspective` or `ortho` & `perspective` & Projection type to use (perspective distorts the view, e.g. parallel lines are not shown as such, but is more natural to human eye, orthogonal projection is what is generally used with technical parts). \crl +`scale` & decimal number & 1 & Scaling to use when orthogonal projection is used. \crl +`FOV` & number between 0 and 180 & 30 & Field of view for use with perspective projection. \crl +`background` & \OpTeX/ color & `\White` & Color used as background in the 3D scene. \crl +`rendermode` & {\typosize[9/10]`Solid`,\hfil\break`SolidWireframe`,\hfil\break`Transparent`,\hfil\break`TransparentWireframe`,\hfil\break`BoundingBox`,\hfil\break`TransparentBoundingBox`,\hfil\break`Wireframe`,\hfil\break`ShadedWireframe`,\hfil\break`Vertices`,\hfil\break`ShadedVertices`,\hfil\break`Illustration`,\hfil\break`SolidOutline`,\hfil\break`ShadedIllustration`} & (taken from 3D file) & Used rendering mode. See PDF standard\tnote{\url{https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G12.2358303}} for more details. \crl +`lighting` & `White`, `Day`, `Night`, `Hard`, `Primary`, `Blue`, `Red`, `Cube`, `CAD`, `Headlamp` & (taken from 3D file) & Used lighting scheme. See PDF standard\tnote{\url{https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G12.2358356}} for more details.\crl +`method` & `media9`, `manual`, `u3d` & `media9` & Method used for defining 3D camera position and orientation. \crll +}} +\tnoteprint +\endinsert + +The value of `method` key influences what other key-value +parameters are available. For details about the manual method see the technical +documentation~(\ref[mm-3dviews]). The `u3d` method works only with U3D files +(not with PRC files) and requires you to know the internal \"path" of the view +contained in the file and is hence not always useful (especially when the paths +are weirdly constructed by exporting applications). But if you know the path +you can use \"`method=u3d, u3dpath=<path>`". All Unicode characters are allowed in +<path>. + +The most useful method of specifying the camera position/orientation is +`method=media9`. The same method is also used in a number of other packages +(movie15, rmannot, Con\TeX/t). Its input are key-value parameters, listed in +Table~\ref[tab:kv-media9]. For illustration of the parameters check the +documentation\fnote{\url{https://mirrors.ctan.org/macros/latex/contrib/media9/doc/media9.pdf\#figure.8}} +of media9. + +\midinsert +\label[tab:kv-media9] +\caption/t Key value parameters available for media9 method of 3D views (\^`\DDDview`) +\cskip +\centerline{\table{lp{38mm\fL}lp{50mm\fL}}{ +Key & Possible values & Default & Description \crll +`coo` & three space separated (decimal) numbers & `0 0 0` & \"Center of orbit". Coordinates of the point camera is supposed to look at. \crl +`roo` & (decimal) number & `0` & Distance of camera from `coo`. \crl +`c2c` & three space separated (decimal) numbers & `0 -1 0` & \"Center of orbit to camera" vector. A directional vector (i.e. length doesn't matter). The direction the camera will be looking at is opposite of this vector. Default is view towards positive $y$.\crll +}} +\endinsert + +You can construct simple views only by using these few parameters. When talking +about meanings/names of different views it is needed to know the real placement +of the 3D object in the 3D world. But for a reasonably orientated object in the +center (`coo=0 0 0`) constructing simple views is very easy (keep in mind +`method=media9` is default): + +\begtt +\DDDview[front][ + projection=ortho, + roo=400, +] +\DDDview[left][ + projection=ortho, + roo=400, + c2c=-1 0 0, +] +\DDDview[top][ + projection=ortho, + roo=400, + c2c=0 0 1, +] +\DDDview[isometric][ + projection=ortho, + roo=500, + c2c=-1 -1 1, +] +\endtt + +We can then perhaps use these views in \^`\RM`: + +\begtt +% Auto activated 3D Rich Media annotation. White background just ensures +% the right dimensions. Comma in `views` is escaped using "{}". +\RM[part.prc][ + activation=auto, + views={front, left}, +]{{\White\vrule width\hsize height\vsize}} + +\RM[part.prc][ % the same 3D file, now with different views + name=part2, + activation=auto, + views={top, isometric}, +]{{\White\vrule width\hsize height\vsize}} +\endtt + +If you want to deduce the view parameters automatically it is possible. You can +just not specify any view, but include the `3Dmenu.js` script from media9 +package. It enables you to right click the annotation and select \"Get Current +View" (or even \"Generate Default View" which finds the view all by itself). A +window with generated parameters will show up. You can then copy the ones this +package understands (`c2c`, `coo`, `roo`) and use them. You don't have to be +excessive with precision, because after calculation everything gets rounded to +6 decimal places anyways. + +\begtt +% using 3Dmenu.js to generate 3D view parameters automatically +\RM[part.prc][ + name=part3, + activation=auto, + scripts=3Dmenu.js, +]{{\White\vrule width\hsize height\vsize}} +\endtt + +The use of `scripts` isn't limited to this though, there are many other +possibilities. First, you can use as many scripts as you want +(`scripts={script1.js, script2.js, ...}`), but be careful that 3D JavaScript is +kind of special, and has to come from embedded files (here we +were using the auto-embedding, but we could have used e.g. +\~`\filedef/e[3dmenu]{3Dmenu.js}` and then \"`3dmenu`" instead). For creating +your own scripts check out the Acrobat 3D JavaScript +API\fnote{\url{https://wwwimages.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/AcrobatDC_js_3d_api_reference.pdf}}. +It is possible to do different transformations and achieve animations using +\"time events". The implicit \"context" of 3D scripts can be accessed from +normal JavaScript actions (see~\ref[user:actions-3djs]). Vice versa 3D scripts +may access the global JavaScript environment using `host` object. + +More examples of 3D Rich Media, including usage of 3D JavaScript, are available +in the example file `pdfextra-example.tex`. They show how it is possible to +port the examples used by media9. + +\sec Actions + +Actions are very important aspect of interactivity in the context of PDF. There +are a few very useful types of actions, like \"goto" actions which jump to +other part of document. There are also a few ways how to {\em execute} actions. +The most usual is a clickable area on page, but clickable bookmarks (\"document +outline") also execute actions behind the scenes. \OpTeX/ supports only basic +\"goto" and \"URI" actions using `\ilink` (used for `\ref`, `\cite`, etc.) and +`\ulink` (used for `\url`). + +This package offers generalization of this mechanism. The core of it is a way +of specifying an action. This syntax is called <action spec> and is used for +example by `\hlink` command, which can replace both `\ilink` and `\ulink`. +<action spec> is a comma separated list of `<type>:<arguments>`. where <type> +refers to the action type and the syntax of arguments is dependant on <type>. +Leading spaces are ignored, trailing aren't. You probably won't often use the +possiblity of specifying multiple actions, but it is for chaining execution of +several actions. + +\^`\pdfaction``[<action spec>]` is available for lower level creation of +different actions, but for clickable areas on page you will use +\^`\hlink``[<action spec>]{<text>}` with a very similiar syntax. Although note, +that `\hlink`'s interface is also not really high level and wrapping it inside +macros like `\ref` or `\url` might be beneficial. <text> will be typeset +directly and the area it occupies will be clickable. Clicking it executes +action defined by <action spec>. Line breaks inside <text> will be possible, in +that case several clickable rectangles will be created, one for each line. +Normally in text you want the ares to be of the same height and depth +(calculated from `\baselineskip`), to achieve sort of a lining, uniform effect. +If you want to define big clickable buttons, you may need to turn off the +lining effect using \^`\nolininglinks`. It respects groups, but a counterpart +(\^`\lininglinks`) is also available. + +There are a few predefined action types (<type>): `url`, `extref`, `extpgref`, +`named`, `transition`, `js`, `goto3dview` and `rendition`. They will be explained in a +moment. Any unrecognized <type> is understood as an \"internal link", where +`<type>:<link>` is the destination of the link. Hence it is possible to +use `\hlink` as `\ilink` for example with \OpTeX/'s normal types +of internal links. For example: +\begtt +See section~\hlink[ref:section]{2.2.13} or page~\hlink[pg:5]{5}. +\endtt +`\ulink` may be replaced like this: +\begtt +Visit CTAN's \hlink[url:https://www.ctan.org/]{website}. +\endtt + +Before we really get into different types of actions, there is a nicer command +for setting the initial (\"open") action of PDF document, which is executed +when the document is opened. It defaults to opening the page with the zoom +level according to viewing user's preferences. But you can change this using +\^`\openaction``[<action spec>]`: + +\begtt +\openaction[pg:2] +\endtt + +\secc External references +There are two actions analogous to internal links that can be used to link to +external documents. `[extref:<name>:<named destination>]` can be used to refer +to named locations in a PDF document prepared by `\filedef` with <name>. +`[extpgref:<name>:<page number>]` is similiar but refers to a page number. +Although it would be nice, these actions aren't well supported by all viewers. + +Example: + +\begtt +\hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation, + section \"Multilingual phrases and quotation marks".} +\hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.} +\endtt + +(Note that \"`:`" in \"`ref:langphrase`" is not part of the syntactic rule, it +is just the value of <named destination> in this case.) + +A little bit of customization is possible, see~\ref[actions-jump]. + +Because of the poor support you may find luck with the less universal url action with `#fragment`: + +\begtt +\hlink[url:http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf#ref:langphrases] + {OpTeX documentation, section \"Multilingual phrases and quotation marks".} +\endtt + +\secc Named actions +There are four defined in PDF standard, but viewers may support more. All in +examples: + +\begtt +\hlink[named:NextPage]{Go to next page,} +\hlink[named:PrevPage]{go to previous page,} +\hlink[named:FirstPage]{go to first page,} +\hlink[named:LastPage]{go to last page.} +\endtt + +\secc Transition actions + +Transition actions generally make sense only when chained {\em after} jump +actions. The specified transition/animation will occur, before destination is +opened, but it will not override a transition defined for the particular page. +The syntax is `[transition:<transition spec>]`. See~\ref[user:transitions] for +more information about `<transition spec>`. + +Example: +\begtt +\hlink[ref:yellow-slide, transition:Box:3:/M /O] + {Go to yellow slide with long outward Box transition} +\endtt + +\secc JavaScript actions + +They allow executing pieces of JavaScript code using syntax: +`[js:<name or script>]`. If <name or script> is a validly `\filedef`'d the script from file +<name> will be executed (only embedded files are valid). Otherwise <script> will +be used directly. Apart from reuse in different documents, scripts loaded from +files may be encoded in UTF-16BE and hence support Unicode, inline <script>s +current don't. + +Examples: + +\begtt +\openaction[js:{% + app.alert("Javascript alert, open action"); + console.println("printing to console from openaction"); +}] + +\filedef/e[jstest]{test.js} +\hlink[js:jstest]{JavaScript action from file} +\endtt + +(Note how braces were used to guard the comma in JavaScript code from being +interpreted as a action separator.) + +In these actions you may want to use your own functions which should be defined +before user has a chance of activating any other JavaScript actions. This is the +purpose of \"document level" JavaScript actions. They function exactly the same +way as normal JavaScript actions, but have names (although meaningless, they +must be unique) and are executed in order of definition. Use +\^`\dljavascript``[<name>]{<name or script>}` for defining these actions: + +\begtt \adef![#1]{\url{#1}} +\filedef/e[preamble]{preamble.js} +\djavascript[preamble]{preamble} + +\dljavascript[initialization]{% + var data = 42; + function getRandomNumber() { + return 4; // chosen by fair dice roll, ![https://xkcd.com/221/] + } + console.println("initialized with seed " + getRandomNumber()); +} +\endtt + +The JavaScript API available is not the same as the one in the web browsers. It +is instead specified by Adobe: +\url{https://wwwimages.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/js_api_reference.pdf}. + +\label[user:actions-3djs] +\secc 3D JavaScript actions + +There are no \"special" JavaScript actions for dealing with 3D. Normal +JavaScript actions are used. You just have to access the 3D context of the +annotation you want to control. For annotation with <name> the context is made +available in \^`\DDDcontext{<name>}`. Under this context object you find all +global definitions from the respective 3D scripts. For example if a \"`turn`" +function is defined, it is possible to call it like this: + +\begtt +\hlink[js:\DDDcontext{part3}.turn();]{Turn by 90 degrees along $x$ axis.} +\endtt + +\secc GoTo3Dview actions + +GoTo3Dview actions allow changing the view of the 3D scene to one of the +predefined views (those listed by `views` comma separated list of \~`\RM`). The +syntax is `[goto3dview:<name>:<view>]`. <name> is name of the annotation whose +view we want to change and <view> is the intended view. You can refer to last +inserted Rich Media annotation using empty name. For <view> you can either use +\"`(<view name>)`" (e.g. \"`(part)`"), index of the view in the view list (zero +based, e.g.\ \"`0`" for the first view) or one of the special values: \"`/N`" +(next), \"`/P`" (previous), \"`/F`" (first) \"`/L`" (\"last"). + +\begtt +% let's define an annotation with a few views +\RM[part.prc][ + activation=auto, + views={front, left, top, isometric}, +]{{\White\vrule width\hsize height\vsize}} + +% try the different methods of reffering to views +\hlink[goto3dview::/N]{Next view}, +\hlink[goto3dview::(left)]{left view} and +\hlink[goto3dview:part.prc:3]{third view}. +\endtt + +\secc Rendition actions + +Rendition actions can be used to control playback of \"Rendition annotations". +They use the syntax `[rendition:<name>:<operation>]`, where <name> refers to +the name of the rendition to control and <operation> is one of `play`, `stop`, +`pause` or `resume`. As a convenience, you can refer to last inserted rendition +using empty name. If a file has been \~`\render`ed more than once with the same +name, the action will influence the first instance. + +Beware that currently these actions do not work in Evince and Okular (but do in +Acrobat and Foxit). + +Examples: + +\begtt +% rendition with name=video, that we want to control +\render[video]{\inspic{example-image.pdf}} + +% we want the rendition action to have yellow border and red content +\let\_renditionborder\Yellow +\let\_renditionlinkcolor\Red + +To start playing the video, click \hlink[rendition::play]{\"Play"}. +After that you can \hlink[rendition:video]{pause}. +\endtt + +\label[user:transitions] +\sec Transitions and other page attributes + +In PDF there are a few settings that can be set as {\em page attributes}. This +means that they apply only to said page. For setting these page attributes, +there are two options: + +\begitems +* value for \"current page" (or rather the page where the command appears), +* default value used if \"current page" value is not set. +\enditems + +While this package contains mechanism to handle all page attributes, not that +many are useful for end user. The interesting ones remaining are: + +\begitems +* Transitions and page durations. When page has the transition attribute any +jump to this page will display the requested animation (customized by the +corresponding parameters). Page duration is the time before PDF viewer will auto +advance to the next page. \^`\transition``[<transition spec>]` sets transition +for the \"current page", \^`\transitions` sets the default. +`<transition spec>` has three parts:\nl\indent +`<animation type>:<duration>:<raw PDF attributes>`\nl +\noindent <animation type> is one of `Split`, `Blinds`, `Box`, `Wipe`, +`Dissolve`, `Glitter`, `Fly`, `Push`, `Cover`, `Uncover` and `Fade`, or the +special value `R` which essentially means no animation and instantaneous +transition (regardless of the set duration of transition). <duration> is the +duration of transition in seconds (integer or decimal number). +<raw PDF attributes> may be used to customize +the animations (for example `/M` can set the direction of motion of `Split`, +`Box` and `Fly`, e.g. `/M /I` for inward motion). For the raw PDF attributes +refer to the standard +itself\fnote{\url{https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G11.2295795}}. +`:<raw PDF attributes>` or even `:<duration>:<raw PDF attributes>` may be omitted. +Default values specified by PDF standard will be used in that case (1 second +duration and default values for all attributes). Page durations can be set +either using \^`\defaultpageduration``[<duration>]` or +\^`\pageduration``[<duration>]`, where duration is in seconds (default is no auto +advancement, i.e. $\infty$). +Examples: + +\begtt +% unless stated otherwise all pages will have Wipe animation +% with 1 second duration +\transitions[Wipe:1] + +% but this page has a 1 second Fade animation +\transition[Fade] + +\pg+ % (if using \slides) + +% and this page has 3 second Split animation +% with vertical direction and inward motion +\transition[Split:3:/Dm /V /M /I] +\endtt + +Note that transitions are only displayed when in {\em full-screen mode}. You +can use \~`\fullscreen` to have the document automatically open in full-screen +mode. + +* Additional actions. It is possible to define actions which will respond to +page events: page open (`/O`) and page close (`/C`). They can be set using +\^`\defaultpageactions``[<additional actions spec>]` (the default for all pages) and +\^`\pageactions``[<additional actions spec>]` (current page override). +<additional actions spec> consists of braced pairs of \"event" (O or C in this +case) and <action spec>. Example: + +\begtt +\pageactions[ + {O} {js:{app.alert("Page open, random = " + getRandomNumber());}} + {C} {js:{app.alert("Page close!");}} +] +\endtt + +\enditems + +\sec Attachments + +Every file embedded into a PDF file may optionally be presented in the user +interface as an embedded file. This allows readers of the document to save or +open the file. + +PDF allows two ways of presenting attachments -- using annotations (the +attachments is represented by a rectangular icon on a page) or global array of +attachments (attachments are visible in PDF viewers toolbar). The first method +is intended more for document reviewers than for primary insertion. Hence this +package supports only the second type. + +You may add an embedded file to the global attachments array using +\^`\attach``[<name>]`. As usual, name is either a <name> defined with +`\filedef` or alternatively a path to file which will be embedded (and +`\filedef`d) automatically. It is not possible to `\attach` files referenced by +path or URL. + +If you want to automatically display toolbar with embedded files, consider +using `\showattached` (see section~\ref[user:document-view]). + +\label[user:document-view] +\sec Document view + +You can choose what is shown when document is opened with commands: + +\begitems +* \^`\fullscreen` (the document is opened in full-screen mode), +* \^`\showoutlines` (show bookmarks/outlines toolbar) +* \^`\showattached` (show attachments in toolbar) +\enditems + +The commands are mutually exclusive and only the first appearing one will be respected. + +You can set request two page view (odd pages on the right) using +\^`\duplexdisplay`. It is useful for more natural display of double sided +documents. Because it may not be desirable to automatically apply this, it is +independent of `\margins`. + +\chap Technical documentation + +\printdoctail pdfextra.opm +\printdoc pdfextra.opm + +\bye -- cgit v1.2.3