From c36a274c633c08115b6006622112f5609031001e Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Wed, 19 Feb 2020 03:02:04 +0000 Subject: CTAN sync 202002190302 --- macros/luatex/optex/doc/optex-doc.pdf | Bin 0 -> 145296 bytes macros/luatex/optex/doc/optex-doc.tex | 1546 +++++++++++++++++++++++++++++++++ macros/luatex/optex/doc/optex.1 | 42 + 3 files changed, 1588 insertions(+) create mode 100644 macros/luatex/optex/doc/optex-doc.pdf create mode 100644 macros/luatex/optex/doc/optex-doc.tex create mode 100644 macros/luatex/optex/doc/optex.1 (limited to 'macros/luatex/optex/doc') diff --git a/macros/luatex/optex/doc/optex-doc.pdf b/macros/luatex/optex/doc/optex-doc.pdf new file mode 100644 index 0000000000..93a6d13eb3 Binary files /dev/null and b/macros/luatex/optex/doc/optex-doc.pdf differ diff --git a/macros/luatex/optex/doc/optex-doc.tex b/macros/luatex/optex/doc/optex-doc.tex new file mode 100644 index 0000000000..514a322dd7 --- /dev/null +++ b/macros/luatex/optex/doc/optex-doc.tex @@ -0,0 +1,1546 @@ + +\fontfam[LMfonts] +\typosize[11/13] +\enlang + +\localcolor +\catcode`<=13 +\def<#1>{\hbox{$\langle$\it#1\/$\rangle$}} +\intthook={\catcode`\<=13} +\tthook=\intthook +\chardef\"="201C + +\def\new{\mnote{\Red$\blacktriangleleft$}} +\fixmnotes\right + +\activettchar` + +\hyperlinks{\Blue}{\Green} +\insertoutline{CONTENTS} \outlines{0} + + +\tit \OpTeX/\nl Format Based on Plain \TeX/ and OPmac\fnotemark1 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\hfill Version Alpha 0.03 + +\centerline{\it Petr Olšák, 2020} + +\bigskip +\centerline{\url{http://petr.olsak.net/optex}} + + +\fnotetext {The OPmac package is a set of simple additional macros to plain\TeX{}. It +enables users to take advantage of basic \LaTeX/ functionality but keeps +plain \TeX/ simplicity. See +\url{http://petr.olsak.net/opmac-e.html} for more information about it. +For OPmac users: the red triangle {\Red$\blacktriangleleft$} in the right margin +means that there is a difference from standard OPmac features.} + +\notoc\nonum \sec Contents +\maketoc + +\nonum \sec Introduction +%%%%%%%%%%%% + +\OpTeX/ is \LuaTeX/ format with plain \TeX/ and OPmac. Only \LuaTeX/ engine +is supported. The main goal of \OpTeX/ is: + +\begitems +* \OpTeX/ keeps the simplicity (like in plain \TeX/ and OPmac macros). +* There is no old obscurities concerning with various 8-bit encodings and + various engines. +* \OpTeX/ provides a powerful font selection system (for Unicode font + families, of course). +* \OpTeX/ supports hyphenations of all languages installed in your \TeX/ system. +* All features from OPmac macros are copied (for example, you can see + opmac-prospectus.pdf) +* Macros are documented in the same place where code is (macros for printing + this documentation will come in the future). +* User name space of control sequences is separated from internal name space + of OpTeX and primitives (`\foo` versus `\_foo`). +\enditems + +\OpTeX/ should be a modern plain \TeX/ with power from OPmac (fonts selection +system, colors, external graphics, references, hyperlinks...) with unicode +fonts. + +\OpTeX/ (like OPmac) offers a markup language for authors of texts (like \LaTeX), +i.e. the fixed set of tags to define the structure of the document. This +markup is different from the \LaTeX{} markup. It may offer to write the +source text of the document somewhat clearer and more attractive. + +\new +{\bf Disclaimer:} This software is under construction. +It is possible that some features documented here will be changed in future. + + +\sec Using \OpTeX/ +%%%%%%%%%%%%%%%%%% + +\new +\OpTeX/ is compiled as a format for \LuaTeX/. Maybe there is a command +`optex` in your \TeX/ distribution. Then you can write into command line + +\begtt +optex document +\endtt +% +You can try to process `optex demo` or `optex optex-doc`. + +If there is no `optex` command, see more information about installation +\OpTeX/ at \url{http://petr.olsak.net/optex}. + +A minimal document should be + +\begtt +\fontfam[LMfonts] +Hello World! \bye +\endtt + +The first line `\fontfam[LMfonts]` tells that Unicode Latin Modern +fonts (derived from Computer Modern) are used. If you omit this line then +preloaded Latin Modern fonts are used but preloaded fonts cannot be in +Unicode\fnote +{This is technical limitations of \LuaTeX/ for fonts in formats: +only 8bit fonts can be preloaded.}. +So the sentence `Hello World` will be OK without the first line, but you +cannot print such sentence in another languges (like `Ahoj světe!`) +where Unicode fonts are needed +because of the characters like `ě` are not mapped correctly in preloaded +font. + +A somewhat larger example with common settings shoud be: + +\begtt +\fontfam[Termes] % selecting Unicode font family Termes +\typosize[11/13] % setting the basic font size and the baselineskip +\margins/1 a4 (1,1,1,1)in % setting 1in margins for A4 paper +\cslang % Czech hyphenation patterns + +Tady je text. +\bye +\endtt +% +You can look at `demo.tex` file for more examples. + + +\sec Compatibility with Plain \TeX/ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +All macros of plain \TeX/ are re-written in \OpTeX/. Common macros should be +work in the same sense as in original plain \TeX. Internal control sequences +\new +like `\p@` or `\f@@t` are removed and mostly replaced by control sequences +prefixed by `_` (like `\_this`). All primitives and common macros have two +control sequences in prefixed and unprefixed form with the same +meaning. For example `\hbox` is equal to `\_hbox`. +Internal macros of \OpTeX/ have and use only prefixed form. User should use +unprefixed forms, but prefixed forms are accessibe too, bacause the `_` is +set as a letter globally (in macro files and in users document too). User +should re-define unprefixed forms of control sequences with no worries that +something internal will be broken (only the sequence `\par` cannot be +re-defined without internal change of \TeX/ behavior because it is +hard-coded in \TeX/s tokenization processor). + +\new +The Latin Modern 8bit fonts instead Computer Modern 7bit fonts are +preloaded in the format, but only few ones. The full family set is ready to +use after the command `\fontfam[LMfonts]` which reads the fonts in OTF +format. + +\new +The `\tenrm`, `\tenbf` etc. selectors are not defined. There are internal +selectors `\_tenrm`, `\_tenbf` etc. instead them. Don't use them directly +until you understand the \OpTeX/ font selection system from +internal point of view. + +\new +The accents macros like `\'`, `\v` are undefined in \OpTeX/. Use real +letters like ř, ž in your soucre document instead these old accents macros. +If you really want to use them, you can initialize them by `\oldaccents` +command. + +\new +The paper size is not set as letter with 1\,in margins but as a4 with 2\,cm +marins. You can change it by `\margins/1 letter (1,1,1,1)in` (this example +sets the classical plainTeX parameters). + +\new +The origin for typographical area is not at top left 1\,in 1\,in coordinates +but at top left paper corner exactly. For example, `\hoffset` includes directly left +margin. + + +\sec Selection of font family +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +You can select the font family by `\fontfam[]`. +The argument is case insensitive and spaces are ignored. So, +`\fontfam[LM Fonts]` is equal to `\fontfam[LMfonts]` and it is equal +to `\fontfam[lmfonts]`. Several aliases are prepared, thus +`\fontfam[Latin Modern]` can be used for loading Latin Modern family too. + +If you write `\fontfam[?]` then all font families registered in \OpTeX/ +are listed on the terminal and in the log file. + +If you write `\fontfam[catalog]` then a catalogue of all fonts registered in +\OpTeX/ and available in your \TeX/ system is printed. And the instructions +how to register your own font family is appedned in such catalogue. + +If the family is loaded then {\em font modifiers} applicable in such font family +are listed on the terminal: (`\caps`, `\cond` for example). +And there are four basic {\em varinat selectors} (`\rm`, `\bf`, `\it`, `\bi`). +The font modifiers of basic variants (`\caps`, `\cond` for example) can +be used immediately before a basic variant selector and they +can be (independently) combined: `\caps\it` or `\cond\caps\bf`. The +modifiers keeps their internal setting until group ends or until another +modifier which negates the previous feature is used. So +`\caps \rm... \it...` uses normal and italics in Caps and SmallCaps. + +\new +There is one special variant selector `\currvar` which does not change the +selected variant but reloads the font in respect of tne (maybe newly +specified) font slector(s). + +\new Most declared font families are configured with recommended Unicode +Math font. This font is automaticlally loaded unless you specify +`\noloadmath` before first `\fontfam` command. See log file for more +information about loading Text font family and UnicodeMath fonts. If you +prefer another Unicode Math font, specify it by `\loadmath{[]}` +or `\loadmath{font_name}` before first `\loadfam` command. + +The `\em` macro acts as `\it` if the current font is `\rm`, acts as `\rm` if +the current font is `\it`, acts as `\bi` if the current font is `\bf` and +acts as `\bf` if the current font is `\bi`. The `\/` spaces are inserted +automatically. Example: + +\begtt +This is {\em important} text. % = This is {\it important\/} text. +\it This is {\em important} text. % = This is\/ {\rm important} text. +\bf This is {\em important} text. % = This is {\bi important\/} text. +\bi This is {\em important} text. % = This is\/ {\bf important} text. +\endtt + +\new +More about the \OpTeX/ font selection system is written the file +`fonts-select.opm`. You can mix more font families in your document, you can +declare your variant selectors o modifiers etc. + +\new +The `\boldify` macro can be used for titles. It sets `\it` to `\bi` and +`\rm` to `\bf`. It means that user can write `{\it something}` in the title +and the result is the same as `{\bi something}`. Math formulae are in bold +variant too. The `\boldify` macro has local validity like others font +modifiers. Example: + +\begtt +{\boldify\typosize[14/16] Title in {\it bold}\par} +\endtt + + +\sec Font sizes +%%%%%%%%%%%%%%% + +The commands for font size setting described below, for variant selectors and +modifiers desribed above have local validity. If you put them into a group, +the font features are selected locally. + +The command `\typosize[/]` sets the font size of text and +math fonts and baselineskip. If one of these two parameters is empty, the +corresponding feature stays unchanged. Don't write the unit of these +parameters. The unit is internally set to `\ptunit` which is 1pt by default. +You can change the unit by the command `\ptunit=`, +for instance `\ptunit=1mm` enlages all font sizes declared by `\typosize`. +Examples: + +\begtt +\typosize[10/12] % default of plainTeX +\typosize[11/12.5] % font 11pt, baseline 12.5pt +\typosize[8/] % font 8pt, baseline unchanged +\endtt + +The command +`\typoscale[/]` +sets the text and math fonts +size and baselineskip as a multiple of the current fonts size and +baselineskip. The factor is written in \"scaled"-like way, it means that 1000 +means factor one. The empty parameter is equal to the parameter 1000, +i.e. the value stays unchanged. Examples: + +\begtt +\typoscale[800/800] % fonts and baselineskip re-size to 80 % +\typoscale[\magstep2/] % fonts bigger 1,44times +\endtt + +First usage of `\typosize` or `\typoscale` macro in your document sets so +called {\em main values}, i.\ e. main font size and main baselineskip. They are internally +saved in registers `\mainfosize` and `\mainbaselineskip`. + +\new +The `\typoscale` comand does scaling in respect to current values by default. +If you want to do it in respect to main values, type `\scalemain` immediately +before `\typoscale` command. + +\begtt +\typosize[12/14.4] % first usage in document, sets main values internally +\typosize[15/18] % bigger font +\scalemain \typoscale[800/800] % reduces from main values, no from current. +\endtt + +The size of the current font can be changed by the command +`\thefontsize[]` or can be rescaled by +`\thefontscale[]`. These macros don't change math fonts sizes nor +baselineskip. + +\new +There is `\setfontsize{}` command which behaves like other +font modifiers. For example `\setfontsize{at15pt}\currvar`. + +More information about resizing of fonts is documented in `fonts-resize.opm` +file. + + +\sec Parts of the document +%%%%%%%%%%%%%%%%%%%%%%%%%% + +The document can be divided into chapters, sections and subsections and titled +by `\tit` command. The parameters are separed by the end of current line (no +braces are used): + +\begtt +\tit Document title +\chap Chapter title +\sec Section title +\secc Subsection title +\endtt + +The chapters are numbered by one number, sections by two numbers +(chapter.section) and subsections by three numbers. If there are no chapters +then section have only one number and subsection two. + +The implicit design of the titles of chapter etc.\ are implemented in the +macros `\printchap`, `\printsec` and `\printsecc`. User can simply change +these macros if he/she needs another behavior. + +The first paragraph after the title of chapter, section and subsection is +not indented but you can type `\let\firstnoindent=\relax` if you need all +paragraphs indented. + +If a title is so long then it breaks to more lines. It is better to hint the +breakpoints because \TeX/ does not interpret the meaning of the title. +User can put the `\nl` (it means newline) macro to the breakpoints. + +The chapter, section or subsection isn't numbered if the `\nonum` precedes. +And the chapter, section or subsection isn't delivered to the table of +contents if `\notoc` precedes. + + +\sec Another numbered objects +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Apart from chapters, sections and subsections, there are another +automatically numbered objects: equations and captions for tables and +figures. + +If user write the `\eqmark` as the last element of the display mode then +this equation is numbered. The format is one number in brackets. This number +is reset in each section. + +If the `\eqalignno` is used, then user can put `\eqmark` to the last column +before `\cr`. For example: + +\begtt +\eqalignno{ + a^2+b^2 &= c^2 \cr + c &= \sqrt{a^2+b^2} & \eqmark \cr} +\endtt + +The next numbered object is caption which is tagged by `\caption/t` for +tables and `\caption/f` for figures. Example: + +\begtt +\hfil\table{rl}{ + age & value \crl\noalign{\smallskip} + 0--1 & unmeasured \cr + 1--6 & observable \cr + 6--12 & significant \cr + 12--20 & extremal \cr + 20--40 & normal \cr + 40--60 & various \cr + 60--$\infty$ & moderate} +\par\nobreak\medskip +\caption/t The dependency of the computer-dependency on the age. +\endtt + +This example produces: + +\bigskip +{\def\addto#1#2{\expandafter\def\expandafter#1\expandafter{#1#2}} +\hfil\table{rl}{age & value \crl\noalign{\smallskip} + 0--1 & unmeasured \cr + 1--6 & observable \cr + 6--12 & significant \cr + 12--20 & extremal \cr + 20--40 & normal \cr + 40--60 & various \cr + 60--$\infty$ & moderate} +\par\nobreak\medskip +{ \leftskip=\parindent plus1fil + \rightskip=\parindent plus-1fil + \parfillskip=0pt plus2fil \noindent +{\bf Table 2.3} The dependency of the com\-puter-dependency on the age.\par} +} +\bigskip + +The word \"Table" followed by a number is added by the macro +`\caption/t`. + +The macro `\caption/f` creates the word figure. +The caption text is centered. If it occupies more lines then the +last line is centered. + +The added word (table, figure) depends on the actual number of the +`\language` register. \OpTeX/ implements the mapping from `\language` +numbers to the languages and the mapping from languages to the generated +words. + +If you wish to make the table or figure as floating object, you need to use +plain \TeX/ macros `\midinsert`, `\topinsert` and `\endinsert`. + +Each automatically numbered object can be referenced, if the +`\label[