diff options
author | Karl Berry <karl@freefriends.org> | 2021-02-09 22:01:07 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-02-09 22:01:07 +0000 |
commit | fe491675252d9e6fe3ae6b1c67b198daed5cf936 (patch) | |
tree | ec846c8c711f8d0cdc9ab381f175d71746864a78 /Master/texmf-dist/doc/luatex | |
parent | 8790b9df74c6be439ccba2d4c53edfb57407ad6b (diff) |
optex (9feb21)
git-svn-id: svn://tug.org/texlive/trunk@57691 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/README | 9 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/omls.tex | 832 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/optex-doc.pdf | bin | 1362584 -> 1366580 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/optex-doc.tex | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/optex-math.tex | 6 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex | 45 |
7 files changed, 875 insertions, 23 deletions
diff --git a/Master/texmf-dist/doc/luatex/optex/README b/Master/texmf-dist/doc/luatex/optex/README index 50d4f1d165a..6c5ae30b5ae 100644 --- a/Master/texmf-dist/doc/luatex/optex/README +++ b/Master/texmf-dist/doc/luatex/optex/README @@ -19,7 +19,14 @@ doc/ ... PDF version of the OpTeX documentation and sources. History: -<0.19> Jan. 2020 +<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. diff --git a/Master/texmf-dist/doc/luatex/optex/omls.tex b/Master/texmf-dist/doc/luatex/optex/omls.tex new file mode 100644 index 00000000000..f161f151d7f --- /dev/null +++ b/Master/texmf-dist/doc/luatex/optex/omls.tex @@ -0,0 +1,832 @@ +\fontfam[lm] + +\adef<#1>{\ifcsname s:#1\endcsname + \link[s:#1]{}{\Blue$\langle$\hbox{\it#1\/}$\rangle$}% + \else {\Blue$\langle$\hbox{\it#1\/}$\rangle$}\fi} +\everyintt={\catcode`<=13 \Red} +\verbchar` +\enlang +\enquotes + +\def\r[#1]{\label[#1]\wlabel{\the\_itemnum}} +\def\:{$\to$} +\let\_narrowlastlinecentered=\ignoreit +\_def\_printsecc#1{\_par + \_abovetitle{\_penalty-200}{\_medskip\_smallskip} + {\_seccfont \_noindent \_raggedright \_printrefnum[@\_quad]% + \_label[\the\_secnum.\the\_seccnum]\wlabel{\the\_secnum.\the\_seccnum}#1\_nbpar}% + \_nobreak \_belowtitle{\_medskip}% + \_firstnoindent +} +\def\.`{\bgroup\catcode`\ =12 \scancs} +\def\scancs#1{\egroup + \immediate\_wref\Xknowncs{\string#1{\the\_secnum.\the\_seccnum}}% + \ea`\string#1% +} +\def\printcs#1{\ea\printcsred\csstring#1;~\ref[#1] \ } +\def\printcsred,#1;{{\Red\tt \bslash#1}} +\def\printknowncs{\ifx\knowncslist\undefined \let\knowncslist=\empty \fi + \ifx\knowncslist\empty TeX me again...\else + \_dosorting\knowncslist \ea\xargs \ea\printcs \knowncslist;\fi} + +\def\~`<#1>`{<#1>\sxdef{s:#1}{}\dest[s:#1]} + +\refdecl{ + \def\knowncslist{}^^J + \def\Xknowncs#1#2{% + \sxdef{,\csstring#1}{#2}% + \global\ea\addto\ea\knowncslist\ea{\csname,\csstring#1\endcsname}% + } +} +\sdef{_item:c}{\pdfsave\llap{\pdfscale{1.3}{1.3}$\circ$\enspace}\pdfrestore} + +%\parindent=15pt \iindent=\parindent \ttindent=\parindent +%\ttindent=0pt +\everylist={\advance\ttindent by-1em} +\hyperlinks \Green \Green +\def\cskip{\par\nobreak} +\def\begblock{\medskip\hbox\bgroup\vrule\vbox\bgroup\hrule\smallskip + \_fnset\leftskip=\parindent \rightskip=\parindent \medskip\noindent} +\def\endblock{\medskip\hrule\egroup\vrule\egroup} + +\def\raggedright{\rightskip=10pt plus1fil\relax} +\def\optexmanual{\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf]{\OpTeX/ manual}} + +\titskip=1cm + +\hfill Version 0.1 + +\tit \OpTeX/ Markup Language Standard + +{\it\hfil Petr Olšák, 2021}\bigskip + +The \OpTeX/ markup language standard (OMLS) declares a list of control +sequences used in \OpTeX/ documents including their syntax and sematic. The +listed control sequences in OMLS in section~\ref[listcs] in table~\ref[alistcs] +are called {\it known} and other control sequences are {\it unknown}. + +The main reason for OMLS is to give instructions on how to program convertors +from \OpTeX/ documents to another formats (Html, Markdown, \LaTeX/) or how +to interpret the \OpTeX/ document sources in such applications as +{\tt texcount} or text editors\fnote +{We suppose advanced editor features: color highlighting, sections/chapters folding, + auto-completions, etc.}. +These converters and applications are called {\it cnv-programs} in this document. + +We suppose that if you need absolute control over the typography of the +document when it is converted to PDF pages, then you use \OpTeX/ itself. If +you need to create other formats of the same document then you can use a +cnv-program which accepts OMLS. The result is a document without +typographical instructions like dimensions of pages, margins, paginations +and headers, selection of a font-family, dimensions of the fonts, etc.\ You can +imagine the result of such a conversion as a single Html page where more +typographical features can be controlled in a different way, for example by +an external CSS file. This is a reason why control sequences like `\fontfam` or +`\margins` are ignored by cnv-programs. + +Obviously, \TeX/ and \OpTeX/ itself gives possibility to declare various +input formats for various purposes. Sometimes (in very special cases) there +exists a good reason to declare a different and special input format by +\TeX/ macros. But if the source of the document respects the OMLS then it is +reasonably transformable to other formats by cnv-programs. We hope that +OMLS-ready documents cover a very large set of typical documents used these +days. + +We suppose that cnv-programs work internally with strings of source lines +without tokenization. This is one of the great differences in processing the +document directly by \OpTeX/ and using a cnv-program. The second difference is +that the expansion process of macros is not implemented in cnv-programs in +its full range. We respect that the result of cnv-programs will be different +than from processing directly by \OpTeX/. But this is not a bug, this is +the feature. We concentrate on the fixed syntax and sematic given by OMLS of the +\OpTeX/ document and we throw behind the head the typographical +exactness of the document which can be done only directly by \TeX/ (and it is +exactly described in \TeX/book, for example). + +\notoc\nonum\sec Table of contents + +\begmulti 2 +\maketoc +\endmulti +\vfil\break + +\sec Syntactical rules + +The syntactical elements are described as strings here. No \TeX/'s tokenization is +taken into account. The rule with a smaller number has precedence. + +\begitems \style n +* end of line or end of file \: \~`<eol>`.\r[eol] +* `%%:` at beginning of the line \: \~`<cnv-declarator>`, see section~\ref[cnv-decl]. +* `<cnv-declarator><text><eol>` is interpreted specially. +* space or a tab-character \: \~`<space>`. +* non-empty sequence of `<space>`s \: \~`<spaces>`.\r[spcs] +* an empty line or a line only with `<spaces>` \: \~`<empty-line>`. +* a character `a`--`z` or `A`--`Z` \: \~`<letter>`. +* a `<letter>` or `_` \: \~`<specletter>`. +* a character different from previous rule or `<eol>` or `<spaces>` \: \~`<non-specletter>` +* `\<non-specletter>` \: \~`<singlechar-control-sequence>`.\r[scs] +* a non-empty sequence of `<specletter>`s \: \~`<letters-seq>`. +* `\<letters-seq><non-specletter>` \: \~`<multiletter-control-sequence>``<non-specletter>`. +* `%<text><eol>` \: `<comment>` and it is completely ignored including `<eol>`.\r[com] +* `<spaces>` at beginning of the line marks that the line as {\it indented}. +* `<spaces>` at beginning of the line \: are ignored.\r[bspace] +* `<spaces><eol>` or `<eol>` \: `<spaces>`.\r[eolrm] +* `<multileter-control-sequence><spaces>` \: `<multileter-control-sequence>`.\r[csspace] +* `<multiletter-control-sequence>` or `<singlechar-control-sequence>` \: \~`<control-sequence>`.\r[cs] +* `<spaces>` \: `<space>`.\r[sspace] +* `~` \: non-breakable space. +* text where all pairs `{` and `}` match at arbitrary level \: \~`<balanced-text>`.\r[balt] +* `{<balanced-text>}` can be interpreted as a parameter of a `<control-sequence>`, see section~\ref[listcs]. +* The `{` alone not used by previous rule opens a group and the `}` alone closes the same group.\r[group] +* There are two main modes: h-mode, v-mode\fnote + {this is great simplification of real \TeX/ modes.}. + The document processing starts in v-mode. +* In v-mode: a `<non-space>` character or a control sequence listed + in table~\ref[vtohmode] swithes to h-mode. +* In h-mode: an `<empty-line>` or a control sequence listed in table~\ref[htovmode] switches to v-mode.\r[htov] +* The switching from v-mode to h-mode \: a paragraph begins. +* The switching from h-mode to v-mode \: the current paragraph ends. +* `$<text>$` or `$$<text>$$` \: process `<text>` in math-mode, see section~\ref[math]. +* a non-empty sequence of digits with optional `+` or `-` in the front \: \~`<number>`. +* `<number>` with optional dot inside the sequence of digits \: \~`<decimal-number>`. +* a pair of letters listed in the table~\ref[tex-units] \: \~`<tex-unit>`. +* optional space, i.e.\ `<space>` or nothing \: \~`<o-space>`. +* `<decimal-number><o-space><tex-unit><o-space>` \: \~`<dimen>`. +* `<control-sequence>` not listed in table~\ref[alistcs] nor in configuration \: \~`<unknown-control-sequence>`.\r[unkncs] +* `=<o-space>` or `<o-space>` \: \~`<o-equal>`. +* `<unknown-control-sequence><o-equal><dimen>` \: should be completely ignored.\r[eqdim] +* `<unknown-control-sequence><o-equal><number>` \: should be completely ignored. +* `<unknown-control-sequence>=<o-space>{<balanced-text>}` \: should be completely ignored. +* `<unknown-control-sequence>[<balanced-text>]` \: should be completely ignored.\r[ibkt] +* `<unknown-control-sequence>` \: should be ignored.\r[ignore] +* `<control-sequence>`s are processed as described in section~\ref[listcs] or + by a configuration of the cnv-program. +\enditems + +\bigskip +\label[vtohmode]\caption/t +List of control sequences which switch from v-mode to h-mode. +\cskip +\begblock +`\`<space>, +`\hfil`, +`\hfill`, +`\hskip`, +`\hss`, +`\indent`, +`\leavevmode`, +`\noindent`, +`\quad`, +`\qquad`, +`\vrule`. +\endblock + +\bigskip +\label[htovmode]\caption/t +List of control sequences which switch from h-mode to v-mode. +\cskip +\begblock +`\begblock`, +`\begitems`, +`\begmulti`, +`\begtt`, +`\bib`, +`\bigskip`, +`\bye`, +`\caption`, +`\chap`, +`\cskip`, +`\end`, +`\endblock`, +`\enditems`, +`\endmulti` +`\hrule`, +`\medskip`, +`\par`, +`\sec`, +`\secc`, +`\secl`, +`\smallskip`, +`\vfil`, +`\vskip`. +\endblock + +\bigskip +\label[tex-units]\caption/t +List of \TeX/ units. +\cskip +\begblock +`bp`, +`cc`, +`cm`, +`dd`, +`em`, +`ex`, +`in`, +`mm`, +`pc`, +`pt`, +`sp`. +\endblock + +\nonum\secc Examples + +\begitems +* `\%` is `<control-sequence>` by rules \ref[scs], \ref[cs]. It does not start + comment, because rule \ref[scs] has precedence before rule \ref[com]. +* `\%<space>`: the `<space>` is kept, but `\foo<space>`: the space is removed + by rule~\ref[csspace]. +* `wordA<spaces><eol><spaces>wordB` is `wordA<space>wordB` by rules~\ref[bspace], + \ref[eolrm], and~\ref[sspace]. +* `\kern-3pt` should be ignored, because `\kern` is `<unknown-control-sequence>` and rule + \ref[eqdim] is applied. +* `\vskip42mm` should finalize paragraph in h-mode by rule~\ref[htov] and then it + is ignored by rule~\ref[eqdim] because `\vskip` is + `<unknown-control-sequence>` not listed in table~\ref[alistcs]. +* `\typosize[12/16]` is ignored by rule~\ref[ibkt]. +* `\foo{text}` is `{text}` (i.e. `text` in a group) by rules~\ref[ignore] and~\ref[group]. +\enditems + +\sec Scanning parameters + +If a control sequence listed in rules above or in the section~\ref[listcs] +has a parameter, the parameter is scanned +as a string with interpretation only those rules which are needed to +determine the boundary of the parameters. For example `\tit <title><eol>` +applies only rule~\ref[eol] during scanning the parameter, i.e.\ `<title>` +is a string telemetered by the end of the line or the end of the file. +Or `\fnote{<balanced-text>}` applies only rule~\ref[balt]. + +If the parameter is in the format `{<something>}` then the `<something>` is +always meant as `<balanced-text>`. We don't specify the type `<balanced-text>` +explicitly here, so we refer to `\fnote{<text>}` and not +`\fnote{<balanced-text>}`, for example. + +The spaces before the scanned parameter are optional +and they are ignored. Spaces inside `{`...`}` are not ignored. + +If the parameter is in the format `{<something>}` and the first non-space +character is not `{` then the parameter is this first non-space character or +a `<control-sequence>` if the first non-space character is~`\`. For example +`\fnote a` is equal to `\fnote{a}`. The difference from this rule is given +for `\input`, `\verbinput`,`\inspic` and `\inkinspic` control sequences in +section~\ref[listcs]. + +If the parameter is scanned as a string already then +all syntactical rules are applied when it is used. For example: +\begtt +\tit This is a title +\endtt +the parameter is scanned as `This is a title` and the rules~\ref[spcs] +and~\ref[sspace] are applied when it is used. + + +\sec Declaration and text parts of the document + +A typical \OpTeX/ document has two parts. A declaration part, where +macros are defined by `\def` and friends, fonts and sizes are declared, etc. +This part should be ignored by cnv-programs. +The second part includes the document text with a markup using well-declared control +sequences. The cnv-program has to interpret the second part. + +So, the cnv-program starts in declaration-skipping mode and it switches to +the text mode later. + +When cnv-program is in declaration-skipping mode then all indented lines are +ignored. And lines which begins by `}` or by a <control-sequence> not listed +in table~\ref[textopen] are ignored too. + +If the line begins by a character other than `}` or by a <control-sequence> +listed in table~\ref[textopen] then cnv-program switches to text mode. All +texts are interpreted from this line including this one. + +User can say explicitly where the second part of the document starts by +`%%:text` given at beginning of a line. Moreover, if `%%:decl` is given at +beginning of a line, then all text between `%%:decl` and `%%:text` is +ignored, only other possible `<cnv-declarator>`s are processed here. +It means that the declaration part and the text part of the document can be +simply determined by the pair `%%:decl` and `%%:text`. + +\bigskip +\label[textopen]\caption/t +List of control sequences which start the text mode. +\cskip +\begblock \raggedright +`\address`, +`\begblock`, +`\begitems`, +`\begmulti`, +`\begtt`, +`\bf`, +`\bi`, +`\bib`, +`\caption`, +`\cite`, +`\clipinoval`, +`\clipincircle`, +`\ecite`, +`\fnote`, +`\frame`, +`\hfil`, +`\hfill`, +`\ii`, +`\iid`, +`\incircle`, +`\inkinspic`, +`\inoval`, +`\inspic`, +`\it`, +`\LaTeX`, +`\LuaTeX`, +`\maketoc`, +`\mnote`, +`\OpTeX`, +`\putpic`, +`\puttext`, +`\rcite`, +`\rm`, +`\rotbox`, +`\sec`, +`\secc`, +`\secl`, +`\table`, +`\TeX`, +`\tit`, +`\usebib`, +`\verbinput`. +\endblock + + +\sec[cnv-decl] The `%%:` declarators + +The `%%:` declarators are ignored when the document is processed by \TeX/ +but they can give instructions to cnv-programs. The `%%:` must be placed at +beginning of the line. The list of `%%:` declarators follows: + +\begitems +* `%%:decl` -- the following text is ignored until `%%:text` occurs. Only + other `%%:` declarators are interpreted. +* `%%:text` -- the following text must be interpreted in text mode. +* `%%:to <format> <config-file>` -- if the cnv-program converts to the + <format> then it has to use the <config-file>. For example: + \begtt + %%:to html html-mydocument.cfg + %%:to markdown markdown-mydocument.cfg + %%:to latex preamble-mydocument.cfg + \endtt + The language of the config files are not a part of this standard, we + suppose something to be natural for used cnv-program. The config file should + give additional rules for interpreting control sequences not listed in the + section~\ref[listcs] (see rule~\ref[unkncs]). For example a tool for + defining a behavior of unknown control sequences can be here. + These definitions can depend on the converted document and on the output + format and they can be given in the configuration files. +* `%%:app <application> <config-file>` -- behaves like `%%;to` but the + cnv-program name instead output format is given here. +* `%%:do <format-or-app> <action>` -- does an `<action>` if `<format-or-app>` + is output format or used cnv\hbox{-}program name. The `<action>` syntax depends + on used cnv-program and it typicaly does a change in its configuration or + give a command to it. +* `%%:skip <formats-or-apps>` -- ignores all following lines until another `%%:` occurs + if the output format or application name is included in the `<formats-or-apps>` + space-separated list. Example: + \begtt + %%:skip html markdown + This text is not interpreted when Html or Markdown output is generated. + %%: + \endtt + If the `<formats-or-apps>` is empty then the `%%:skip` is applied for + each cnv-program and for each output. +* `%%:if <formats-or-apps>` -- processes following lines until another `%%:` + only if the output format or application name is included in the + `<formats-or-apps>` space-separated list. Other cnv-programs or output formats + not mentioned here skip these lines. Note that \TeX/ processes such lines always. + But you can use `\ignoreit{<text>}` which is processed as + `{<text>}` by cnv-programs (see rule~\ref[ignore]) but it is ignored by \OpTeX. + Example: + \begtt + %%:if html latex + \ignoreit{\input{file.tex}} + %%: + \endtt + The `file.tex` in this example is processed only if \LaTeX/ or Html output is generated. +* `%%:use` -- the next single line is fully interpreted unless cnv-program ignores + declarations by `%%:decl` or because it is in declaration-skipping mode. + Example: + \begtt + %%:use + \verbchar` \picdir={img/} + \endtt + The example shows how cnv-program is able to read `\verbchar` or + `\picdir` settings in the declaration\hbox{-}skipping mode although these control + sequences are not listed in table~\ref[textopen]. +* `%%:quotes <qql> <qqr> <ql> <qr>` -- declares \~`<qql>` and \~`<qqr>` (left + and right double quotation marks), \~`<ql>` and \~`<qr>` (left and right single + quotation mark). They are used when `\"` or `\'` control sequences are + processed. Default: unset, i.e.\ `\"` and `\'` are interpreted as + unknown control sequences. +\enditems + + +\sec[listcs] List of known control sequences + +The phrase \"should be" is used very often when the interpretation of +control sequences is declared here. It means that this is only a common +interpretation, but differences are possible due to the type of the output +format and used cnv-program. For example, when we convert to \LaTeX\, then +`\-` and `\/` are not ignored but they are re-written without change to the +output of the \LaTeX/ source file. + +\bigskip +\label[alistcs] +\caption/t List of known control sequences alphabeticaly sorted. +\cskip +\begblock +\raggedright \printknowncs +\endblock + + +\secc Character-like control sequences + +\begitems +* \.`\%`, \.`\$`, \.`\&`,\.`\#` respectively \: should be normal characters + `%`, `$`, `&`, `#` respectively. +* \.`\bslash` \: normal character `\`. +* \.`\space`, `\<space>`, `\<eol>` \: space. +* `\,` \: should be small space or space. +* \.`\quad`, \.`\qquad` \: should be bigger space or more spaces. +* \.`\-`, \.`\/` \: should be ignored. +* \.`\"<text>"` or \.`\'<text>'` \: `<clqq><text><crqq>` or `<clq><text><crq>`, + only if `%%:quotes` are set. +\enditems + +\secc Input files + +\begitems +* \.`\input {<file-name>}` or `\input <file-name><space>` should redirect the + input to given file. At the end of the input-ed file or at \.`\endinput` the + reading of the current file continues. The file is read from the current + directory, but the <file-name> should include the full path to the file + or relative path starting from the current directory. First, the file + `<file-name>.tex` is tried to read and if it doesn't exist then + the file `<file-name>` is read. +* \.`\picdir <o-equal>{<text>}` saves `<text>` to `<picdir-value>`. By + default, `<picdir-value>` is empty. +* \.`\inspic {<file-name>}` or `\inspic <file-name><space>` should include the + given picture from the `<picdir-value><file-name>`. +* \.`\inkinspic {<file-name>}` or `\inkinspic <file-name><space>` behaves like + `\inspic`. +* \.`\verinput <ignore> (<lines>) <file-name><space>` should include the + <file-name> (only given lines) as a verbatim text, i.\,e. without any + syntactical interpretation. +* \.`\usebib/<letter> (<style>) <file-names>` should use files from + `<file-names>` to generate the list of bib references. The `<file-names>` + is comma separated list (the `.bib` extension is appended to + each such file name). Only cited bib records should be used in this + bib-references, i.e. their label must be used in a `\cite[<labels>]` or + `\rcite[<labels>]` or `\ecite[<label>]`. + What bib fields are used in bib records depends on the cnv-program and + on its configuration. Maybe, simple cnv-programs should generate nothing here. +\enditems + +\secc Titles + +\begitems +* \.`\tit <title><eof>` should be a title of the document. +* \.`\chap <title><eof>` or `\chap [<label>] <title><eof>` is the title of + first level. +* \.`\sec <title><eof>` or `\sec [<label>] <title><eof>` is the title of + second level. +* \.`\secc <title><eof>` or `\secc [<label>] <title><eof>` is the title of + third level. +* \.`\secl<level> <title><eof>` is the title of given level. +\enditems + +\secc Fonts + +\.`\rm` selects upright normal font (it is selected by default), \.`\it` selects +italic, \.`\bf` selects upright bold font, \.`\bi` selects bold italic and +\.`\tt` selects a monospaced font, \.`\em` select italic (if upright is current) or upright +(if italic is current). The font sizes or other font features are typically ignored +by cnv-programs. The actual font selection is closed at the end of the current group. +The groups are given: +\begitems +* explicitly by `{` and `}` characters (which are not delimiters of + parameters of known control sequences), +* implicitly: parameters of control sequences listed in table~\ref[groupcs] + are processed in a group and blocks of text enclosed by + `\begitems`...`\enditems`, `\begblock`...`\endblock`, `\begmulti`...`\endmulti` + are processed in a group. + Each item in `\table` is in a group. +\enditems + +\label[groupcs] +\caption/t Parameters of following control sequences are processed in a group. +\cskip +\begblock +`\caption`, +`\chap`, +`\fnote`, +`\mnote`, +`\sec`, +`\secc`, +`\tit`. +\endblock + +\secc Colors + +\.`\Red`, \.`\Green`, \.`\Blue`, \.`\Cyan`, \.`\Magenta`, \.`\Yellow`, \.`\White`, +\.`\Black`, and \.`\Brown` should select the given color of the font. The selection +is closed at the end of the current group (like font selectors). + +\secc Blockquotes + +The blockquote\fnote +{The terminology is borrowed from Markdown.} +is opened by \.`\begblock` and closed by \.`\endblock`. +Blockquotes can contain multiple paragraphs and can contain nested +blockquotes. + +\secc Lists + +The list is opened by \.`\begitems` and closed by \.`\enditems`. The `*` starts +a new item in this environment. Nested lists are allowed. + +The type of items (ordered/unordered) +is given by \.`\style <character>`, see section 1.4.5 in the +\optexmanual. Default type is unordered (bullets are used). + + +\secc Code blocks (verbatim texts) + +Code blocks are inline verbatim or display verbatim. + +\begitems +* \.`\begtt <ignored><eol><text>\endtt<ignored><eol>` processes `<text>` in + \"display verbatim mode", i.\,e. there are no special characters, each character + is processed without special interpretation, the <eol>s are end of lines. + The text at the same line after `\begtt` and after `\endtt` (if any) is + ignored. +* \.`\verbchar <character>` declares `<verbchar>`. By default, it is undeclared.\nl + New `\verbchar <character>` rewrites previous setting. The setting is + local in the group. +* Inline verbatim is enclosed in the pairs of `<verbchar>`s. + The text between two `<verbchar>`s is processed without special interpretation. + Only possibly <eol>s are replaced by space. + Example: + \begtt + %%:use + \verbchar` + Now, `$this %text ~\` is processed as inline verbatim. + \endtt + gives: Now, `$this %text ~\` is processed as inline verbatim. +* \.`\code{<text>}` processes `<text>` like inline verbatim, but + all `\<character>` are processed as `<character>`, specially `\{` and `\}` + are `{` and `}` but without taking them into `<balanced-text>` rule, + `\\` is `\` but do not create a `<control-sequence>`, etc. +\enditems + + +\secc Multiclolumns + +\.`\begmulti <number><space>` opens the group and \.`\endmulti` +closes the group. If output format allows multi-columns then +the text enclosed between `\begmulti <number><space>` and matching +`\endmulti` should be printed in `<number>` balanced columns. + + +\secc Links + +\begitems +* \.`\url{<text>}` creates `<text>` as an external link which points to `<text>`. + The `\<character>` is interpreted as `<character>` in `<text>` with one + exception: `\|` is ignored. +* \.`\ulink[<url>]{<text>}` creates `<text>` as an external link which points + to `<url>`. The `\<character>` is interpreted as `<character>` only in + `<url>` parameter. +* \.`\label[<label>]` sets the `<label>`. First following occurence of `\chap`, `\sec`, + `\secc`, `\caption` or `\eqmark` sets this `<label>` as bounded to its + position in the document. +* \.`\ref[<label>]` should create an internal link to the position given by + `\chap`, `\sec`, `\secc`, `\caption` or `\eqmark`, + if `[<label>]` is used as the parameter of this control sequence + else if `<label>` is bounded here by previous `\label[<label>]` + The visual aspect of the link + is not declared by OMLS because we don't suppose that the chapters, + sections, equations, etc.\ are automatically numbered by exactly the same way as in + \OpTeX/. A recommendation should be: create a simple sequence of numbers over + all internal links. +* \.`\pgref[<label>]` should be replaced by `??` if cnv-program generates single-page + output (like Html, Markdown). Unfortunately, we get the irrelevant phrases in the output: + \"{\tt The problem is shown at the page ??}". + Users can declare `%%:skip` for such cases. +* \.`\bib[<label>]` or `\bib[<label>]<o-space>=<o-space>{<ignored>}` should open the new bib + record. More exactly, it closes previous paragraph (if h-mode is current) + and opens new h-mode. Then prints an auto-generated reference number in + `[...]`. Following text is interpreted as a bib record until the h-mode ends. +* \.`\cite[<labels>]` should create internal links to corresponding bib + records generated by `\usebib` or by `\bib`. The `<labels>` is a comma-separated list + of labels used in `.bib` files or in `\bib` commands to indicate + the corresponding bib record. The labels should be replaced by auto-generated + reference numbers used in bib records. All reference numbers created by + single `\cite` should be enclosed by single `[...]`. These numbers are + internal links. If the cnv-program does not implement this complicated + bib machinery then `\cite[<labels>]` should print only `[<labels>]`. +* \.`\rcite[<labels>]` does the same as `\cite[<labels>]` but doesn't print + outer `[...]`. +* \.`\ecite[<label>]{<text>}` creates the link to corresponding bib record, + `<text>` is is hyperlinked (no the auto-generated reference number). +* \.`\maketoc` should create a list of titles from all `\chap`, `\sec` and `\secc` + used in the document if they are not preceded by \.`\notoc`. All lines in + this list should include internal links to the position where the corresponding title + is used. +\enditems + +\secc Tables + +\begitems +* \.`\caption/<letter>` opens a caption. More exactly, if current mode is + h-mode, then switch to v-mode first (i.e.\ close the current paragraph). + Then switch from v-mode to h-mode and put a <caption-head>. The following + text should be interpreted as the caption text until h-mode ends. + If <letter> is `t` then <caption-head> is `Table` followed + by an auto-generated number. If the <letter> is `f` then <caption-head> is + `Figure` followed by an auto-generated number. The configuration of + cnv-programs shoud allow different words than default `Table` or `Figure` (for + example, if another language is used). +* \.`\table<ignored>{<declaration>}{<data>}` should create a table. The fidelity + rate of created output depends heavily on the used cnv-program and the output + format. We don't suppose that all aspects of \OpTeX/ tables are implemented. + The following features are listed in their priority of implementation. + \begitems \style c + * Items in `<data>` are separated by `&`. + The last item in each row is separated by end-row separator: \.`\cr`, \.`\crl`, \.`\crll`, + \.`\crli`, \.`\crlli`, or \.`\crlp{<list>}`. If there are $n$ columns in + the table then we have $n-1$ `&` separators and one end-row separator + for each table row. + There can be an optional end-row separator at the first item in `<data>` and + it should be ignored. The `<data>` can end without the end-row separator, it + should be added here. + * Spaces around `&` and before end-row separator are ignored. + * \.`\noalign{<text>}` and \.`\tskip <dimen>` should be ignored. + * Colum declarators in <declaration> should be interpreted: `l` (left aligned), `c` (center + aligned), `r` (right aligned) or `p{<ignored>}` (paragraph-like item). + * The `<number><letter>` or `<number>{<text>}` should be interpreted as + `<number>`-times repeated `<letter>` or `<text>` in `<declaration>`. + * \.`\vspan<decimal-number>{<text>}` should be an item with only `<text>`. + * \.`\mspan<number>[<decl>]{<text>}` should create `<text>` as an item which + spans over `<number>` columns. It is used instead `<number>` real + items, i.e.\ `<number>`$-1$ separators `&` aren't used here. + * Rules in the table should be interpreted, i.e. `|` in <declaration> + should be not ignored and + various end-row separators should be distinguished (see \optexmanual, + section 1.4.6). + * The aligning of `p{<p-data>}` columns should be interpreded by reading + \.`\fL`, \.`\fR`, \.`\fC`, \.`\fS` and \.`\fX` control sequences in `<p-data>`. + See \optexmanual, section 1.4.6. + \enditems +\enditems + +\secc Footnotes, marginal notes + +\begitems +* \.`\fnote{<text>}` should create a footnote link as an auto-generated + reference number. + The `<text>` should be appended at the end of the document labeled by this + reference number. Another alternative (for Html output, for example): the mouse over + the reference number riases an auto-popup `<text>`. +* \.`\fnotemark<number>` should create a pointer to a next declared + footnote as auto-generated reference number. The `<text>` of the footnote is + declared after that by \.`\fnotetext{<text>}`. Exact behavior: if the + reference number of the last processed `\fnote` is $n$ then + `\fnotemark<number>` uses the value + $n+{}$`<number>` as its reference number. A set of `\fnotemark`s + is followed by an equally large set of `\fnotetext{<text>}`. First one + have reference number $n+1$, second $n+2$, etc. When whole set of `\fnotetext{<text>}` + is processed then $n$ is reset to the last reference number used here. +* \.`\mnote <ignored>{<text>}` should be created as auto-popup `<text>` or the `<text>` + is inserted at the margin. +\enditems + +\secc Tagging for index + +We don't suppose that the cnv-program can generate the alphabetically sorted +index. So, the markup for creating the index should be ignored: + +\begitems +* \.`\ii <word><space>` (where `<word>` is a sequence of non-space characters) + should be ignored. +* \.`\iid <word><space>` is `<word><space>` by default, but + if `,` or `.` follows after `<space>` then the `<space>` is removed. +\enditems + +\secc Logos + +\.`\TeX`, \.`\LuaTeX`, \.`\OpTeX`, \.`\LaTeX`, respectively \: +`TeX`, `LuaTeX`, `OpTeX`, `LaTeX`, respectively. If `/` follows +these control sequences then it is ignored. Other logos should be declared +in the configuration of the cnv-program. + +\secc What should be ignored + +\begitems +* \.`\def<text>{<text>}` and other variants with \.`\gdef`, \.`\edef`, \.`\xdef`. + Reason: user can insert a special definition in the `%%:text` part of the + document in order to solve a problem. But cnv-program should ignore~it. +* \.`\outlines{<text>}`, \.`\insertoutline{<text>}` and \.`\thisoutline{<text>}`. +\enditems + + +\sec[math] Math mode processing + +There are two math modes, inline: `$<formula>$` or display: `$$<formula>$$`. +We suppose that `<formula>` will be processed by MathJax or similar +software. So, the `<formula>` should be kept without changes in cnv-program +output, but there are exceptions: + +\begitems +* `$<sign><decimal-number>$` should be transformed to non-math text + `<sign><decimal-number>`. The `<sign>` is~`+` or~`-` or nothing. + The `<decimal-number>` can include `,` (comma) instead `.` (period). + If the `<sign>` is~`-` (character U+002D) then + it must be converted to `−` (character U+2212, math minus). +* `{\bbchar <text>}` should be converted to `\mathbb{<text>}`, because + MathJax doesn't understand `\bbchar`. `$\bbchar <text>$` should be + converted to `$\mathbb{<text>}$`. +* `{\frak <text>}` or `$\frak <text>$` \: + `\mathfrak{<text>}` or `$\mathfrak{<text>}$`. +* `{\script <text>}` or `$\script <text>$` \: + `\mathscr{<text>}` or `$\mathscr{<text>}$`. +* `\eqmark`, `\eqmark[<label>]` \: `\leqno (<num>)`, where `<num>` is + auto-generated number. Or it should be completely ignored. +* It is strongly recommended to allow users to declare another replacement + rules over `<formula>` in configuration files of cnv-programs. +\enditems + + +\sec Notes on various conversions + +The cnv-programs behave differently because output formats have different +concepts and are intended for different purposes. The following sections +mention the main differences for typical conversions. + +\secc To Html + +The Html document is one single page. If we want to split the document to more +pages, then we can use `%%:do html <action>` in positions where the document +should be split (the syntax of `<action>` depends on the used cnv-program.) + +The design of Html pages should be declared by CSS files. + +Pictures inserted by `\inspic` should be inserted into the Html page as +\code{<img src="...">}, so the picture files must be installed in +the webserver to render the Html page correctly in a web browser. + +The `\maketoc` used in the \OpTeX/ document means that the Table of contents should +be here. It should be generated by the cnv-program, two-pass processing is +needed because the cnv-program needs to read all titles of `\chap`, `\sec` and +`\secc`. Another approach is to read the `.ref` file produced by \OpTeX/. + + +\secc To Markdown + +Markdown source file is \"one-page document" too. The principles a +re similar to conversion to Html. + +\secc From Markdown + +The cnv-program which does such a reverse conversion should be very useful for +people they prefer even clearer markup than in \OpTeX/. + +\secc To \LaTeX + +\LaTeX/ gives the same main feature as \OpTeX/: it can generate PDF +output from a source file. But different macros, a different concept, and +a different markup are used. + +The main reason for such conversion is that journal editors +require \LaTeX/ source file, but user want to prepare their real document in +more comfortable (\OpTeX/) markup and with more simple macros. + +This conversion should keep almost all features. For example, the +`\pgref[<label>]` is converted to `\pageref{<label>}`. The cnv-program +needs not to generate a Table of contents, bibliography references, etc. Only +appropriate \LaTeX/ markup must be used. + +The contents of generated \LaTeX/ preamble should be configurable. + + +\secc From \LaTeX + +The reverse conversion from \LaTeX/ to \OpTeX/ can be usable +for people, they want to switch to creating their documents in \OpTeX/. + +The cnv-program must solve additional problem in this type of conversion. +There are various math \LaTeX/ environments, they must be converted to +plain~\TeX/ syntax of math typesetting. For example:\nl +`\begin{array}...\end{array}` \: `\matrix{...}`,\nl +`\begin{align*}...\end{align*}` \: `$$\eqalign{...}$$`\nl +`\frac{...}{...}` \: `{...\over...}`. + +\bye diff --git a/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf b/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf Binary files differindex aacd564a608..4bd55547cb0 100644 --- a/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf +++ b/Master/texmf-dist/doc/luatex/optex/optex-doc.pdf diff --git a/Master/texmf-dist/doc/luatex/optex/optex-doc.tex b/Master/texmf-dist/doc/luatex/optex/optex-doc.tex index 4ce127f9036..f8fcc45ca08 100644 --- a/Master/texmf-dist/doc/luatex/optex/optex-doc.tex +++ b/Master/texmf-dist/doc/luatex/optex/optex-doc.tex @@ -20,7 +20,7 @@ \tit Format Based on Plain \TeX/ and OPmac\fnotemark1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\hfill Version 0.19 +\hfill Version 1.00 \centerline{\it Petr Olšák, 2020, 2021} @@ -92,6 +92,8 @@ document \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf] \notoc\nonum \sec Contents \maketoc +\thisoutline {USER DOCUMENTATION} + \chap User documentation \input optex-userdoc diff --git a/Master/texmf-dist/doc/luatex/optex/optex-math.tex b/Master/texmf-dist/doc/luatex/optex/optex-math.tex index c36459f74ef..2fd21af218a 100644 --- a/Master/texmf-dist/doc/luatex/optex/optex-math.tex +++ b/Master/texmf-dist/doc/luatex/optex/optex-math.tex @@ -13,7 +13,7 @@ \def\new #1 {\mnote{\Red$\blacktriangleleft$\,\sans\setfontsize{at9pt}\rm#1}} \fixmnotes\right \enquotes -\activettchar` +\verbchar` \catcode`\<=13 \def<#1>{$\langle\hbox{\it#1\/}\rangle$} \everyintt={\catcode`\<=13 } @@ -47,7 +47,7 @@ \tit Typesetting Math with \OpTeX/ -\hfill Version 02, October 2020 +\hfill Version 03, January 2021 \author Petr Olšák @@ -1475,7 +1475,7 @@ $$ \eqalignno{ \secc[fams] Math families -\TeX/can use more than one math font in math mode. This was a +\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: diff --git a/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex b/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex index 2c0a71cc270..4ae25a9c7ec 100644 --- a/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex +++ b/Master/texmf-dist/doc/luatex/optex/optex-techdoc.tex @@ -6,6 +6,8 @@ \load [doc.opm] +\thisoutline {TECHNICAL DOCUMENTATION} + \chap Technical documentation This documentation is written in the source files `*.opm` between diff --git a/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex b/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex index 8f2fe4d3d3e..899b1d55aae 100644 --- a/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex +++ b/Master/texmf-dist/doc/luatex/optex/optex-userdoc.tex @@ -650,7 +650,7 @@ 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 +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 @@ -663,6 +663,8 @@ If the linked text have to be different than the URL, you can use `\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 @@ -683,6 +685,11 @@ the main level~0. These entries can be placed before the table of contents (crea 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 %%%%%%%%%% @@ -768,9 +775,9 @@ These letters can be combined by the `|` character (vertical line). Example July & yacht & k\$ 170 \crl} \endtt % -generates the following result: +generates the result: -\medskip +\vskip-\medskipamount \noindent\hfil\table{||lc|r||}{ \crl Month & commodity & price \crli \tskip2pt January & notebook & \$ 700 \cr @@ -902,29 +909,28 @@ You can use this for creating tables like in the following example: & 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} + \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 -The <number> parameter of \^`\vspan` must be one-digit number. -If you want to set more digits then use braces. -You can use non-integer values too if you feel that the -result is better, for example \^`\vspan{2.1}{text}`. +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. +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] +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}. @@ -935,7 +941,7 @@ 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 -\^`\activettchar``<char>`. For example \code{\\activettchar`} +\^`\verbchar``<char>`. For example \code{\\verbchar`} declares the character \code{`} for in-line verbatim markup. And you can use \code{`\\relax`} for @@ -974,7 +980,7 @@ 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 \^`\activettchar` or processed by the \~`\code` +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 @@ -997,7 +1003,7 @@ Each occurrence of ? will be changed to ! and vice versa. @ \endtt -The in-line verbatim surrounded by an `\activettchar` doesn't work in +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/). @@ -1556,10 +1562,11 @@ coordinates `<x>`, `<y>`. More exactly the left edge of its baseline is at that position. \new -The \^`\putpic` `<x> <y> <width> <height> {<image>}` puts the `<image>` of given +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 given. +You can write \^`\nospec` instead `<width>` or `<height>` if this parameter +is not specified. \sec Others %%%%%%%%%%% @@ -1795,7 +1802,7 @@ put it as the first command in your document: ~endblock' % end of block of text ~begtt' % start a verbatim text ~endtt' % end verbatim text -~activettchar' X % initialization character X for in-text verbatim +~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) @@ -1873,7 +1880,8 @@ documentation. \^`\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 -\^`\ignoreit` `<one>`, \^`\ignoresecond` `<one><two>`, \^`\usesecond` `<one><two>` ignores parameters.\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 @@ -1899,6 +1907,7 @@ documentation. \^`\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 |