| 1 |
\fontfam[lm] |
| 2 |
|
| 3 |
\adef<#1>{\ifcsname s:#1\endcsname |
| 4 |
\link[s:#1]{}{\Blue$\langle$\hbox{\it#1\/}$\rangle$}% |
| 5 |
\else {\Blue$\langle$\hbox{\it#1\/}$\rangle$}\fi} |
| 6 |
\everyintt={\catcode`<=13 \Red} |
| 7 |
\verbchar` |
| 8 |
\enlang |
| 9 |
\enquotes |
| 10 |
|
| 11 |
\def\r[#1]{\label[#1]\wlabel{\the\_itemnum}} |
| 12 |
\def\:{$\to$} |
| 13 |
\let\_narrowlastlinecentered=\ignoreit |
| 14 |
\_def\_printsecc#1{\_par |
| 15 |
\_abovetitle{\_penalty-200}{\_medskip\_smallskip} |
| 16 |
{\_seccfont \_noindent \_raggedright \_printrefnum[@\_quad]% |
| 17 |
\_label[\the\_secnum.\the\_seccnum]\wlabel{\the\_secnum.\the\_seccnum}#1\_nbpar}% |
| 18 |
\_nobreak \_belowtitle{\_medskip}% |
| 19 |
\_firstnoindent |
| 20 |
} |
| 21 |
\def\.`{\bgroup\catcode`\ =12 \scancs} |
| 22 |
\def\scancs#1{\egroup |
| 23 |
\immediate\_wref\Xknowncs{\string#1{\the\_secnum.\the\_seccnum}}% |
| 24 |
\ea`\string#1% |
| 25 |
} |
| 26 |
\def\printcs#1{\ea\printcsred\csstring#1;~\ref[#1] \ } |
| 27 |
\def\printcsred,#1;{{\Red\tt \bslash#1}} |
| 28 |
\def\printknowncs{\ifx\knowncslist\undefined \let\knowncslist=\empty \fi |
| 29 |
\ifx\knowncslist\empty TeX me again...\else |
| 30 |
\_dosorting\knowncslist \ea\xargs \ea\printcs \knowncslist;\fi} |
| 31 |
|
| 32 |
\def\~`<#1>`{<#1>\sxdef{s:#1}{}\dest[s:#1]} |
| 33 |
|
| 34 |
\refdecl{ |
| 35 |
\def\knowncslist{}^^J |
| 36 |
\def\Xknowncs#1#2{% |
| 37 |
\sxdef{,\csstring#1}{#2}% |
| 38 |
\global\ea\addto\ea\knowncslist\ea{\csname,\csstring#1\endcsname}% |
| 39 |
} |
| 40 |
} |
| 41 |
\sdef{_item:c}{\pdfsave\llap{\pdfscale{1.3}{1.3}$\circ$\enspace}\pdfrestore} |
| 42 |
|
| 43 |
%\parindent=15pt \iindent=\parindent \ttindent=\parindent |
| 44 |
%\ttindent=0pt |
| 45 |
\everylist={\advance\ttindent by-1em} |
| 46 |
\hyperlinks \Green \Green |
| 47 |
\ifx\_partokenset\undefined |
| 48 |
\def\cskip{\par\nobreak} |
| 49 |
\else |
| 50 |
\def\cskip{\_par\nobreak} |
| 51 |
\fi |
| 52 |
|
| 53 |
\def\begblock{\medskip\hbox\bgroup\vrule\vbox\bgroup\hrule\smallskip |
| 54 |
\_fnset\leftskip=\parindent \rightskip=\parindent \medskip\noindent} |
| 55 |
\def\endblock{\medskip\hrule\egroup\vrule\egroup} |
| 56 |
|
| 57 |
\def\raggedright{\rightskip=10pt plus1fil\relax} |
| 58 |
\def\optexmanual{\ulink[http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf]{\OpTeX/ manual}} |
| 59 |
|
| 60 |
\titskip=1cm |
| 61 |
|
| 62 |
\hfill Version 0.1 |
| 63 |
|
| 64 |
\tit \OpTeX/ Markup Language Standard |
| 65 |
|
| 66 |
{\it\hfil Petr Olšák, 2021}\bigskip |
| 67 |
|
| 68 |
The \OpTeX/ markup language standard (OMLS) declares a list of control |
| 69 |
sequences used in \OpTeX/ documents including their syntax and semantics. The |
| 70 |
listed control sequences in OMLS in section~\ref[listcs] in table~\ref[alistcs] |
| 71 |
are called {\it known} and other control sequences are {\it unknown}. |
| 72 |
|
| 73 |
The main reason for OMLS is to give instructions on how to program converters |
| 74 |
from \OpTeX/ documents to another formats (Html, Markdown, \LaTeX/) or how |
| 75 |
to interpret the \OpTeX/ document sources in such applications as |
| 76 |
{\tt texcount} or text editors\fnote |
| 77 |
{We suppose advanced editor features: color highlighting, sections/chapters folding, |
| 78 |
auto-completions, etc.}. |
| 79 |
These converters and applications are called {\it cnv-programs} in this document. |
| 80 |
|
| 81 |
We suppose that if you need absolute control over the typography of the |
| 82 |
document when it is converted to PDF pages, then you use \OpTeX/ itself. If |
| 83 |
you need to create other formats of the same document then you can use a |
| 84 |
cnv-program which accepts OMLS. The result is a document without |
| 85 |
typographical instructions like dimensions of pages, margins, paginations |
| 86 |
and headers, selection of a font-family, dimensions of the fonts, etc.\ You can |
| 87 |
imagine the result of such a conversion as a single Html page where more |
| 88 |
typographical features can be controlled in a different way, for example by |
| 89 |
an external CSS file. This is a reason why control sequences like `\fontfam` or |
| 90 |
`\margins` are ignored by cnv-programs. |
| 91 |
|
| 92 |
Obviously, \TeX/ and \OpTeX/ itself gives possibility to declare various |
| 93 |
input formats for various purposes. Sometimes (in very special cases) there |
| 94 |
exists a good reason to declare a different and special input format by |
| 95 |
\TeX/ macros. But if the source of the document respects the OMLS then it is |
| 96 |
reasonably transformable to other formats by cnv-programs. We hope that |
| 97 |
OMLS-ready documents cover a very large set of typical documents used these |
| 98 |
days. |
| 99 |
|
| 100 |
We suppose that cnv-programs work internally with strings of source lines |
| 101 |
without tokenization. This is one of the great differences in processing the |
| 102 |
document directly by \OpTeX/ and using a cnv-program. The second difference is |
| 103 |
that the expansion process of macros is not implemented in cnv-programs in |
| 104 |
its full range. We respect that the result of cnv-programs will be different |
| 105 |
than from processing directly by \OpTeX/. But this is not a bug, this is |
| 106 |
the feature. We concentrate on the fixed syntax and semantics given by OMLS of the |
| 107 |
\OpTeX/ document and we throw behind the head the typographical |
| 108 |
exactness of the document which can be done only directly by \TeX/ (and it is |
| 109 |
exactly described in \TeX/book, for example). |
| 110 |
|
| 111 |
\notoc\nonum\sec Table of contents |
| 112 |
|
| 113 |
\begmulti 2 |
| 114 |
\maketoc |
| 115 |
\endmulti |
| 116 |
\vfil\break |
| 117 |
|
| 118 |
\sec Syntactical rules |
| 119 |
|
| 120 |
The syntactical elements are described as strings here. No \TeX/'s tokenization is |
| 121 |
taken into account. The rule with a smaller number has precedence. |
| 122 |
|
| 123 |
\begitems \style n |
| 124 |
* end of line or end of file \: \~`<eol>`.\r[eol] |
| 125 |
* `%%:` at beginning of the line \: \~`<cnv-declarator>`, see section~\ref[cnv-decl]. |
| 126 |
* `<cnv-declarator><text><eol>` is interpreted specially. |
| 127 |
* space or a tab-character \: \~`<space>`. |
| 128 |
* non-empty sequence of `<space>`s \: \~`<spaces>`.\r[spcs] |
| 129 |
* an empty line or a line only with `<spaces>` \: \~`<empty-line>`. |
| 130 |
* a character `a`--`z` or `A`--`Z` \: \~`<letter>`. |
| 131 |
* a `<letter>` or `_` \: \~`<specletter>`. |
| 132 |
* a character different from previous rule or `<eol>` or `<spaces>` \: \~`<non-specletter>` |
| 133 |
* `\<non-specletter>` \: \~`<singlechar-control-sequence>`.\r[scs] |
| 134 |
* a non-empty sequence of `<specletter>`s \: \~`<letters-seq>`. |
| 135 |
* `\<letters-seq><non-specletter>` \: \~`<multiletter-control-sequence>``<non-specletter>`. |
| 136 |
* `%<text><eol>` \: `<comment>` and it is completely ignored including `<eol>`.\r[com] |
| 137 |
* `<spaces>` at beginning of the line marks that the line as {\it indented}. |
| 138 |
* `<spaces>` at beginning of the line \: are ignored.\r[bspace] |
| 139 |
* `<spaces><eol>` or `<eol>` \: `<spaces>`.\r[eolrm] |
| 140 |
* `<multileter-control-sequence><spaces>` \: `<multileter-control-sequence>`.\r[csspace] |
| 141 |
* `<multiletter-control-sequence>` or `<singlechar-control-sequence>` \: \~`<control-sequence>`.\r[cs] |
| 142 |
* `<spaces>` \: `<space>`.\r[sspace] |
| 143 |
* `~` \: non-breakable space. |
| 144 |
* text where all pairs `{` and `}` match at arbitrary level \: \~`<balanced-text>`.\r[balt] |
| 145 |
* `{<balanced-text>}` can be interpreted as a parameter of a `<control-sequence>`, see section~\ref[listcs]. |
| 146 |
* The `{` alone not used by previous rule opens a group and the `}` alone closes the same group.\r[group] |
| 147 |
* There are two main modes: h-mode, v-mode\fnote |
| 148 |
{this is great simplification of real \TeX/ modes.}. |
| 149 |
The document processing starts in v-mode. |
| 150 |
* In v-mode: a `<non-space>` character or a control sequence listed |
| 151 |
in table~\ref[vtohmode] switches to h-mode. |
| 152 |
* In h-mode: an `<empty-line>` or a control sequence listed in table~\ref[htovmode] switches to v-mode.\r[htov] |
| 153 |
* The switching from v-mode to h-mode \: a paragraph begins. |
| 154 |
* The switching from h-mode to v-mode \: the current paragraph ends. |
| 155 |
* `$<text>$` or `$$<text>$$` \: process `<text>` in math-mode, see section~\ref[math]. |
| 156 |
* a non-empty sequence of digits with optional `+` or `-` in the front \: \~`<number>`. |
| 157 |
* `<number>` with optional dot inside the sequence of digits \: \~`<decimal-number>`. |
| 158 |
* a pair of letters listed in the table~\ref[tex-units] \: \~`<tex-unit>`. |
| 159 |
* optional space, i.e.\ `<space>` or nothing \: \~`<o-space>`. |
| 160 |
* `<decimal-number><o-space><tex-unit><o-space>` \: \~`<dimen>`. |
| 161 |
* `<control-sequence>` not listed in table~\ref[alistcs] nor in configuration \: \~`<unknown-control-sequence>`.\r[unkncs] |
| 162 |
* `=<o-space>` or `<o-space>` \: \~`<o-equal>`. |
| 163 |
* `<unknown-control-sequence><o-equal><dimen>` \: should be completely ignored.\r[eqdim] |
| 164 |
* `<unknown-control-sequence><o-equal><number>` \: should be completely ignored. |
| 165 |
* `<unknown-control-sequence>=<o-space>{<balanced-text>}` \: should be completely ignored. |
| 166 |
* `<unknown-control-sequence>[<balanced-text>]` \: should be completely ignored.\r[ibkt] |
| 167 |
* `<unknown-control-sequence>` \: should be ignored.\r[ignore] |
| 168 |
* `<control-sequence>`s are processed as described in section~\ref[listcs] or |
| 169 |
by a configuration of the cnv-program. |
| 170 |
\enditems |
| 171 |
|
| 172 |
\bigskip |
| 173 |
\label[vtohmode]\caption/t |
| 174 |
List of control sequences which switch from v-mode to h-mode. |
| 175 |
\cskip |
| 176 |
\begblock |
| 177 |
`\`<space>, |
| 178 |
`\hfil`, |
| 179 |
`\hfill`, |
| 180 |
`\hskip`, |
| 181 |
`\hss`, |
| 182 |
`\indent`, |
| 183 |
`\leavevmode`, |
| 184 |
`\noindent`, |
| 185 |
`\quad`, |
| 186 |
`\qquad`, |
| 187 |
`\vrule`. |
| 188 |
\endblock |
| 189 |
|
| 190 |
\bigskip |
| 191 |
\label[htovmode]\caption/t |
| 192 |
List of control sequences which switch from h-mode to v-mode. |
| 193 |
\cskip |
| 194 |
\begblock |
| 195 |
`\begblock`, |
| 196 |
`\begitems`, |
| 197 |
`\begmulti`, |
| 198 |
`\begtt`, |
| 199 |
`\bib`, |
| 200 |
`\bigskip`, |
| 201 |
`\bye`, |
| 202 |
`\caption`, |
| 203 |
`\chap`, |
| 204 |
`\cskip`, |
| 205 |
`\end`, |
| 206 |
`\endblock`, |
| 207 |
`\enditems`, |
| 208 |
`\endmulti` |
| 209 |
`\hrule`, |
| 210 |
`\medskip`, |
| 211 |
`\par`, |
| 212 |
`\sec`, |
| 213 |
`\secc`, |
| 214 |
`\secl`, |
| 215 |
`\smallskip`, |
| 216 |
`\vfil`, |
| 217 |
`\vskip`. |
| 218 |
\endblock |
| 219 |
|
| 220 |
\bigskip |
| 221 |
\label[tex-units]\caption/t |
| 222 |
List of \TeX/ units. |
| 223 |
\cskip |
| 224 |
\begblock |
| 225 |
`bp`, |
| 226 |
`cc`, |
| 227 |
`cm`, |
| 228 |
`dd`, |
| 229 |
`em`, |
| 230 |
`ex`, |
| 231 |
`in`, |
| 232 |
`mm`, |
| 233 |
`pc`, |
| 234 |
`pt`, |
| 235 |
`sp`. |
| 236 |
\endblock |
| 237 |
|
| 238 |
\nonum\secc Examples |
| 239 |
|
| 240 |
\begitems |
| 241 |
* `\%` is `<control-sequence>` by rules \ref[scs], \ref[cs]. It does not start |
| 242 |
comment, because rule \ref[scs] has precedence before rule \ref[com]. |
| 243 |
* `\%<space>`: the `<space>` is kept, but `\foo<space>`: the space is removed |
| 244 |
by rule~\ref[csspace]. |
| 245 |
* `wordA<spaces><eol><spaces>wordB` is `wordA<space>wordB` by rules~\ref[bspace], |
| 246 |
\ref[eolrm], and~\ref[sspace]. |
| 247 |
* `\kern-3pt` should be ignored, because `\kern` is `<unknown-control-sequence>` and rule |
| 248 |
\ref[eqdim] is applied. |
| 249 |
* `\vskip42mm` should finalize paragraph in h-mode by rule~\ref[htov] and then it |
| 250 |
is ignored by rule~\ref[eqdim] because `\vskip` is |
| 251 |
`<unknown-control-sequence>` not listed in table~\ref[alistcs]. |
| 252 |
* `\typosize[12/16]` is ignored by rule~\ref[ibkt]. |
| 253 |
* `\foo{text}` is `{text}` (i.e. `text` in a group) by rules~\ref[ignore] and~\ref[group]. |
| 254 |
\enditems |
| 255 |
|
| 256 |
\sec Scanning parameters |
| 257 |
|
| 258 |
If a control sequence listed in rules above or in the section~\ref[listcs] |
| 259 |
has a parameter, the parameter is scanned |
| 260 |
as a string with interpretation only those rules which are needed to |
| 261 |
determine the boundary of the parameters. For example `\tit <title><eol>` |
| 262 |
applies only rule~\ref[eol] during scanning the parameter, i.e.\ `<title>` |
| 263 |
is a string telemetered by the end of the line or the end of the file. |
| 264 |
Or `\fnote{<balanced-text>}` applies only rule~\ref[balt]. |
| 265 |
|
| 266 |
If the parameter is in the format `{<something>}` then the `<something>` is |
| 267 |
always meant as `<balanced-text>`. We don't specify the type `<balanced-text>` |
| 268 |
explicitly here, so we refer to `\fnote{<text>}` and not |
| 269 |
`\fnote{<balanced-text>}`, for example. |
| 270 |
|
| 271 |
The spaces before the scanned parameter are optional |
| 272 |
and they are ignored. Spaces inside `{`...`}` are not ignored. |
| 273 |
|
| 274 |
If the parameter is in the format `{<something>}` and the first non-space |
| 275 |
character is not `{` then the parameter is this first non-space character or |
| 276 |
a `<control-sequence>` if the first non-space character is~`\`. For example |
| 277 |
`\fnote a` is equal to `\fnote{a}`. The difference from this rule is given |
| 278 |
for `\input`, `\verbinput`,`\inspic` and `\inkinspic` control sequences in |
| 279 |
section~\ref[listcs]. |
| 280 |
|
| 281 |
If the parameter is scanned as a string already then |
| 282 |
all syntactical rules are applied when it is used. For example: |
| 283 |
\begtt |
| 284 |
\tit This is a title |
| 285 |
\endtt |
| 286 |
the parameter is scanned as `This is a title` and the rules~\ref[spcs] |
| 287 |
and~\ref[sspace] are applied when it is used. |
| 288 |
|
| 289 |
|
| 290 |
\sec Declaration and text parts of the document |
| 291 |
|
| 292 |
A typical \OpTeX/ document has two parts. A declaration part, where |
| 293 |
macros are defined by `\def` and friends, fonts and sizes are declared, etc. |
| 294 |
This part should be ignored by cnv-programs. |
| 295 |
The second part includes the document text with a markup using well-declared control |
| 296 |
sequences. The cnv-program has to interpret the second part. |
| 297 |
|
| 298 |
So, the cnv-program starts in declaration-skipping mode and it switches to |
| 299 |
the text mode later. |
| 300 |
|
| 301 |
When cnv-program is in declaration-skipping mode then all indented lines are |
| 302 |
ignored. And lines which begins by `}` or by a <control-sequence> not listed |
| 303 |
in table~\ref[textopen] are ignored too. |
| 304 |
|
| 305 |
If the line begins by a character other than `}` or by a <control-sequence> |
| 306 |
listed in table~\ref[textopen] then cnv-program switches to text mode. All |
| 307 |
texts are interpreted from this line including this one. |
| 308 |
|
| 309 |
User can say explicitly where the second part of the document starts by |
| 310 |
`%%:text` given at beginning of a line. Moreover, if `%%:decl` is given at |
| 311 |
beginning of a line, then all text between `%%:decl` and `%%:text` is |
| 312 |
ignored, only other possible `<cnv-declarator>`s are processed here. |
| 313 |
It means that the declaration part and the text part of the document can be |
| 314 |
simply determined by the pair `%%:decl` and `%%:text`. |
| 315 |
|
| 316 |
\bigskip |
| 317 |
\label[textopen]\caption/t |
| 318 |
List of control sequences which start the text mode. |
| 319 |
\cskip |
| 320 |
\begblock \raggedright |
| 321 |
`\address`, |
| 322 |
`\begblock`, |
| 323 |
`\begitems`, |
| 324 |
`\begmulti`, |
| 325 |
`\begtt`, |
| 326 |
`\bf`, |
| 327 |
`\bi`, |
| 328 |
`\bib`, |
| 329 |
`\caption`, |
| 330 |
`\cite`, |
| 331 |
`\clipinoval`, |
| 332 |
`\clipincircle`, |
| 333 |
`\ecite`, |
| 334 |
`\fnote`, |
| 335 |
`\frame`, |
| 336 |
`\hfil`, |
| 337 |
`\hfill`, |
| 338 |
`\ii`, |
| 339 |
`\iid`, |
| 340 |
`\incircle`, |
| 341 |
`\inkinspic`, |
| 342 |
`\inoval`, |
| 343 |
`\inspic`, |
| 344 |
`\it`, |
| 345 |
`\LaTeX`, |
| 346 |
`\LuaTeX`, |
| 347 |
`\maketoc`, |
| 348 |
`\mnote`, |
| 349 |
`\OpTeX`, |
| 350 |
`\putpic`, |
| 351 |
`\puttext`, |
| 352 |
`\rcite`, |
| 353 |
`\rm`, |
| 354 |
`\rotbox`, |
| 355 |
`\sec`, |
| 356 |
`\secc`, |
| 357 |
`\secl`, |
| 358 |
`\table`, |
| 359 |
`\TeX`, |
| 360 |
`\tit`, |
| 361 |
`\usebib`, |
| 362 |
`\verbinput`. |
| 363 |
\endblock |
| 364 |
|
| 365 |
|
| 366 |
\sec[cnv-decl] The `%%:` declarators |
| 367 |
|
| 368 |
The `%%:` declarators are ignored when the document is processed by \TeX/ |
| 369 |
but they can give instructions to cnv-programs. The `%%:` must be placed at |
| 370 |
beginning of the line. The list of `%%:` declarators follows: |
| 371 |
|
| 372 |
\begitems |
| 373 |
* `%%:decl` -- the following text is ignored until `%%:text` occurs. Only |
| 374 |
other `%%:` declarators are interpreted. |
| 375 |
* `%%:text` -- the following text must be interpreted in text mode. |
| 376 |
* `%%:to <format> <config-file>` -- if the cnv-program converts to the |
| 377 |
<format> then it has to use the <config-file>. For example: |
| 378 |
\begtt |
| 379 |
%%:to html html-mydocument.cfg |
| 380 |
%%:to markdown markdown-mydocument.cfg |
| 381 |
%%:to latex preamble-mydocument.cfg |
| 382 |
\endtt |
| 383 |
The language of the config files are not a part of this standard, we |
| 384 |
suppose something to be natural for used cnv-program. The config file should |
| 385 |
give additional rules for interpreting control sequences not listed in the |
| 386 |
section~\ref[listcs] (see rule~\ref[unkncs]). For example a tool for |
| 387 |
defining a behavior of unknown control sequences can be here. |
| 388 |
These definitions can depend on the converted document and on the output |
| 389 |
format and they can be given in the configuration files. |
| 390 |
* `%%:app <application> <config-file>` -- behaves like `%%:to` but the |
| 391 |
cnv-program name instead output format is given here. |
| 392 |
* `%%:do <format-or-app> <action>` -- does an `<action>` if `<format-or-app>` |
| 393 |
is output format or used cnv\hbox{-}program name. The `<action>` syntax depends |
| 394 |
on used cnv-program and it typically does a change in its configuration or |
| 395 |
give a command to it. |
| 396 |
* `%%:skip <formats-or-apps>` -- ignores all following lines until another `%%:` occurs |
| 397 |
if the output format or application name is included in the `<formats-or-apps>` |
| 398 |
space-separated list. Example: |
| 399 |
\begtt |
| 400 |
%%:skip html markdown |
| 401 |
This text is not interpreted when Html or Markdown output is generated. |
| 402 |
%%: |
| 403 |
\endtt |
| 404 |
If the `<formats-or-apps>` is empty then the `%%:skip` is applied for |
| 405 |
each cnv-program and for each output. |
| 406 |
* `%%:if <formats-or-apps>` -- processes following lines until another `%%:` |
| 407 |
only if the output format or application name is included in the |
| 408 |
`<formats-or-apps>` space-separated list. Other cnv-programs or output formats |
| 409 |
not mentioned here skip these lines. Note that \TeX/ processes such lines always. |
| 410 |
But you can use `\ignoreit{<text>}` which is processed as |
| 411 |
`{<text>}` by cnv-programs (see rule~\ref[ignore]) but it is ignored by \OpTeX. |
| 412 |
Example: |
| 413 |
\begtt |
| 414 |
%%:if html latex |
| 415 |
\ignoreit{\input{file.tex}} |
| 416 |
%%: |
| 417 |
\endtt |
| 418 |
The `file.tex` in this example is processed only if \LaTeX/ or Html output is generated. |
| 419 |
* `%%:use` -- the next single line is fully interpreted unless cnv-program ignores |
| 420 |
declarations by `%%:decl` or because it is in declaration-skipping mode. |
| 421 |
Example: |
| 422 |
\begtt |
| 423 |
%%:use |
| 424 |
\verbchar` \picdir={img/} |
| 425 |
\endtt |
| 426 |
The example shows how cnv-program is able to read `\verbchar` or |
| 427 |
`\picdir` settings in the declaration\hbox{-}skipping mode although these control |
| 428 |
sequences are not listed in table~\ref[textopen]. |
| 429 |
* `%%:quotes <qql> <qqr> <ql> <qr>` -- declares \~`<qql>` and \~`<qqr>` (left |
| 430 |
and right double quotation marks), \~`<ql>` and \~`<qr>` (left and right single |
| 431 |
quotation mark). They are used when `\"` or `\'` control sequences are |
| 432 |
processed. Default: unset, i.e.\ `\"` and `\'` are interpreted as |
| 433 |
unknown control sequences. |
| 434 |
\enditems |
| 435 |
|
| 436 |
|
| 437 |
\sec[listcs] List of known control sequences |
| 438 |
|
| 439 |
The phrase \"should be" is used very often when the interpretation of |
| 440 |
control sequences is declared here. It means that this is only a common |
| 441 |
interpretation, but differences are possible due to the type of the output |
| 442 |
format and used cnv-program. For example, when we convert to \LaTeX\, then |
| 443 |
`\-` and `\/` are not ignored but they are re-written without change to the |
| 444 |
output of the \LaTeX/ source file. |
| 445 |
|
| 446 |
\bigskip |
| 447 |
\label[alistcs] |
| 448 |
\caption/t List of known control sequences alphabetically sorted. |
| 449 |
\cskip |
| 450 |
\begblock |
| 451 |
\raggedright \printknowncs |
| 452 |
\endblock |
| 453 |
|
| 454 |
|
| 455 |
\secc Character-like control sequences |
| 456 |
|
| 457 |
\begitems |
| 458 |
* \.`\%`, \.`\$`, \.`\&`,\.`\#` respectively \: should be normal characters |
| 459 |
`%`, `$`, `&`, `#` respectively. |
| 460 |
* \.`\bslash` \: normal character `\`. |
| 461 |
* \.`\space`, `\<space>`, `\<eol>` \: space. |
| 462 |
* `\,` \: should be small space or space. |
| 463 |
* \.`\quad`, \.`\qquad` \: should be bigger space or more spaces. |
| 464 |
* \.`\-`, \.`\/` \: should be ignored. |
| 465 |
* \.`\"<text>"` or \.`\'<text>'` \: `<qql><text><qqr>` or `<ql><text><qr>`, |
| 466 |
only if `%%:quotes` are set. |
| 467 |
\enditems |
| 468 |
|
| 469 |
\secc Input files |
| 470 |
|
| 471 |
\begitems |
| 472 |
* \.`\input {<file-name>}` or `\input <file-name><space>` should redirect the |
| 473 |
input to given file. At the end of the input-ed file or at \.`\endinput` the |
| 474 |
reading of the current file continues. The file is read from the current |
| 475 |
directory, but the <file-name> should include the full path to the file |
| 476 |
or relative path starting from the current directory. First, the file |
| 477 |
`<file-name>.tex` is tried to read and if it doesn't exist then |
| 478 |
the file `<file-name>` is read. |
| 479 |
* \.`\picdir <o-equal>{<text>}` saves `<text>` to `<picdir-value>`. By |
| 480 |
default, `<picdir-value>` is empty. |
| 481 |
* \.`\inspic {<file-name>}` or `\inspic <file-name><space>` should include the |
| 482 |
given picture from the `<picdir-value><file-name>`. |
| 483 |
* \.`\inkinspic {<file-name>}` or `\inkinspic <file-name><space>` behaves like |
| 484 |
`\inspic`. |
| 485 |
* \.`\verinput <ignore> (<lines>) <file-name><space>` should include the |
| 486 |
<file-name> (only given lines) as a verbatim text, i.\,e. without any |
| 487 |
syntactical interpretation. |
| 488 |
* \.`\usebib/<letter> (<style>) <file-names>` should use files from |
| 489 |
`<file-names>` to generate the list of bib references. The `<file-names>` |
| 490 |
is comma separated list (the `.bib` extension is appended to |
| 491 |
each such file name). Only cited bib records should be used in this |
| 492 |
bib-references, i.e. their label must be used in a `\cite[<labels>]` or |
| 493 |
`\rcite[<labels>]` or `\ecite[<label>]`. |
| 494 |
What bib fields are used in bib records depends on the cnv-program and |
| 495 |
on its configuration. Maybe, simple cnv-programs should generate nothing here. |
| 496 |
\enditems |
| 497 |
|
| 498 |
\secc Titles |
| 499 |
|
| 500 |
\begitems |
| 501 |
* \.`\tit <title><eol>` should be a title of the document. |
| 502 |
* \.`\chap <title><eol>` or `\chap [<label>] <title><eof>` is the title of |
| 503 |
first level. |
| 504 |
* \.`\sec <title><eol>` or `\sec [<label>] <title><eof>` is the title of |
| 505 |
second level. |
| 506 |
* \.`\secc <title><eol>` or `\secc [<label>] <title><eof>` is the title of |
| 507 |
third level. |
| 508 |
* \.`\secl<level> <title><eol>` is the title of given level. |
| 509 |
\enditems |
| 510 |
|
| 511 |
\secc Fonts |
| 512 |
|
| 513 |
\.`\rm` selects upright normal font (it is selected by default), \.`\it` selects |
| 514 |
italic, \.`\bf` selects upright bold font, \.`\bi` selects bold italic and |
| 515 |
\.`\tt` selects a monospaced font, \.`\em` select italic (if upright is current) or upright |
| 516 |
(if italic is current). The font sizes or other font features are typically ignored |
| 517 |
by cnv-programs. Selection of font is local to a group (i.e. should be reverted |
| 518 |
at the end of the current group). |
| 519 |
The groups are given: |
| 520 |
\begitems |
| 521 |
* explicitly by `{` and `}` characters (which are not delimiters of |
| 522 |
parameters of known control sequences), |
| 523 |
* implicitly: parameters of control sequences listed in table~\ref[groupcs] |
| 524 |
are processed in a group and blocks of text enclosed by |
| 525 |
`\begitems`...`\enditems`, `\begblock`...`\endblock`, `\begmulti`...`\endmulti` |
| 526 |
are processed in a group. |
| 527 |
Each item in `\table` is in a group. |
| 528 |
\enditems |
| 529 |
|
| 530 |
\label[groupcs] |
| 531 |
\caption/t Parameters of following control sequences are processed in a group. |
| 532 |
\cskip |
| 533 |
\begblock |
| 534 |
`\caption`, |
| 535 |
`\chap`, |
| 536 |
`\fnote`, |
| 537 |
`\mnote`, |
| 538 |
`\sec`, |
| 539 |
`\secc`, |
| 540 |
`\tit`. |
| 541 |
\endblock |
| 542 |
|
| 543 |
\secc Colors |
| 544 |
|
| 545 |
\.`\Red`, \.`\Green`, \.`\Blue`, \.`\Cyan`, \.`\Magenta`, \.`\Yellow`, \.`\White`, |
| 546 |
\.`\Black`, and \.`\Brown` should select the given color of the font. The selection |
| 547 |
is closed at the end of the current group (like font selectors). |
| 548 |
|
| 549 |
\secc Blockquotes |
| 550 |
|
| 551 |
The blockquote\fnote |
| 552 |
{The terminology is borrowed from Markdown.} |
| 553 |
is opened by \.`\begblock` and closed by \.`\endblock`. |
| 554 |
Blockquotes can contain multiple paragraphs and can contain nested |
| 555 |
blockquotes. |
| 556 |
|
| 557 |
\secc Lists |
| 558 |
|
| 559 |
The list is opened by \.`\begitems` and closed by \.`\enditems`. The `*` starts |
| 560 |
a new item in this environment. Nested lists are allowed. |
| 561 |
|
| 562 |
The type of items (ordered/unordered) |
| 563 |
is given by \.`\style <character>`, see section 1.4.5 in the |
| 564 |
\optexmanual. Default type is unordered (bullets are used). |
| 565 |
|
| 566 |
|
| 567 |
\secc Code blocks (verbatim texts) |
| 568 |
|
| 569 |
Code blocks are inline verbatim or display verbatim. |
| 570 |
|
| 571 |
\begitems |
| 572 |
* \.`\begtt <ignored><eol><text>\endtt<ignored><eol>` processes `<text>` in |
| 573 |
\"display verbatim mode", i.\,e. there are no special characters, each character |
| 574 |
is processed without special interpretation, the <eol>s are end of lines. |
| 575 |
The text at the same line after `\begtt` and after `\endtt` (if any) is |
| 576 |
ignored. |
| 577 |
* \.`\verbchar <character>` declares `<verbchar>`. By default, it is undeclared.\nl |
| 578 |
New `\verbchar <character>` rewrites previous setting. The setting is |
| 579 |
local in the group. |
| 580 |
* Inline verbatim is enclosed in the pairs of `<verbchar>`s. |
| 581 |
The text between two `<verbchar>`s is processed without special interpretation. |
| 582 |
Only possibly <eol>s are replaced by space. |
| 583 |
Example: |
| 584 |
\begtt |
| 585 |
%%:use |
| 586 |
\verbchar` |
| 587 |
Now, `$this %text ~\` is processed as inline verbatim. |
| 588 |
\endtt |
| 589 |
gives: Now, `$this %text ~\` is processed as inline verbatim. |
| 590 |
* \.`\code{<text>}` processes `<text>` like inline verbatim, but |
| 591 |
all `\<character>` are processed as `<character>`, specially `\{` and `\}` |
| 592 |
are `{` and `}` but without taking them into `<balanced-text>` rule, |
| 593 |
`\\` is `\` but do not create a `<control-sequence>`, etc. |
| 594 |
\enditems |
| 595 |
|
| 596 |
|
| 597 |
\secc Multicolumns |
| 598 |
|
| 599 |
\.`\begmulti <number><space>` opens the group and \.`\endmulti` |
| 600 |
closes the group. If output format allows multi-columns then |
| 601 |
the text enclosed between `\begmulti <number><space>` and matching |
| 602 |
`\endmulti` should be printed in `<number>` balanced columns. |
| 603 |
|
| 604 |
|
| 605 |
\secc Links |
| 606 |
|
| 607 |
\begitems |
| 608 |
* \.`\url{<text>}` creates `<text>` as an external link which points to `<text>`. |
| 609 |
The `\<character>` is interpreted as `<character>` in `<text>` with one |
| 610 |
exception: `\|` is ignored. |
| 611 |
* \.`\ulink[<url>]{<text>}` creates `<text>` as an external link which points |
| 612 |
to `<url>`. The `\<character>` is interpreted as `<character>` only in |
| 613 |
`<url>` parameter. |
| 614 |
* \.`\label[<label>]` sets the `<label>`. First following occurrence of `\chap`, `\sec`, |
| 615 |
`\secc`, `\caption` or `\eqmark` sets this `<label>` as bounded to its |
| 616 |
position in the document. |
| 617 |
* \.`\ref[<label>]` should create an internal link to the position given by |
| 618 |
`\chap`, `\sec`, `\secc`, `\caption` or `\eqmark`, |
| 619 |
if `[<label>]` is used as the parameter of this control sequence |
| 620 |
else if `<label>` is bounded here by previous `\label[<label>]` |
| 621 |
The visual aspect of the link |
| 622 |
is not declared by OMLS because we don't suppose that the chapters, |
| 623 |
sections, equations, etc.\ are automatically numbered by exactly the same way as in |
| 624 |
\OpTeX/. A recommendation should be: create a simple sequence of numbers over |
| 625 |
all internal links. |
| 626 |
* \.`\pgref[<label>]` should be replaced by `??` if cnv-program generates single-page |
| 627 |
output (like Html, Markdown). Unfortunately, we get the irrelevant phrases in the output: |
| 628 |
\"{\tt The problem is shown at the page ??}". |
| 629 |
Users can declare `%%:skip` for such cases. |
| 630 |
* \.`\bib[<label>]` or `\bib[<label>]<o-space>=<o-space>{<ignored>}` should open the new bib |
| 631 |
record. More exactly, it closes previous paragraph (if h-mode is current) |
| 632 |
and opens new h-mode. Then prints an auto-generated reference number in |
| 633 |
`[...]`. Following text is interpreted as a bib record until the h-mode ends. |
| 634 |
* \.`\cite[<labels>]` should create internal links to corresponding bib |
| 635 |
records generated by `\usebib` or by `\bib`. The `<labels>` is a comma-separated list |
| 636 |
of labels used in `.bib` files or in `\bib` commands to indicate |
| 637 |
the corresponding bib record. The labels should be replaced by auto-generated |
| 638 |
reference numbers used in bib records. All reference numbers created by |
| 639 |
single `\cite` should be enclosed by single `[...]`. These numbers are |
| 640 |
internal links. If the cnv-program does not implement this complicated |
| 641 |
bib machinery then `\cite[<labels>]` should print only `[<labels>]`. |
| 642 |
* \.`\rcite[<labels>]` does the same as `\cite[<labels>]` but doesn't print |
| 643 |
outer `[...]`. |
| 644 |
* \.`\ecite[<label>]{<text>}` creates the link to corresponding bib record, |
| 645 |
`<text>` is is hyperlinked (no the auto-generated reference number). |
| 646 |
* \.`\maketoc` should create a list of titles from all `\chap`, `\sec` and `\secc` |
| 647 |
used in the document if they are not preceded by \.`\notoc`. All lines in |
| 648 |
this list should include internal links to the position where the corresponding title |
| 649 |
is used. |
| 650 |
\enditems |
| 651 |
|
| 652 |
\secc Tables |
| 653 |
|
| 654 |
\begitems |
| 655 |
* \.`\caption/<letter>` opens a caption. More exactly, if current mode is |
| 656 |
h-mode, then switch to v-mode first (i.e.\ close the current paragraph). |
| 657 |
Then switch from v-mode to h-mode and put a <caption-head>. The following |
| 658 |
text should be interpreted as the caption text until h-mode ends. |
| 659 |
If <letter> is `t` then <caption-head> is `Table` followed |
| 660 |
by an auto-generated number. If the <letter> is `f` then <caption-head> is |
| 661 |
`Figure` followed by an auto-generated number. The configuration of |
| 662 |
cnv-programs should allow different words than default `Table` or `Figure` (for |
| 663 |
example, if another language is used). |
| 664 |
* \.`\table<ignored>{<declaration>}{<data>}` should create a table. The fidelity |
| 665 |
rate of created output depends heavily on the used cnv-program and the output |
| 666 |
format. We don't suppose that all aspects of \OpTeX/ tables are implemented. |
| 667 |
The following features are listed in their priority of implementation. |
| 668 |
\begitems \style c |
| 669 |
* Items in `<data>` are separated by `&`. |
| 670 |
The last item in each row is separated by end-row separator: \.`\cr`, \.`\crl`, \.`\crll`, |
| 671 |
\.`\crli`, \.`\crlli`, or \.`\crlp{<list>}`. If there are $n$ columns in |
| 672 |
the table then we have $n-1$ `&` separators and one end-row separator |
| 673 |
for each table row. |
| 674 |
There can be an optional end-row separator at the first item in `<data>` and |
| 675 |
it should be ignored. The `<data>` can end without the end-row separator, it |
| 676 |
should be added here. |
| 677 |
* Spaces around `&` and before end-row separator are ignored. |
| 678 |
* \.`\noalign{<text>}` and \.`\tskip <dimen>` should be ignored. |
| 679 |
* Column declarators in <declaration> should be interpreted: `l` (left aligned), `c` (center |
| 680 |
aligned), `r` (right aligned) or `p{<ignored>}` (paragraph-like item). |
| 681 |
* The `<number><letter>` or `<number>{<text>}` should be interpreted as |
| 682 |
`<number>`-times repeated `<letter>` or `<text>` in `<declaration>`. |
| 683 |
* \.`\vspan<decimal-number>{<text>}` should be an item with only `<text>`. |
| 684 |
* \.`\mspan<number>[<decl>]{<text>}` should create `<text>` as an item which |
| 685 |
spans over `<number>` columns. It is used instead `<number>` real |
| 686 |
items, i.e.\ `<number>`$-1$ separators `&` aren't used here. |
| 687 |
* Rules in the table should be interpreted, i.e. `|` in <declaration> |
| 688 |
should be not ignored and |
| 689 |
various end-row separators should be distinguished (see \optexmanual, |
| 690 |
section 1.4.6). |
| 691 |
* The aligning of `p{<p-data>}` columns should be interpreded by reading |
| 692 |
\.`\fL`, \.`\fR`, \.`\fC`, \.`\fS` and \.`\fX` control sequences in `<p-data>`. |
| 693 |
See \optexmanual, section 1.4.6. |
| 694 |
\enditems |
| 695 |
\enditems |
| 696 |
|
| 697 |
\secc Footnotes, marginal notes |
| 698 |
|
| 699 |
\begitems |
| 700 |
* \.`\fnote{<text>}` should create a footnote link as an auto-generated |
| 701 |
reference number. |
| 702 |
The `<text>` should be appended at the end of the document labeled by this |
| 703 |
reference number. Another alternative (for Html output, for example): the mouse over |
| 704 |
the reference number riases an auto-popup `<text>`. |
| 705 |
* \.`\fnotemark<number>` should create a pointer to a next declared |
| 706 |
footnote as auto-generated reference number. The `<text>` of the footnote is |
| 707 |
declared after that by \.`\fnotetext{<text>}`. Exact behavior: if the |
| 708 |
reference number of the last processed `\fnote` is $n$ then |
| 709 |
`\fnotemark<number>` uses the value |
| 710 |
$n+{}$`<number>` as its reference number. A set of `\fnotemark`s |
| 711 |
is followed by an equally large set of `\fnotetext{<text>}`. First one |
| 712 |
have reference number $n+1$, second $n+2$, etc. When whole set of `\fnotetext{<text>}` |
| 713 |
is processed then $n$ is reset to the last reference number used here. |
| 714 |
* \.`\mnote <ignored>{<text>}` should be created as auto-popup `<text>` or the `<text>` |
| 715 |
is inserted at the margin. |
| 716 |
\enditems |
| 717 |
|
| 718 |
\secc Tagging for index |
| 719 |
|
| 720 |
We don't suppose that the cnv-program can generate the alphabetically sorted |
| 721 |
index. So, the markup for creating the index should be ignored: |
| 722 |
|
| 723 |
\begitems |
| 724 |
* \.`\ii <word><space>` (where `<word>` is a sequence of non-space characters) |
| 725 |
should be ignored. |
| 726 |
* \.`\iid <word><space>` is `<word><space>` by default, but |
| 727 |
if `,` or `.` follows after `<space>` then the `<space>` is removed. |
| 728 |
\enditems |
| 729 |
|
| 730 |
\secc Logos |
| 731 |
|
| 732 |
\.`\TeX`, \.`\LuaTeX`, \.`\OpTeX`, \.`\LaTeX`, respectively \: |
| 733 |
`TeX`, `LuaTeX`, `OpTeX`, `LaTeX`, respectively. If `/` follows |
| 734 |
these control sequences then it is ignored. Other logos should be declared |
| 735 |
in the configuration of the cnv-program. |
| 736 |
|
| 737 |
\secc What should be ignored |
| 738 |
|
| 739 |
\begitems |
| 740 |
* \.`\def<text>{<text>}` and other variants with \.`\gdef`, \.`\edef`, \.`\xdef`. |
| 741 |
Reason: user can insert a special definition in the `%%:text` part of the |
| 742 |
document in order to solve a problem. But cnv-program should ignore~it. |
| 743 |
* \.`\outlines{<text>}`, \.`\insertoutline{<text>}` and \.`\thisoutline{<text>}`. |
| 744 |
\enditems |
| 745 |
|
| 746 |
|
| 747 |
\sec[math] Math mode processing |
| 748 |
|
| 749 |
There are two math modes, inline: `$<formula>$` or display: `$$<formula>$$`. |
| 750 |
We suppose that `<formula>` will be processed by MathJax or similar |
| 751 |
software. So, the `<formula>` should be kept without changes in cnv-program |
| 752 |
output, but there are exceptions: |
| 753 |
|
| 754 |
\begitems |
| 755 |
* `$<sign><decimal-number>$` should be transformed to non-math text |
| 756 |
`<sign><decimal-number>`. The `<sign>` is~`+` or~`-` or nothing. |
| 757 |
The `<decimal-number>` can include `,` (comma) instead `.` (period). |
| 758 |
If the `<sign>` is~`-` (character U+002D) then |
| 759 |
it must be converted to `−` (character U+2212, math minus). |
| 760 |
* `{\bbchar <text>}` should be converted to `\mathbb{<text>}`, because |
| 761 |
MathJax doesn't understand `\bbchar`. `$\bbchar <text>$` should be |
| 762 |
converted to `$\mathbb{<text>}$`. |
| 763 |
* `{\frak <text>}` or `$\frak <text>$` \: |
| 764 |
`\mathfrak{<text>}` or `$\mathfrak{<text>}$`. |
| 765 |
* `{\script <text>}` or `$\script <text>$` \: |
| 766 |
`\mathscr{<text>}` or `$\mathscr{<text>}$`. |
| 767 |
* `\eqmark`, `\eqmark[<label>]` \: `\leqno (<num>)`, where `<num>` is |
| 768 |
auto-generated number. Or it should be completely ignored. |
| 769 |
* It is strongly recommended to allow users to declare another replacement |
| 770 |
rules over `<formula>` in configuration files of cnv-programs. |
| 771 |
\enditems |
| 772 |
|
| 773 |
|
| 774 |
\sec Notes on various conversions |
| 775 |
|
| 776 |
The cnv-programs behave differently because output formats have different |
| 777 |
concepts and are intended for different purposes. The following sections |
| 778 |
mention the main differences for typical conversions. |
| 779 |
|
| 780 |
\secc To Html |
| 781 |
|
| 782 |
The Html document is one single page. If we want to split the document to more |
| 783 |
pages, then we can use `%%:do html <action>` in positions where the document |
| 784 |
should be split (the syntax of `<action>` depends on the used cnv-program.) |
| 785 |
|
| 786 |
The design of Html pages should be declared by CSS files. |
| 787 |
|
| 788 |
Pictures inserted by `\inspic` should be inserted into the Html page as |
| 789 |
\code{<img src="...">}, so the picture files must be installed in |
| 790 |
the webserver to render the Html page correctly in a web browser. |
| 791 |
|
| 792 |
The `\maketoc` used in the \OpTeX/ document means that the Table of contents should |
| 793 |
be here. It should be generated by the cnv-program, two-pass processing is |
| 794 |
needed because the cnv-program needs to read all titles of `\chap`, `\sec` and |
| 795 |
`\secc`. Another approach is to read the `.ref` file produced by \OpTeX/. |
| 796 |
|
| 797 |
|
| 798 |
\secc To Markdown |
| 799 |
|
| 800 |
Markdown source file is \"one-page document" too. The principles a |
| 801 |
re similar to conversion to Html. |
| 802 |
|
| 803 |
\secc From Markdown |
| 804 |
|
| 805 |
The cnv-program which does such a reverse conversion should be very useful for |
| 806 |
people they prefer even clearer markup than in \OpTeX/. |
| 807 |
|
| 808 |
\secc To \LaTeX |
| 809 |
|
| 810 |
\LaTeX/ gives the same main feature as \OpTeX/: it can generate PDF |
| 811 |
output from a source file. But different macros, a different concept, and |
| 812 |
a different markup are used. |
| 813 |
|
| 814 |
The main reason for such conversion is that journal editors |
| 815 |
require \LaTeX/ source file, but user want to prepare their real document in |
| 816 |
more comfortable (\OpTeX/) markup and with more simple macros. |
| 817 |
|
| 818 |
This conversion should keep almost all features. For example, the |
| 819 |
`\pgref[<label>]` is converted to `\pageref{<label>}`. The cnv-program |
| 820 |
needs not to generate a Table of contents, bibliography references, etc. Only |
| 821 |
appropriate \LaTeX/ markup must be used. |
| 822 |
|
| 823 |
The contents of generated \LaTeX/ preamble should be configurable. |
| 824 |
|
| 825 |
|
| 826 |
\secc From \LaTeX |
| 827 |
|
| 828 |
The reverse conversion from \LaTeX/ to \OpTeX/ can be usable |
| 829 |
for people, they want to switch to creating their documents in \OpTeX/. |
| 830 |
|
| 831 |
The cnv-program must solve additional problem in this type of conversion. |
| 832 |
There are various math \LaTeX/ environments, they must be converted to |
| 833 |
plain~\TeX/ syntax of math typesetting. For example:\nl |
| 834 |
`\begin{array}...\end{array}` \: `\matrix{...}`,\nl |
| 835 |
`\begin{align*}...\end{align*}` \: `$$\eqalign{...}$$`\nl |
| 836 |
`\frac{...}{...}` \: `{...\over...}`. |
| 837 |
|
| 838 |
\bye |