From ae496a1c963576dfe63885afa818b2af745ed44a Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 27 Apr 2020 03:03:41 +0000 Subject: CTAN sync 202004270303 --- macros/luatex/optex/doc/optex-userdoc.tex | 1803 +++++++++++++++++++++++++++++ 1 file changed, 1803 insertions(+) create mode 100644 macros/luatex/optex/doc/optex-userdoc.tex (limited to 'macros/luatex/optex/doc/optex-userdoc.tex') diff --git a/macros/luatex/optex/doc/optex-userdoc.tex b/macros/luatex/optex/doc/optex-userdoc.tex new file mode 100644 index 0000000000..470214dfdc --- /dev/null +++ b/macros/luatex/optex/doc/optex-userdoc.tex @@ -0,0 +1,1803 @@ +%% This is part of OpTeX project, see http://petr.olsak.net/optex + +% This file is read from optex-doc.tex +% Use: optex optex-doc (three times) to create whole documentation. + +\sec Starting with \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 op-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 a technical limitation of \LuaTeX/ for fonts downloaded 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 languages (for example `Ahoj světe!`) +where Unicode fonts are needed +because of the characters like `ě` are not mapped correctly in preloaded +fonts. + +A somewhat larger example with common settings should be: + +\begtt \catcode`!=0 +\fontfam[Termes] % selecting Unicode font family Termes (section !ref[fontfam]) +\typosize[11/13] % setting default font size and baselineskip (sec. !ref[sizes]) +\margins/1 a4 (1,1,1,1)in % setting A4 paper, 1 in margins (section !ref[marg]) +\cslang % Czech hyphenation patterns (section !ref[lang]) + +Tady je zkušební textík v českém jazyce. +\bye +\endtt +% +You can look at `op-demo.tex` file for more complex, but still simple example. + + +\sec Page layout +%%%%%%%%%%%%%%%% + +\secc[marg] Setting the margins +%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The \^`\margins` command declares margins of the document. This command have +the following parameters: + +\begtt \catcode`\<=13 +\margins/ (,,,) + example: +\margins/1 a4 (2.5,2.5,2,2)cm +\endtt + +Parameters are: + +\begitems +* \dots\ `1` or `2` specifies one-page or two-pages design. +* \dots\ paper format (a4, a4l, a5, letter, etc. or user defined). +* , , , \dots\ gives the amount of left, right, + top and bottom margins. +* \dots\ unit used for values , , , . +\enditems + +Each of the parameters , , , can be empty. +If both and are nonempty then `\hsize` is set. Else `\hsize` +is unchanged. If both and are empty then typesetting area is +centered in the paper format. The analogical rule works when or +parameter is empty (`\vsize` instead `\hsize` is used). Examples: + +\begtt +\margins/1 a4 (,,,)mm % \hsize, \vsize untouched, + % typesetting area centered +\margins/1 a4 (,2,,)cm % right margin set to 2cm + % \hsize, \vsize untouched, vertically centered +\endtt + +If `=1` then all pages have the same margins. If `=2` then the +declared margins are true for odd pages. The margins at the even pages are +automatically mirrored in such case, it means that is replaced by + and vice versa. + +\OpTeX/ declares following paper formats: a4, a4l (landscape~a4), +a5, a5l, b5, letter and user can declare another own format by `\sdef`: + +\begtt +\sdef{_pgs:b5l}{(250,176)mm} +\sdef{_pgs:letterl}{(11,8.5)in} +\endtt + +The `` can be also in the form `(,)` where `` is +optional. If it is missing then `` after margins specification is +used. For example: + +\begtt +\margins/1 (100,200) (7,7,7,7)mm +\endtt +% +declares the paper 100$\times$200\,mm with all four margins 7\,mm. The spaces +before and after parameter are necessary. + +The command \^`\magscale[]` scales the whole typesetting area. +\new The fixed point of such scaling is the upper left corner of the paper sheet. +Typesetting (breakpoints etc.) is unchanged. All units are relative after +such scaling. Only paper formats dimensions stays unscaled. Example: + +\begtt +\margins/2 a5 (22,17,19,21)mm +\magscale[1414] \margins/1 a4 (,,,)mm +\endtt +% +The first line sets the `\hsize` and `\vsize` and margins for final +printing at a5 format. The setting on the second line centers the scaled +typesetting area to the true a4 paper while breaking points for paragraphs +and pages are unchanged. It may be usable for +review printing. After review is done, the second line can be commented out. + +\secc Concept of default page +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\OpTeX/ uses for page design very similar to Plain \TeX/ \"output routine". +There is \^`\headline` followed by \"page body" followed by +\^`\footline`. The \^`\headline` is empty by default and it can be used +for running headers repeated on each page. The \^`\footline` prints +centered page number by default. You can set the \^`\footline` to empty +using \^`\nopagenumbers` macro. + +The margins declared by \^`\margins` macro (documented in the previous +section~\ref[marg]) is concerned to the page body, +i.e.\ the \^`\headline` and \^`\footline` are placed to the top and bottom +margins. + +The distance between the \^`\headline` and the top of the page body is given by +the \^`\headlinedist` register. The distance between bottom of the page body and +the \^`\footline` is given by \^`\footlinedist`. The default values are: + +\begtt +\headline = {} +\footline = {\_hss\_rmfixed \_folio \_hss} % \folio expands to page number +\headlinedist = 14pt % from baseline of \headline to top of page body +\footlinedist = 24pt % from last line in pagebody to baseline of footline +\endtt + +The page body should be divided to top insertions (floating tables and +figures) followed by a real text and followed by footnotes. +Typically, only real text is here. + +The \^`\pgbackground` tokens list is empty by default but it can be used for +creating background of each page (colors, picture, watermark for example). +The macro \^`\draft` uses this register and puts big text DRAFT as watermark +to each page. You can try it. + +More about the page layout is documented in files `parameters.opm` and +`output.opm`. + + +\secc Footnotes and marginal notes +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The Plain \TeX/'s macro \^`\footnote` can be used as usual. But a new macro +\^`\fnote{}` is defined. The footnote mark is added automatically and it +is numbered +\new +on each chapter from one\fnote +{You can declare \^`\fnotenumglobal` if you want footnotes numbered in whole +document from one or \^`\fnotenumpages` if you want footnotes numbered at each +page from one. Default setting is \^`\fnotenumchapters`}. +The is scaled to 80 \%. +User can redefine footnote mark or scaling, as shown in the file +`fnotes.opm`. + +The \^`\fnote` macro is fully applicable only in \"normal outer" paragraph. +It doesn't work inside boxes (tables, for example). If you are solving such +case then you can use the command \^`\fnotemark``` inside the box: only the +footnote mark is generated here. When the box is finished you can use +\^`\fnotetext{}`. This macro puts the to the footnote. +The have to be `1` if only one such command is in the box. +Second \^`\fnotemark` inside the same box have to have the parameter `2` etc. +The same number of \^`\fnotetext`s have to be written +after the box as the number of \^`\fnotemark`s inserted inside the box. +Example: + +\begtt +Text in a paragraph\fnote{First notice}... % a "normal" footnote +\table{...}{...\fnotemark1...\fnotemark2...} % two footnotes in a box +\fnotetext{Second notice} +\fnotetext{Third notice} +... +\table{...}{...\fnotemark1...} % one footnote in a box +\fnotetext{Fourth notice} +\endtt + +The marginal note can be printed by the \^`\mnote{}` macro. The +is placed to the right margin on the odd pages and it is placed to the left +margin on the even pages. This is done after second \TeX{} run because the +relevant information is stored in an external file and read from it again. +If you need to place the notes only to the fixed margin write +\^`\fixmnotes\right` or \^`\fixmnotes\left`. + +The is formatted as a little paragraph with the maximal width +\^`\mnotesize` ragged left on the left margins or ragged right on the right +margins. The first line of this little paragraph has its vertical position +given by the position of \^`\mnote` in the text. The exceptions are possible +by setting the \^`\mnoteskip` register. You can implement such exceptions to +each \^`\mnote` manually in final printing in order to margin notes do not +overlap. The positive value of \^`\mnoteskip` shifts the note up and negative +value shifts it down. For example \^`\mnoteskip=2\baselineskip` \^`\mnote{}` +shifts this (and only this) note two lines up. + + +\sec Fonts +%%%%%%%%%% + +\secc[fontfam] Font families +%%%%%%%%%%%%%%%%%%%%%%% + +You can select the font family by \^`\fontfam[]`. +The argument is case insensitive and spaces are ignored in it. For +example, \^`\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 catalog of all fonts registered in +\OpTeX/ and available in your \TeX/ system is printed. The instructions +how to register your own font family is appended in such catalog. + +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 variant selectors} (\^`\rm`, \^`\bf`, \^`\it`, \^`\bi`). +The usage of variant selectors is the same as in Plain \TeX: +`{\it italics text}`, `{\bf bold text}` etc. + +The font modifiers (`\caps`, `\cond` for example) can +be used before a 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 First text \it Second text` +gives {\caps \rm First text \it Second text}. + +\new +There is one special variant selector \^`\currvar` which does not change the +selected variant but reloads the font due to (maybe newly +specified) font modifier(s). + +The context between variants \^`\rm` $\leftrightarrow$ \^`\it` and +\^`\bf` $\leftrightarrow$ \^`\bi` is kept by the \^`\em` +macro (emphasize text). +It switches from current \^`\rm` to \^`\it`, from current \^`\it` to \^`\rm`, from +current \^`\bf` to \^`\bi` and from current \^`\bi` to \^`\bf`. +The italics correction `\/` is inserted automatically, if needed. 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 technical +documentation in the section~\ref[fontsystem]. +You can mix more font families in your document, you can +declare your own variant selectors or modifiers etc. + +\secc[sizes] Font sizes +%%%%%%%%%%%%%%%%%%%%% + +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` enlarges all font sizes declared by \^`\typosize`. +Examples: + +\begtt +\typosize[10/12] % default of Plain TeX +\typosize[11/12.5] % font 11pt, baseline 12.5pt +\typosize[8/] % font 8pt, baseline unchanged +\endtt + +The commands for font size setting described in this section +have local validity. If you put them into a group, +the settings are lost when the group is finished. If you set +something relevant with paragraph shape (baselineskip given by +\^`\typosize` for example) then you must first finalize the +paragraph before closing the group: +`{\typosize[12/14] ...... \par}`. + +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 (\magstep2 expands to 1440) +\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` command 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 \"low level" \^`\setfontsize{}` command which behaves like +a font modifier and sets given font size used by next variant selectors. +It doesn't change the font size immediately, but following variant slelector +does it. For example \^`\setfontsize{at15pt}`\^`\currvar` sets current variant to 15pt. + +If you are using a font family with \"optical sizes feature" (i.\,e.\ there +are more recommended sizes of the same font which are not scaled +linearly; good example is Computer Modern aka Latin Modern fonts) +then the recommended size is selected by all mentioned commands automatically. + +More information about resizing of fonts is documented in the +section~\ref[setfontsize]. + +\secc Typesetting math +%%%%%%%%%%%%%%%%%%%%% + +\OpTeX/ preloads a collection of 7bit Computer Modern math fonts +and AMS fonts in its format for math typesetting. +You can use them in any size and in the \^`\boldmath` variant. +% +\new +Most declared text font families (see \^`\fontfam` in the section~\ref[fontfam]) +are configured with recommended Unicode +math font. This font is automatically loaded unless you specify +\^`\noloadmath` before first \^`\fontfam` command. See log file for more +information about loading text font family and Unicode math fonts. If you +prefer another Unicode math font, specify it by \^`\loadmath{[]}` +or \^`\loadmath{font-name}` before first \^`\fontfam` command. + +Hundreds math symbols and operators like in AMS\TeX/ are accessible. +For example `\alpha` $\alpha$, `\geq`~$\geq$, `\sum` $\sum$, +`\sphericalangle` $\sphericalangle$, `\bumpeq`, $\bumpeq$. See AMS\TeX/ +manual for complete list of symbols. + +The following math alphabets are available: + +\begtt \catcode`\$=3 \catcode`/=0 \medmuskip=0mu \adef{ }{ } +\mit % mathematical variables $abc-xyz,ABC-XYZ$ +\it % text italics $/it abc-xyz,ABC-XYZ$ +\rm % text roman $/rm abc-xyz,ABC-XYZ$ +\cal % normal calligraphics $/cal ABC-XYZ$ +\script % script $/script ABC-XYZ$ +\frak % fracture $/frak abc-xyz,ABC-XYZ$ +\bbchar % double stroked letters $/bbchar ABC-XYZ$ +\bf % sans serif bold $/bf abc-xyz,ABC-XYZ$ +\bi % sans serif bold slanted $/bi abc-xyz,ABC-XYZ$ +\endtt + +The last two selectors \^`\bf` and \^`\bi` select the sans serif fonts in math regardless +the current text font family. This is common notation for vectors and +matrices. You can re-declare it, see the file `unimath-codes.opm` where +Unicode math variants of \^`\bf` and \^`\bi` selectors are defined. + +The math fonts can be scaled by \^`\typosize` and \^`\typoscale` macros. +Two math fonts collections are prepared: \^`\normalmath` for normal weight +and \^`\boldmath` for bold. The first one is set by default, the second one +is usable for math formulae in titles typeset in bold, for example. + +\new +You can use \^`\mathbox{}` inside math mode. It behaves as `{\hbox{}}` +(i.e. the is printed in horizontal non-math mode) +but the size of the is adapted to the context of math size (text or script or +scriptscript). + + +\sec Typical elements of document +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\secc[chap] Chapters and sections +%%%%%%%%%%%%%%%%%%%%%%%%%% + +The document can be divided into chapters (\^`\chap`), +sections (\^`\sec`), subsections (\^`\secc`) and they can be titled +by \^`\tit` command. The parameters are separated by the end of current line (no +braces are used): + +\begtt \catcode`\<=13 +\tit Document title +\chap Chapter title +\sec Section title +\secc Subsection title +\endtt + +If you want to write a title to more lines in your source file then you can +use percent character before . Such is not +scanned and reading of the title continues at the next line. + +The chapters are automatically 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`. A designer 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. You can combine both prefixes. + +\secc[cap] Another numbered objects +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Apart from chapters, sections and subsections, there are another +automatically numbered objects: equations, captions for tables and +figures. The user can declare more numbered object. + +If the user writes the \^`\eqmark` as the last element of the display mode then +this equation is numbered. The equation number is printed in brackets. This number +resets in each section by default. + +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 + +Another automatically numbered object is a caption which is tagged by \^`\caption/t` for +tables and \^`\caption/f` for figures. The caption text follows. +The \^`\cskip` can be used between \^`\caption` text and the real object (table +or figure). You can use two orders: `\cskip ` or +`\cskip `. +The \^`\cskip` creates appropriate vertical space between them. Example: + +\begtt +\caption/t The dependency of the computer-dependency on the age. +\cskip +\noindent\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} +\endtt + +This example produces: + +\medskip +\caption/t The dependency of the computer-dependency on the age. +\cskip +\noindent\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} +\medskip + +You can see that the word \"Table" followed by a number is added by the macro +`\caption/t`. +The caption text is centered. If it occupies more lines then the +last line is centered. + +The macro \^`\caption/f` behaves like \^`\caption/t` but it is intended for +figure captions with independent numbering. +The word (Table, Figure) depends on the actual selected language (see +section~\ref[lang] about languages). + +If you wish to make the table or figure as floating object, you need to use +Plain \TeX/ macros \^`\midinsert` or \^`\topinsert` terminated by \^`\endinsert`. +Example: + +\begtt +\topinsert % table and its caption printed at the top of the current page + +\endinsert +\endtt + +\new +There are five prepared counters `A`, `B`, `C`, `D` and `E`. +They are reset in each chapter and section\fnote +{This feature can be changed, see the section~\ref[sections] in the technical documentation.}. +They can be used in context of \^`\numberedpar` `{}` +macro. For example: +\begtt +\def\theorem {\numberedpar A{Theorem}} +\def\corollary {\numberedpar A{Corollary}} +\def\definition {\numberedpar B{Definition}} +\def\example {\numberedpar C{Example}} +\endtt +% +Three independent numbers are used in this example. One for Theorems and Corollaries +second for Definitions and third for Examples. The user can write +`\theorem Let $M$ be...` and the new paragraph is started with the text: +{\bf Theorem 2.3.1.} Let $M$ be... +You can add an optional parameter in brackets. For example, +`\theorem [(L'Hôpital's rule)] Let $f$, $g$ be...` +is printed like {\bf Theorem 2.4.2 (L'Hôpital's rule).} Let $f$, $g$ be... + + +\secc References +%%%%%%%%%%%%%%% + +Each automatically numbered object documented in +sections \ref[chap] and \ref[cap] can be referenced +\new +if optional parameter +`[