Debian Codegraph @

texmf-dist/doc/optex/base/omls.tex

raw
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