From d65c208b161ffee9ce5343fdfdb17d00523cecae Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Tue, 20 Apr 2021 03:00:55 +0000 Subject: CTAN sync 202104200300 --- macros/optex/doc/omls.tex | 832 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 832 insertions(+) create mode 100644 macros/optex/doc/omls.tex (limited to 'macros/optex/doc/omls.tex') diff --git a/macros/optex/doc/omls.tex b/macros/optex/doc/omls.tex new file mode 100644 index 0000000000..bcc5749a51 --- /dev/null +++ b/macros/optex/doc/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><eof>` should be a title of the document. +* \.`\chap <title><eof>` or `\chap [<label>] <title><eof>` is the title of + first level. +* \.`\sec <title><eof>` or `\sec [<label>] <title><eof>` is the title of + second level. +* \.`\secc <title><eof>` or `\secc [<label>] <title><eof>` is the title of + third level. +* \.`\secl<level> <title><eof>` is the title of given level. +\enditems + +\secc Fonts + +\.`\rm` selects upright normal font (it is selected by default), \.`\it` selects +italic, \.`\bf` selects upright bold font, \.`\bi` selects bold italic and +\.`\tt` selects a monospaced font, \.`\em` select italic (if upright is current) or upright +(if italic is current). The font sizes or other font features are typically ignored +by cnv-programs. The actual font selection is closed at the end of the current group. +The groups are given: +\begitems +* explicitly by `{` and `}` characters (which are not delimiters of + parameters of known control sequences), +* implicitly: parameters of control sequences listed in table~\ref[groupcs] + are processed in a group and blocks of text enclosed by + `\begitems`...`\enditems`, `\begblock`...`\endblock`, `\begmulti`...`\endmulti` + are processed in a group. + Each item in `\table` is in a group. +\enditems + +\label[groupcs] +\caption/t Parameters of following control sequences are processed in a group. +\cskip +\begblock +`\caption`, +`\chap`, +`\fnote`, +`\mnote`, +`\sec`, +`\secc`, +`\tit`. +\endblock + +\secc Colors + +\.`\Red`, \.`\Green`, \.`\Blue`, \.`\Cyan`, \.`\Magenta`, \.`\Yellow`, \.`\White`, +\.`\Black`, and \.`\Brown` should select the given color of the font. The selection +is closed at the end of the current group (like font selectors). + +\secc Blockquotes + +The blockquote\fnote +{The terminology is borrowed from Markdown.} +is opened by \.`\begblock` and closed by \.`\endblock`. +Blockquotes can contain multiple paragraphs and can contain nested +blockquotes. + +\secc Lists + +The list is opened by \.`\begitems` and closed by \.`\enditems`. The `*` starts +a new item in this environment. Nested lists are allowed. + +The type of items (ordered/unordered) +is given by \.`\style <character>`, see section 1.4.5 in the +\optexmanual. Default type is unordered (bullets are used). + + +\secc Code blocks (verbatim texts) + +Code blocks are inline verbatim or display verbatim. + +\begitems +* \.`\begtt <ignored><eol><text>\endtt<ignored><eol>` processes `<text>` in + \"display verbatim mode", i.\,e. there are no special characters, each character + is processed without special interpretation, the <eol>s are end of lines. + The text at the same line after `\begtt` and after `\endtt` (if any) is + ignored. +* \.`\verbchar <character>` declares `<verbchar>`. By default, it is undeclared.\nl + New `\verbchar <character>` rewrites previous setting. The setting is + local in the group. +* Inline verbatim is enclosed in the pairs of `<verbchar>`s. + The text between two `<verbchar>`s is processed without special interpretation. + Only possibly <eol>s are replaced by space. + Example: + \begtt + %%:use + \verbchar` + Now, `$this %text ~\` is processed as inline verbatim. + \endtt + gives: Now, `$this %text ~\` is processed as inline verbatim. +* \.`\code{<text>}` processes `<text>` like inline verbatim, but + all `\<character>` are processed as `<character>`, specially `\{` and `\}` + are `{` and `}` but without taking them into `<balanced-text>` rule, + `\\` is `\` but do not create a `<control-sequence>`, etc. +\enditems + + +\secc Multicolumns + +\.`\begmulti <number><space>` opens the group and \.`\endmulti` +closes the group. If output format allows multi-columns then +the text enclosed between `\begmulti <number><space>` and matching +`\endmulti` should be printed in `<number>` balanced columns. + + +\secc Links + +\begitems +* \.`\url{<text>}` creates `<text>` as an external link which points to `<text>`. + The `\<character>` is interpreted as `<character>` in `<text>` with one + exception: `\|` is ignored. +* \.`\ulink[<url>]{<text>}` creates `<text>` as an external link which points + to `<url>`. The `\<character>` is interpreted as `<character>` only in + `<url>` parameter. +* \.`\label[<label>]` sets the `<label>`. First following occurence of `\chap`, `\sec`, + `\secc`, `\caption` or `\eqmark` sets this `<label>` as bounded to its + position in the document. +* \.`\ref[<label>]` should create an internal link to the position given by + `\chap`, `\sec`, `\secc`, `\caption` or `\eqmark`, + if `[<label>]` is used as the parameter of this control sequence + else if `<label>` is bounded here by previous `\label[<label>]` + The visual aspect of the link + is not declared by OMLS because we don't suppose that the chapters, + sections, equations, etc.\ are automatically numbered by exactly the same way as in + \OpTeX/. A recommendation should be: create a simple sequence of numbers over + all internal links. +* \.`\pgref[<label>]` should be replaced by `??` if cnv-program generates single-page + output (like Html, Markdown). Unfortunately, we get the irrelevant phrases in the output: + \"{\tt The problem is shown at the page ??}". + Users can declare `%%:skip` for such cases. +* \.`\bib[<label>]` or `\bib[<label>]<o-space>=<o-space>{<ignored>}` should open the new bib + record. More exactly, it closes previous paragraph (if h-mode is current) + and opens new h-mode. Then prints an auto-generated reference number in + `[...]`. Following text is interpreted as a bib record until the h-mode ends. +* \.`\cite[<labels>]` should create internal links to corresponding bib + records generated by `\usebib` or by `\bib`. The `<labels>` is a comma-separated list + of labels used in `.bib` files or in `\bib` commands to indicate + the corresponding bib record. The labels should be replaced by auto-generated + reference numbers used in bib records. All reference numbers created by + single `\cite` should be enclosed by single `[...]`. These numbers are + internal links. If the cnv-program does not implement this complicated + bib machinery then `\cite[<labels>]` should print only `[<labels>]`. +* \.`\rcite[<labels>]` does the same as `\cite[<labels>]` but doesn't print + outer `[...]`. +* \.`\ecite[<label>]{<text>}` creates the link to corresponding bib record, + `<text>` is is hyperlinked (no the auto-generated reference number). +* \.`\maketoc` should create a list of titles from all `\chap`, `\sec` and `\secc` + used in the document if they are not preceded by \.`\notoc`. All lines in + this list should include internal links to the position where the corresponding title + is used. +\enditems + +\secc Tables + +\begitems +* \.`\caption/<letter>` opens a caption. More exactly, if current mode is + h-mode, then switch to v-mode first (i.e.\ close the current paragraph). + Then switch from v-mode to h-mode and put a <caption-head>. The following + text should be interpreted as the caption text until h-mode ends. + If <letter> is `t` then <caption-head> is `Table` followed + by an auto-generated number. If the <letter> is `f` then <caption-head> is + `Figure` followed by an auto-generated number. The configuration of + cnv-programs shoud allow different words than default `Table` or `Figure` (for + example, if another language is used). +* \.`\table<ignored>{<declaration>}{<data>}` should create a table. The fidelity + rate of created output depends heavily on the used cnv-program and the output + format. We don't suppose that all aspects of \OpTeX/ tables are implemented. + The following features are listed in their priority of implementation. + \begitems \style c + * Items in `<data>` are separated by `&`. + The last item in each row is separated by end-row separator: \.`\cr`, \.`\crl`, \.`\crll`, + \.`\crli`, \.`\crlli`, or \.`\crlp{<list>}`. If there are $n$ columns in + the table then we have $n-1$ `&` separators and one end-row separator + for each table row. + There can be an optional end-row separator at the first item in `<data>` and + it should be ignored. The `<data>` can end without the end-row separator, it + should be added here. + * Spaces around `&` and before end-row separator are ignored. + * \.`\noalign{<text>}` and \.`\tskip <dimen>` should be ignored. + * Colum declarators in <declaration> should be interpreted: `l` (left aligned), `c` (center + aligned), `r` (right aligned) or `p{<ignored>}` (paragraph-like item). + * The `<number><letter>` or `<number>{<text>}` should be interpreted as + `<number>`-times repeated `<letter>` or `<text>` in `<declaration>`. + * \.`\vspan<decimal-number>{<text>}` should be an item with only `<text>`. + * \.`\mspan<number>[<decl>]{<text>}` should create `<text>` as an item which + spans over `<number>` columns. It is used instead `<number>` real + items, i.e.\ `<number>`$-1$ separators `&` aren't used here. + * Rules in the table should be interpreted, i.e. `|` in <declaration> + should be not ignored and + various end-row separators should be distinguished (see \optexmanual, + section 1.4.6). + * The aligning of `p{<p-data>}` columns should be interpreded by reading + \.`\fL`, \.`\fR`, \.`\fC`, \.`\fS` and \.`\fX` control sequences in `<p-data>`. + See \optexmanual, section 1.4.6. + \enditems +\enditems + +\secc Footnotes, marginal notes + +\begitems +* \.`\fnote{<text>}` should create a footnote link as an auto-generated + reference number. + The `<text>` should be appended at the end of the document labeled by this + reference number. Another alternative (for Html output, for example): the mouse over + the reference number riases an auto-popup `<text>`. +* \.`\fnotemark<number>` should create a pointer to a next declared + footnote as auto-generated reference number. The `<text>` of the footnote is + declared after that by \.`\fnotetext{<text>}`. Exact behavior: if the + reference number of the last processed `\fnote` is $n$ then + `\fnotemark<number>` uses the value + $n+{}$`<number>` as its reference number. A set of `\fnotemark`s + is followed by an equally large set of `\fnotetext{<text>}`. First one + have reference number $n+1$, second $n+2$, etc. When whole set of `\fnotetext{<text>}` + is processed then $n$ is reset to the last reference number used here. +* \.`\mnote <ignored>{<text>}` should be created as auto-popup `<text>` or the `<text>` + is inserted at the margin. +\enditems + +\secc Tagging for index + +We don't suppose that the cnv-program can generate the alphabetically sorted +index. So, the markup for creating the index should be ignored: + +\begitems +* \.`\ii <word><space>` (where `<word>` is a sequence of non-space characters) + should be ignored. +* \.`\iid <word><space>` is `<word><space>` by default, but + if `,` or `.` follows after `<space>` then the `<space>` is removed. +\enditems + +\secc Logos + +\.`\TeX`, \.`\LuaTeX`, \.`\OpTeX`, \.`\LaTeX`, respectively \: +`TeX`, `LuaTeX`, `OpTeX`, `LaTeX`, respectively. If `/` follows +these control sequences then it is ignored. Other logos should be declared +in the configuration of the cnv-program. + +\secc What should be ignored + +\begitems +* \.`\def<text>{<text>}` and other variants with \.`\gdef`, \.`\edef`, \.`\xdef`. + Reason: user can insert a special definition in the `%%:text` part of the + document in order to solve a problem. But cnv-program should ignore~it. +* \.`\outlines{<text>}`, \.`\insertoutline{<text>}` and \.`\thisoutline{<text>}`. +\enditems + + +\sec[math] Math mode processing + +There are two math modes, inline: `$<formula>$` or display: `$$<formula>$$`. +We suppose that `<formula>` will be processed by MathJax or similar +software. So, the `<formula>` should be kept without changes in cnv-program +output, but there are exceptions: + +\begitems +* `$<sign><decimal-number>$` should be transformed to non-math text + `<sign><decimal-number>`. The `<sign>` is~`+` or~`-` or nothing. + The `<decimal-number>` can include `,` (comma) instead `.` (period). + If the `<sign>` is~`-` (character U+002D) then + it must be converted to `−` (character U+2212, math minus). +* `{\bbchar <text>}` should be converted to `\mathbb{<text>}`, because + MathJax doesn't understand `\bbchar`. `$\bbchar <text>$` should be + converted to `$\mathbb{<text>}$`. +* `{\frak <text>}` or `$\frak <text>$` \: + `\mathfrak{<text>}` or `$\mathfrak{<text>}$`. +* `{\script <text>}` or `$\script <text>$` \: + `\mathscr{<text>}` or `$\mathscr{<text>}$`. +* `\eqmark`, `\eqmark[<label>]` \: `\leqno (<num>)`, where `<num>` is + auto-generated number. Or it should be completely ignored. +* It is strongly recommended to allow users to declare another replacement + rules over `<formula>` in configuration files of cnv-programs. +\enditems + + +\sec Notes on various conversions + +The cnv-programs behave differently because output formats have different +concepts and are intended for different purposes. The following sections +mention the main differences for typical conversions. + +\secc To Html + +The Html document is one single page. If we want to split the document to more +pages, then we can use `%%:do html <action>` in positions where the document +should be split (the syntax of `<action>` depends on the used cnv-program.) + +The design of Html pages should be declared by CSS files. + +Pictures inserted by `\inspic` should be inserted into the Html page as +\code{<img src="...">}, so the picture files must be installed in +the webserver to render the Html page correctly in a web browser. + +The `\maketoc` used in the \OpTeX/ document means that the Table of contents should +be here. It should be generated by the cnv-program, two-pass processing is +needed because the cnv-program needs to read all titles of `\chap`, `\sec` and +`\secc`. Another approach is to read the `.ref` file produced by \OpTeX/. + + +\secc To Markdown + +Markdown source file is \"one-page document" too. The principles a +re similar to conversion to Html. + +\secc From Markdown + +The cnv-program which does such a reverse conversion should be very useful for +people they prefer even clearer markup than in \OpTeX/. + +\secc To \LaTeX + +\LaTeX/ gives the same main feature as \OpTeX/: it can generate PDF +output from a source file. But different macros, a different concept, and +a different markup are used. + +The main reason for such conversion is that journal editors +require \LaTeX/ source file, but user want to prepare their real document in +more comfortable (\OpTeX/) markup and with more simple macros. + +This conversion should keep almost all features. For example, the +`\pgref[<label>]` is converted to `\pageref{<label>}`. The cnv-program +needs not to generate a Table of contents, bibliography references, etc. Only +appropriate \LaTeX/ markup must be used. + +The contents of generated \LaTeX/ preamble should be configurable. + + +\secc From \LaTeX + +The reverse conversion from \LaTeX/ to \OpTeX/ can be usable +for people, they want to switch to creating their documents in \OpTeX/. + +The cnv-program must solve additional problem in this type of conversion. +There are various math \LaTeX/ environments, they must be converted to +plain~\TeX/ syntax of math typesetting. For example:\nl +`\begin{array}...\end{array}` \: `\matrix{...}`,\nl +`\begin{align*}...\end{align*}` \: `$$\eqalign{...}$$`\nl +`\frac{...}{...}` \: `{...\over...}`. + +\bye -- cgit v1.2.3