diff options
Diffstat (limited to 'Master/texmf-dist/doc/cstex/opmac-u-en.tex')
| -rw-r--r-- | Master/texmf-dist/doc/cstex/opmac-u-en.tex | 1251 |
1 files changed, 1251 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/cstex/opmac-u-en.tex b/Master/texmf-dist/doc/cstex/opmac-u-en.tex new file mode 100644 index 00000000000..95408df9a3e --- /dev/null +++ b/Master/texmf-dist/doc/cstex/opmac-u-en.tex @@ -0,0 +1,1251 @@ + +\input opmac + +\def\toasciidata{}\def\r{} + +\typosize[11/13] + +\def\thefnote{$^{\locfnum}$} + +\catcode`<=13 +\def<#1>{\hbox{$\langle$\it#1\/$\rangle$}} + +\activettchar" + +\insertoutline{CONTENTS} \outlines{0} \hyperlinks{\Blue}{\Green} + + +\tit OPmac -- macros for plain\TeX\fnotemark1 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\centerline{\it Petr Ol\v s\'ak, 2012, 2013, 2014} + +\bigskip +\centerline{\url{http://petr.olsak.net/opmac-e.html}} + + +\fnotetext {This text is second revised version. The first version was + published in TUGboat 34:1, 2013, pp.~88--96} + +\notoc\nonum \sec Contents\par\maketoc + +\nonum \sec Introduction +%%%%%%%%%%%% + +The OPmac package is simple additional macros to plain\TeX{}. It enables +users to take advantage of basic \LaTeX{} functionality: the font size +selection, automatic creation of table of contents and index, working with +bibliography databases, tables, references including hyperlinks option, +margins settings, etc. + +I have decided to publish my macros together with the new version of +\csplain{}. I am using these macros long time for various purposes only in +my own computer. Now, I have made them more clean and added the user and +technical documentation and released them. + +The main reason is to give a set of macros which solves the common tasks to +the plain\TeX{} users. The side effect is that the macros demonstrate +that it is possible to do \TeX{} code simple and effective. Most of +\LaTeX{} macro packages don't have this feature. All macros are in the single +documented file "opmac.tex" with only 1700 lines. On the other hand the +\LaTeX{} code which solves comparable tasks is placed in kernel and tens +of \LaTeX{} packages with many tens of thousands lines in total. + +The main principles which I followed when creating this macro package, are: + +\begitems + * Simplicity is power. + * Macros are not universal, but are readable and understandable. + * User can easily redefine these macros as he/she wishes. +\enditems + +Each part of the macro code is written in order to maximize readability for +human who will want to read it, understand it and change it. + +OPmac package 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. The OPmac +package, however, does not care for typographic of the document. The simple +sober document is created if no additional macros are used. We assume that +the author of additional macros is able to create a look of the document to +suit specific requirement. + +OPmac has a small number of additional packages: "pdfuni", "opmac-xetex" and +"opmac-bib" (see the end of \url{http://petr.olsak.net/opmac-e.html} page). +Moreover, there exist many tens of little OPmac tricks comparable with +\LaTeX{} packages +mentioned on \url{http://petr.olsak.net/opmac-tricks.html} page. + +\secnum=-1 + +\sec Using OPmac +%%%%%%%%%%%%%%%% + +OPmac is not compiled as a format. For using it in plain\TeX{}, you can simply +"\input opmac" at the beginning of your document. The example of the simple +document follows: + +\begtt +\input opmac +\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 + +Here is a text. +\bye +\endtt + +You can use \TeX, pdf\TeX, Xe\TeX{} or lua\TeX{} with eplain or \csplain{} +preloaded. The \csplain{} is recommended but it is not explicitly requested if you +don't need to use Czech/Slovak specific features\fnote +{Warnings: ``falling back to ASCII sorting'' +or ``CZ/SK outline-conversion is off'' may occur without \csplain{}.}. + + +\sec Font sizes +%%%%%%%%%%%%%%% + +The commands for font size setting described here have local validity. It +means that if you put them into group, the font sizes are selected locally. + +The command "\typosize[<fontsize>/<baselineskip>]" sets the font size of text and +math fonts and baselineskip. If one of these two parameters is empty, the +corresponding feature stays unchanged. The metric unit is supposed "pt" and +this unit isn't written in parameters. You can change the unit by the +command "\ptunit=<something-else>", for instance "\ptunit=1mm". +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[<font-factor>/<baselineskip-factor>]" +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 + +The sizes declared by these macros (for example in titles) are relative to +the basic size selected for the font (this may be arbitrary size, not only +10pt). + +The size of the current font can be changed by the command +"\thefontsize[<font-size>]" or can be rescaled by +"\thefontscale[<factor>]". These macros don't change math fonts sizes nor +baselineskip. + +The "\resizefont", "\regfont" and "\resizeall" commands (documented in +\csplain) can be used even if +the used format is not \csplain. The best +design size of the font for desired size is selected. +For example "\typosize[18/]" selects the font "cmr17 at 18pt". + +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 + + +\sec Parts of the document +%%%%%%%%%%%%%%%%%%%%%%%%%% + +The document can be divided into chapters, sections and subsections and titled +by "\tit" command. The parameters have to be separed by empty line (no +braces are used): + +\begtt +\tit Document title <empty line> +\chap Chapter title <empty line> +\sec Section title <empty line> +\secc Subsection title <empty line> +\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. OPmac 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[<label>]" command precedes. The reference commands are +"\ref[<label>]" and "\pgref[<label>]". Example: + +\begtt +\label[beatle] \sec About Beatles + +\label[comp-dependence] +\hfil\table{rl}{...} % the table +\caption/t The dependency of the computer-dependency on the age. + +\label[pythagoras] +$$ a^2 + b^2 = c^2 \eqmark $$ + +Now we can point to the section~\ref[beatle] on the page~\pgref[beatle] +or write about the equation~\ref[pythagoras]. Finally there +is an interesting Table~\ref[comp-dependence]. +\endtt + +If there are forward referenced objects then user have to run \TeX{} twice. +During each pass, the working "*.ref" file (with refereces data) is created +and this file is used (if it exists) at the begin of the document. + + +\sec Lists +%%%%%%%%%% + +The list of items is surrounded by "\begitems" and "\enditems" commands. +The asterisk ("*") is active within this environment and it starts one item. +The item style can be chosen by "\style" parameter written after "\begitems": + +\begtt +\style o % small bullet +\style O % big bullet (default) +\style - % hyphen char +\style n % numbered items 1., 2., 3., ... +\style N % numbered items 1), 2), 3), ... +\style i % numbered items (i), (ii), (iii), ... +\style I % numbered items I, II, III, IV, ... +\style a % items of type a), b), c), ... +\style A % items of type A), B), C), ... +\style x % small rectangle +\style X % big rectangle +\endtt + +Another style can be defined by the command "\sdef{item:<style>}{<text>}". +Default item can be redefined by "\def\normalitem{<text>}". +The list environments can be nested. Each new level of item is indented by +next multiple of "\iindent" which is set to "\parindent" by default. +The vertical space at begin and end of the environment is inserted by the +macro "\iiskip". + + +\sec Table of contents +%%%%%%%%%%%%%%%%%%%%%% + +The "\maketoc" command prints the table of contents of all "\chap", "\sec" +and "\secc" used in the document. These data are read from external "*.ref" file, so +you have to run \TeX{} more than once (typically three times if the table of +contents is at the beginning of the document). + +The name of the section with table of contents is not printed. The direct usage +of "\chap" or "\sec" isn't recommended here because the table of contents +is typically not referenced to itself. You can print the unnumbered and unreferenced +title of the section by the code: + +\begtt +\nonum\notoc\sec Table of Contents +\endtt + +The title of chapters etc.\ are written into the external file and they are +read from this file in a next run of \TeX. This technique can induce some +problems when a somewhat complicated macro is used in the title. OPmac +solves this problem by different way than \LaTeX. User can set the +problematic macro as ``robust'' by "\addprotect\macro" declaration. The +"\macro" itself cannot be redefined. The common macros used in OPmac which +can be occur in the titles are declared by this way. For example: + +\begtt +\addprotect~ \addprotect\TeX \addprotect\thefontsize \addprotect\em +\endtt + + +\sec Making the index +%%%%%%%%%%%%%%%%%%%%% + +The index can be included into document by "\makeindex" macro. No external +program is needed, the alphabetical sorting are done inside \TeX{} at macro +level. + +The "\ii" command (insert to index) declares the word separated by the space +as the index item. This declaration is represented as invisible atom on the +page connected to the next visible word. The page number of the page where +this atom occurs is listed in the index entry. So you can type: + +\begtt +The \ii resistor resistor is a passive electrical component ... +\endtt + +You cannot double the word if you use the "\iid" instead "\ii": + +\begtt +The \iid resistor is a passive electrical component ... +or: +Now we'll deal with the \iid resistor . +\endtt + +Note that the dot or comma have to be separated by space when "\iid" is +used. This space (before dot or comma) is removed by the macro in +the current text. + +The multiple-words entries are commonly organized in the index by the format +(for example): + +\medskip + +linear~dependency 11, 40--50 + +--- independency 12, 42--53 + +--- space 57, 76 + +--- subspace 58 + +\medskip + +To do this you have to declare the parts of the words by the "/" separator. +Example: + +\begtt +{\bf Definition.} +\ii linear/space,vector/space +{\em Linear space} (or {\em vector space}) is a nonempty set of... +\endtt + +The number of the parts of one index entry is unlimited. Note, that you can +spare your typing by the comma in the "\ii" parameter. The previous example +is equivalent to "\ii linear/space" "\ii vector/space". + +Maybe you need to propagate to the index the similar entry to the +linear/space in the form space/linear. You can do this by the shorthand ",@" +at the end of the "\ii" parameter. Example: + +\begtt +\ii linear/space,vector/space,@ +is equivalent to: +\ii linear/space,vector/space \ii space/linear,space/vector +\endtt + +If you really need to insert the space into the index entry, write ``"~"''. + +The "\makeindex" creates the list of alphabetically sorted index entries +without the title of the section and without creating more columns. OPmac +provides another macros for more columns: + +\begtt +\begmulti <number of columns> +<text> +\endmulti +\endtt + +The columns will be balanced. The Index can be printed by the following +code: + +\begtt +\sec Index\par +\begmulti 3 \makeindex \endmulti +\endtt + +Only ``pure words'' can be propagated to the index by the "\ii" command. It +means that there cannot be any macro, \TeX{} primitive, math selector etc. +But there is another possibility to create such complex index entry. Use +``pure equivalent'' in the "\ii" parameter and map this equivalent to the +real word which is printed in the index by "\iis" command. Example: + +\begtt +The \ii chiquadrat $\chi$-quadrat method is +... +If the \ii relax "\relax" command is used then \TeX\ is relaxing. +... +\iis chiquadrat {$\chi$-quadrat} +\iis relax {{\tt \char`\\relax}} +... +\endtt + +The "\iis <equivalent> {<text>}" creates one entry in the ``dictionary +of the exceptions''. The sorting is done by the "<equivalent>" but the +"<text>" is printed in the index entry list. + +The special sorting by the Czech or Slovak standard of alphabetical sorting +is activated if \csplain{} is used and if "\language" register is set to the +Czech or Slovak hyphenation patterns when "\makeindex" is in progress. The +main difference from English sorting is that ``ch'' is treated as one +character between h and i. + + +\sec Colors +%%%%%%%%%%% + +The colors selection macros are working only if pdf\TeX-like engine is used. +OPmac provides a small number of color selectors: +{\localcolor\Blue "\Blue"}, +{\localcolor\Red "\Red"}, +{\localcolor\Brown "\Brown"}, +{\localcolor\Green "\Green"}, +{\localcolor\Yellow "\Yellow"}, +{\localcolor\Cyan "\Cyan"}, +{\localcolor\Magenta "\Magenta"}, +{"\White"}, +{\localcolor\Grey "\Grey"}, +{\localcolor\LightGrey "\LightGrey"} and +"\Black". But user can define more +such selectors by setting the CMYK components. For example + +\begtt +\def\Orange{\setcmykcolor{0 0.5 1 0}} +\endtt + +The selectors itself change the color of the text and of the lines with the +thickness more than 1bp. If the "\linecolor" immediately precedes the color +selector then the lines with thickness less or equal 1bp are colored. This +is a second independent type of the color. + +The color selectors work globally on the one page. If the colored text is +broken to the next page then the color is correctly set on the following +page(s) after the second run of \TeX, because this event is implemented via +external file. User can write "\localcolor" inside the group. This command +saves the current color and restore it after the group is completed. It is +supposed that the group corresponds to the boundary of a box which cannot break +to more pages. If this is not true case then user can use "\longlocalcolor" +instead "\localcolor". Example: + +\begtt +\Red The text is red +\hbox{\loacalcolor \Blue here is blue {\localcolor \Green and green} + restored blue \Brown and brown} +now the text is red. +\endtt + +\def\coloron#1#2#3{% + \setbox0=\hbox{#3}\leavevmode + {\localcolor\rlap{#1\strut \vrule width\wd0}#2\box0}% +} +The more usable example follows. It defines a macro which creates the +\coloron\Yellow\Brown{colored text on the} +\coloron\Yellow\Brown{colored background}. Usage: +"\coloron<background><foreground>{<text>}" + +The "\coloron" can be defined as follows: + +\begtt +\def\coloron#1#2#3{% + \setbox0=\hbox{#3}\leavevmode + {\localcolor\rlap{#1\strut \vrule width\wd0}#2\box0}% +} +\coloron\Yellow\Brown{The brown text on the yellow backround} +\endtt + +{\bf The watermark} is grey text on the backrounf of the page. OPmac offers +an example: the macro "\draft" which creates grey scaled and rotated text +DRAFT on the background of every page. + + +\sec Hyperlinks, outlines +%%%%%%%%%%%%%%%%%%%%%%%%% + +If the command "\hyperlins{<color-in>}{<color-out>}" is used at the beginning of +the file, then the following objects are hyperlinked when PDF output is used: + +\begitems +* numbers generated by "\ref" or "\pgref", +* numbers of chapters, sections and subsections in the table of contents, +* numbers or marks generated by "\cite" command (bibliography references), +* texts printed by "\url" command. +\enditems + +The last object is an external link and it is colored by +"<color-out>". Others links are internal and they are colored by +"<color-in>". Example: + +\begtt +\hyperlinks \Blue \Green % internal links blue, URLs green. +\endtt + +You can use another marking of active links: by frames which are visible in +the PDF viewer but invisible when the document is printed. The way to do it +is to define the macros "\pgborder", "\tocborder", "\citeborder", +"\refborder" and "\urlborder" as the triple of RGB components of the used +color. Example: + +\begtt +\def\tocborder {1 0 0} % links in table of contents: red frame +\def\pgborder {0 1 0} % links to pages: green frame +\def\citeborder {0 0 1} % links to references: blue frame +\endtt + +By default these macros are not defined. It means that no frames are created. + +There are ``low level'' commands to create the links. You can specify the +destination of the internal link by "\dest[<type>:<label>]". The +active text linked to the "\dest" can be created by +"\link[<type>:<label>]{<color>}{<text>}". The "<type>" parameter is one of +the "toc", "pg", "cite", "ref" or another special for your purpose. + +The "\url" macro prints its parameter in "\tt" font and creates a potential +breakpoints in it (after slash or dot, for example). If "\hyperlinks" +declaration is used then the parameter of "\url" is treated as an external URL link. +An example: "\url{http://www.olsak.net}" creates \url{http://www.olsak.net}. +The charecters {\tt\%}, "\", "#", "$", "{" and "}" have to be protected by +backslash in the "\url" argument, the other special charecters "~", "_", +"^", "&" can be written as single character. You can insert the "\|" command +in the "\url" argument as a potential breakpoint. + +If the linked text have to be different than the URL, you can use +"\ulink[<url>]{text}" macro. For example: + +\begtt +\ulink[http://www.olsak.net/opmac-e.html]{OPmac page} +\endtt +creates +\ulink[http://www.olsak.net/opmac-e.html]{OPmac page}. + +The PDF format provides ``outlines'' which are notes placed in the special frame of +the PDF viewer. These notes can be managed as structured and hyperlinked +table of contents of the document. The command "\outlines{<level>}" creates +such outlines from data used for table of contents in the document. The +"<level>" parameter gives the level of opened sub-outlines +in the default view. The deeper levels can be open by mouse click on the +triangle symbol after that.\looseness=-1 + +The strings used in PDF outlines are converted if \csplain{} is used: the +accents are stripped off because they can make problems in outlines. But +user can use "\input pdfuni" in order to convert these strings to internal +UNICODE representation. + +The command "\insertoutline{<text>}" inserts next entry into PDF outlines at +the main level~0. This entry can be placed before table of contents (created +by "\outlines") or after it. + + +\sec Verbatim +%%%%%%%%%%%%% + +The display verbatim text have to be surrounded by the "\begtt" and +"\endtt" couple. +The inline verbatim have to be tagged (before and after) +by a character which is declared by +"\activettchar<char>". For example "\activettchar"{\tt\char`"} +declares the +{\tt\char`"} for inline verbatim markup. + +If the numerical register "\ttline" is set to the non-negative value then +display verbatim will number the lines. The first line has the number +"\ttline+1" and when the verbatim ends then the "\ttline" value is equal to the +number of last line printed. Next "\begtt...\endtt" environment will follow +the line numbering. OPmac sets "\ttline=-1" by default. + +The indentation of each line in display verbatim is controlled by +"\ttindent" register. This register is set to the "\parindent" when +"opmac.tex" is read. User have to change its value if the "\parindent" is +changed after reading of "opmac.tex". + +The "\begtt" starts internal group in which the catcodes are changed. Then +the "\tthook" macro is run. This macro is empty by default and user can +control fine behavior by it. For example the cactodes can be reset here. If +you need to define active character in the "\tthook", use "\adef" as in the +following example: + +{\def\tthook{\adef@{\string\endtt}} +\begtt +\def\tthook{\adef!{?}\adef?{!}} +\begtt +Each occurrence of the exclamation mark will be changed to +the question mark and vice versa. Really? You can try it! +@ +\endtt +} + +The "\adef" command sets its parameter as active {\it after\/} +the body of "\tthook" is read. So you can't worry about active +categories. + +There are tips for global "\tthook" definitions here: + +\begtt +\def\tthook{\typosize[9/11]} % setting font size for verbatim +\def\tthook{\ttline=0} % each listing will be numbered from one +\def\tthook{\adef{ }{\char`\ }} % visualisation of spaces +\endtt + +You can print verbatim listing from external files by "\verbinput" command. +Examples: + +\begtt +\verbinput (12-42) program.c % listing from program.c, only lines 12-42 +\verbinput (-60) program.c % print from begin to the line 60 +\verbinput (61-) program.c % from line 61 to the end +\verbinput (-) program.c % whole file is printed +\verbinput (70+10) program.c % from line 70, only 10 lines printed +\verbinput (+10) program.c % from the last line read, print 10 lines +\vebrinput (-5+7) program.c % from the last line read, skip 5, print 7 +\verbinput (+) program.c % from the last line read to the end +\endtt + + +The "\ttline" influences the line numbering by the same way as in +"\begtt...\endtt" environment. If "\ttline=-1" then real line numbers are +printed (this is default). If "\ttline"{\tt\char`\<-1} then no line +numbers are printed. + +The "\verbinput" can be controlled by "\tthook", "\ttindent" just like +in "\begtt...\endtt". + + +\sec Tables +%%%%%%%%%%% + +The macro "\table{<declaration>}{<data>}" provides similar "<declaration>" +as in \LaTeX: you can use letters "l", "r", "c", each letter declares +one column (aligned to left, right, center respectively). +These letters can be combined by the ``{\tt\char`\|}'' character +(vertical line). Example + +\begtt +\table{||lc|r||}{ \crl + Month & commodity & price \crli + \tskip.2em + January & notebook & \$ 700 \cr + February & skateboard & \$ 100 \cr + July & yacht & k\$ 170 \crl} +\endtt +% +generates the following result: + +\bigskip +\table{||lc|r||}{ \crl + Month & commodity & price \crli + \tskip.2em + January & notebook & \$ 700 \cr + February & skateboard & \$ 100 \cr + July & yacht & k\$ 170 \crl} +\bigskip + +The command "\cr" is generally known. Moreover OPmac defines following similar +commands: + +\begitems +* "\crl" \dots\ the end of the row with a horizontal line after it. +* "\crli" \dots\ like "\crl" but the horizontal line doesn't intersect the + vertical double lines. +* "\crlli" \dots\ like "\crli" but horizontal line is doubled. +\enditems + +The "\tskip<dimen>" command works like the "\noalign{\vskip<dimen>}" +after "\cr*" commands but it doesn't interrupt the vertical lines. + +The configuration macros for "\table" are defined in the following listing +with their default values: + +\begtt +\def\tabiteml{\enspace} % left material in each column +\def\tabitemr{\enspace} % right material in each column +\def\tabstrut{\strut} % strut inserted in each line +\def\vvkern{1pt} % space between double vertical line +\def\hhkern{1pt} % space between double horizontal line +\endtt + +If you do "\def\tabiteml{$\enspace}\def\tabitemr{\enspace$}" then +the "\table" acts like \LaTeX's array environment. + +The "\frame{<text>}" makes a frame around "<text>". You can put the whole "\table" +into "\frame" if you need double-ruled border of the table. Example: + +\begtt +\frame{\table{|c||l||r|}{\crl + \multispan3\vrule\hss\bf Title\hss \vrule\tabstrut \crl + \noalign{\kern\hhkern}\crli + first & second & third \crlli + seven & eight & nine \crli}} +\endtt +% +creates the following result: + +\bigskip +\frame{\table{|c||l||r|}{\crl + \multispan3\vrule\hss\bf Title\hss \vrule\tabstrut \crl + \noalign{\kern\hhkern}\crli + first & second & third \crlli + seven & eight & nine \crli}} +\bigskip + +The "c", "l" and "r" are default <declaration> letters but you can define +more such letters by "\def\tabdeclare<letter>{<left>##<right>}". For +example: + +\begtt +\newdimen\Pwidth +\def\tabdeclareP {\enskip\vtop{\hsize=\Pwidth \rightskip=0pt plus1fil + \baselineskip=1.2em\lineskiplimit=0pt\noindent##\tabstrutA}\hss\enskip} +\endtt +% +declares the letter P which means the tabular column with "\vtop"s. This is +similar to \LaTeX's parbox. + +The rule width of tables (and implicit width of all "\vrule"s and "\hrule"s) +can be set by the command "\rulewidth=<dimen>". The default value given +by \TeX{} is 0.4pt. + +Many tips about tables can be seen on +\url{http://petr.olsak.net/opmac-tricks.html}. + +\sec Images +%%%%%%%%%%% + +The "\inspic <filename>.<extension><space>" inserts the picture stored in +the graphics file with the name "<filename>.<extension>". +You can set the picture width by "\picw=<dimen>" before first "\inspic" command +which declares the width of the picture. +The files can be in the PNG, JPG, JBIG2 or PDF format. The "\inspic" command +works with pdf\TeX{}/Xe\TeX{} only. + +The "\picwidth" is an equivalent register to "\picw". Moreover there is an +"\picheight" register which denotes the height of the picture. If both +registers are set then the picture will be (probably) deformed. + +The file is searched in "\picdir". This macro is empty by default, this +means that the file is searched in current directory. + +\sec PDF transformations +%%%%%%%%%%%%%%%%%%%%%%%% + +All typesetting elements are transformed in pdf\TeX{} by linear +transformation given by the current transformation matrix. The +"\pdfsetmatrix {<a> <b> <c> <d>}" command makes the internal multiplication +with the current matrix so linear transformations can be composed. The +stack-oriented commands "\pdfsave" and "\pdfrestore" gives a possibility of +storing and restoring the current transformation matrix and current point. +The possition of current point have to be the same from \TeX{}'s point of +view as from transformation point of view when "\pdfrestore" is processed. +Due to this fact the "\pdfsave\rlap{<transformed text>}\pdfrestore" +or something similar is recomeded. + +OPmac provides the macros + +\begtt +\pdfscale{<horizontal-factor>}{<vertical-factor>} +\pdfrotate{<angle-in-degrees>} +\endtt + +These macros simply calls the +properly "\pdfsetmatrix" primitive command. + +It is known that the comosition of transformations is not commutative. It +means that the order is important. You have to read the tranformation +matrices from right to left. Example: + +\begtt +First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore + % text1 is scaled two times and it is reflected about vertical axis + % and next it is rotated by 30 degrees left. +second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore + % text2 is rotated by 30 degrees left then it is scaled two times + % and reflected about vertical axis. +third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}% + \pdfrestore % first slanted, then rotated by 15.3 degrees right +\endtt + +\bigskip\smallskip +This gives the following result. +First: \pdfsave \pdfrotate{30}\pdfscale{-2}{2}\rlap{text1}\pdfrestore +second: \pdfsave \pdfscale{-2}{2}\pdfrotate{30}\rlap{text2}\pdfrestore +third: \pdfsave \pdfrotate{-15.3}\pdfsetmatrix{2 0 1.5 2}\rlap{text3}\pdfrestore +\bigskip\bigskip + +\sec Footnotes and marginal notes +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The plain\TeX{}'s macro "\footnote" is not redefined. But a new macro +"\fnote{<text>}" is defined. The footnote mark is added automatically and it +is numbered on each page from one\fnote +{This behavior is changed if {\tt\char`\\runningfnotes} is used: +the footnotes are numbered from one in whole document in such case. +Alternatives are possible, see OPmac tricks or technical documentation.}. +The "<text>" is scaled by +"\typoscale[800]". The implicit visual aspect of the footnote mark is defined by +"\def\thefnote{$^{\locfnum}$)}". User can redefine it, for example: + +\begtt +\def\thefnote{\ifcase\locfnum\or + *\or**\or***\or$^{\dag}$\or + $^{\ddag}$\or$^{\dag\dag}$\fi} +\endtt + +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 you can use "\fnotemark<number>" inside the box (only the footnote mark is +generated). When the box is finished you can use "\fnotetext{<text>}". This +macro puts the "<text>" to the footnote. The "<number>" after "\fnotemark" +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. + +The marginal note can be printed by the "\mnote{<text>}" macro. The <text> +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. If you need to place the +notes only to the fixed margin write "\fixmnotes\right" or +"\fixmnotes\left". + +The <text> 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 is at the same height as +the invisible mark created by "\mnote" in the current paragraph. The +exceptions are possible by "\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{<text>}" shifts this (and only this) note +two lines up. + + +\sec Bib\TeX ing +%%%%%%%%%%%%%%%% + +The command "\cite[<label>]" or its variations of the type +\hbox{"\cite[<label-1>,<label-2>,<label-3>]"} +create the citations in the form [42] or [15,~19,~26]. +If "\shortcitations" is declared at the beginning of the document then continuous sequences of +numbers are re-printed like this: \hbox{[3--5,~7,~9--11]}. If +"\sortcitations" is declared then numbers generated by one "\cite" command +are sorted upward. + +If "\nonumcitations" is used then the marks instead numbers are generated +depending on the used bib\TeX{} style. For example the citations look like +[Now08] when "alpha" style is used and like [Nowak, 2008] when "apalike" +style is used. + +The "\rcite[<labels>]" creates the same list as "\cite[<labels>]" but without +the outer brackets. Example: "[\rcite[tbn], pg.~13]" creates [4,~pg.13]. + +The "\ecite[<label>]{<text>}" prints the "<text>" only, but the entry labeled +"<label>" is decided as to be cited. If "\hyperlinks" is used then "<text>" +is linked to the references list. + +You can define alternative formating of "\cite" command. Example: + +\begtt +\def\cite[#1]{(\rcite[#1])} % \cite[<label>] creates (27) +\def\cite[#1]{$^{\rcite[#1]}$} % \cite[<label>] creates^{27} +\endtt + +The numbers printed by "\cite" correspond to the same numbers generated in +the list of references. There are four possibilities to generate this +references list: + +\begitems +* Manually using "\bib[<label>]" commands. +* Using bib\TeX{} and "\usebibtex{<bib-base>}{<bib-style>}" command. +* Using pregenerated "*.bbl" file and "\usebbl/<type> <bbl-base>" command. +* By "\usebib/<type> (<style>) <bbl-base>" command which reads "*.bib" + databases directly. +\enditems + +These possibilities are documented here in detail: + +\medskip\noindent +{\bf References created manually using "\bib[<label>]" command.} + +{\def\tthook{\catcode`/=0 \catcode`+=9 } +\begtt +\bib [tbn] P. Ol/v+s/'ak. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 1997. +\bib [tst] P. Ol/v+s/'ak. {\it Typografick/'y syst/'em \TeX.} + 269~s. Praha: CSTUG, 1995. +\endtt +} + +If you are using "\nonumcitations" then you need to declare the "<marks>" +used by "\cite" command. To do it you have to use long form of the "\bib" +command which is in the format "\bib[<label>] = {<mark>}". The spaces around +equal sign are mandatory. Example: + +{\def\tthook{\catcode`/=0 \catcode`+=9 } +\begtt +\bib [tbn] = {Olšák, 2001} + P. Ol/v+s/'ak. {\it\TeX{}book naruby.} 468~s. Brno: Konvoj, 2001. +\endtt +} + +{\bf References using bib\TeX.} +The command "\usebibtex{<bib-base>}{<bst-style>}" + creates the list of cited entries and entries indicated by +"\nocite[<label>]". +After first \TeX{} run the "*.aux" file is created, so user have to run +the bib\TeX{} by the command "bibtex <document>". After second \TeX{} run +the bib\TeX's +output is read and after third \TeX{} run all references are properly +created. + +The "<bib-base>" is one or more "*.bib" database source files (separated by +spaces and without extension) and the "<bst-style>" is the style used by +bib\TeX. The common styles are "plain", "alpha", "apalike", "ieeetr", +"unsrt". + +\medskip\noindent +{\bf Using pregenerated "*.bbl" file by bib\TeX.} +You can create the temporary file ("mybase.tex", for example) +which looks like: + +\begtt +\input opmac +\genbbl{<bib-base>}{<bst-style>} +\end +\endtt +% +After first \TeX{} run the "mybase.aux" is generated. Then you can run +"bibtex mybase" which generates the ".bbl" file with all entries from the +"<bib-base>" "*.bib" file(s). Second \TeX{} run on the file "mybase.tex" generates +the printed form of the list of all bib entries with labels. This is usable +printed matter, you can place it to your notice board when you create +your document. Finally you can insert to your real document one of the +following commands: + +\begtt +\usebbl/a mybase % print all entries from mybase.bbl (a=all) +\usebbl/b mybase % print only \cited and \nocided entries + % sorted by mybase.bbl (b=bbl) +\usebbl/c mybase % print only \cited and \nocited entries + % sorted by \cite-order (c=cite) +\endtt + +Sometimes the pure \LaTeX{} command occurs (unfortunately) +in the ".bib" database or bib\TeX{} +style. User can define such commands in the "\bibtexhook" macro which is a +hook started inside the group before ".bbl" file is read. Example: + +\begtt +\def\bibtexhook{\def\emph##1{{\em##1}}\def\frac##1##2{{##1\over##2}}} +\endtt + +\noindent +{\bf Direct reading of ".bib" files} is possible after "\input opmac-bib". +This package uses the external package "librarian.tex" by Paul Isambert. +The usage is similar to previous case: + +\begtt + % print only \cited and \nocited entries +\usebib/c (<style>) <bib-base> % sorted by \cite-order (c=cite), +\usebib/s (<style>) <bib-base> % sorted by style (s=style). +\endtt + +The "<bib-base>" is one or more "*.bib" database source files (separated by +spaces and without extension) and the "<style>" is the part of the filename +"opmac-bib-<style>.tex" where the formatting of the references list is +defined. Possible styles are "simple" or "iso690". The behavior of +"opmac-bib.tex" and "opmac-bib-iso690.tex" is full documented in these files +(after "\endpinput" command). + +\medskip\noindent +{\bf Formatting of the references list} is controlled by the "\printb" macro. +It is called at the begin of each entry. The default "\printb" macro prints +the number of the entry in square brackets. If the "\nonumcitations" is set +then no numbers are printed, only all lines (but no first one) are indented. +The "\printb" macro can use the following values: "\the\bibnum" (the number +of the entry) and "\the\bibmark" (the mark of the entry used when +"\nonumcitations" is set). Examples: + +\begtt +% The numbers are without square brackets: +\def\printbib{\hangindent=\parindent \indent \llap{\the\bibnum. }} +% Printing of <marks> when \nonumcitations is set: +\def\printbib{\hangindent=\parindent \noindent [\the\bibmark]\quad} +\endtt + +Next examples can be found on the +\ulink[http://petr.olsak.net/opmac-tricks.html]{OPmac tricks WWW page}. + + +\sec Typesetting math +%%%%%%%%%%%%%%%%%%%%% + +There are two files for math typesetting prepared in \csplain: + +\begitems +* "ams-math.tex" loads the AMS math fonts visual compatible with Computer + modern. +* "tx-math.tex" loads the TX fonts visual compatible with Times. +\enditems + +OPmac reads the first file "ams-math.tex" by default. If you are using font +files from \csplain{} ("ctimes.tex", "cbookman.tex", "cs-termes.tex" etc.) +then the second math-file "tx-math.tex" is loaded. + +This section describes the features of the macros from "ams-math.tex" or +"tx-math.tex". More documentation is written in these files themselves. + +Hundreds math symbols and operators like in AMS\TeX{} are accesible. +For example "\alpha" $\alpha$, "\geq" $\geq$, "\sum" $\sum$, +"\sphericalangle" $\sphericalangle$, "\bumpeq", $\bumpeq$. See AMS\TeX{} +manual (or TX-fonts manual) for complete list of symbols. + +The following math alphabets are available: + +{\def\tthook{\catcode`\$=3 \catcode`/=0 \medmuskip=0mu}% +\begtt +\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 regardless +current text font family. The reason is that these shapes are used for +vectors and matrices in Czech math typesetting. + +The math fonts are 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. +There is an example for math typesetting in titles: + +\begtt +\def\title#1\par{\centerline{\typosize[17/]\bf\boldmath #1}} +\title The title with math $\int_a^b f(x) {\rm d}x$ is here +\endtt + +Variables are printed by special math italics when "ams-math.tex" is loaded +and by text italics of the current text font when "tx-math.tex" is loaded. +You can change this behavior by following commands: + +\begtt +\itvariables % variables typeset by text italics. +\mitvariables % mariables typeset by math italics. +\endtt + + +\sec Setting the margins +%%%%%%%%%%%%%%%%%%%%%%%% + +OPmac declares 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 "\margins" command declares margins of the document. This command have +the following parameters: + +\begtt +\margins/<pg> <fmt> (<left>,<right>,<top>,<bot>)<unit> + example: +\margins/1 a4 (2.5,2.5,2,2)cm +\endtt + +Parameters are: + +\begitems +* <pg> \dots\ "1" or "2" specifies one-page or two-pages design. +* <fmt> \dots\ paper format (a4, a4l, etc.). +* <left>, <right>, <top>, <bot> \dots\ gives the amount of left, right, + top and bottom margins. +* <unit> \dots\ unit used for values <left>, <right>, <top>, <bot>. +\enditems + +Each of the parameters <left>, <right>, <top>, <bot> can be empty. +If both <left> and <right> are nonempty then "\hsize" is set. Else "\hsize" +is unchanged. If both <left> and <right> are empty then typesetting area is +centered in the paper format. The analogical rule works when <top> or <bot> +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 "<pg>=1" then all pages have the same margins. If "<pg>=2" then the +declared margins are true for odd pages. The margins at the even pages are +mirrored in such case, it means that <left> is replaced by <right> and vice +versa. + +The command "\magscale[<factor>]" scales the whole typesetting area. The +fixed point of such scaling is the so called the ``Knuth's point'': 1in +below and 1in right of paper sides. 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. + +\sec The last page +%%%%%%%%%%%%%%%%%% + +The number of the last page (it may be different from number of pages) is +stored in the "\lastpage" register after first \TeX{} run if the working "*.ref" +file is open. This file isn't open for every documents; only for those +where the forward references are printed or table of contents is created. +If the "*.ref" file isn't open for your document and you need to use the "\lastpage" +register then you have to write the command "\openref". This command opens +the "*.ref" file immediatelly. + +There is an example for footlines in the format ``current page / last +page'': + +\begtt +\footline={\hss \rm \thefontsize[10]\the\pageno/\the\lastpage \hss} +\endtt + +\sec Summary +%%%%%%%%%%%% + +\def\tthook{\adef!{\string\endtt}\adef&{\kern.25em}} +\begtt +\tit Title (terminated by a blank line) +\chap Chapter Title (terminated by a blank line) +\sec Section Title (terminated by a blank line) +\secc Subsection Title (terminanted by a blank line) + +\maketoc % table of contents generation +\ii item1,item2 % insertion the items to the index +\makeindex % the index is generated + +\label [labname] % link target location +\ref [labname] % link to the chapter, section, subsection, equation +\pgref [labname] % link to the page of the chapter, section, ... + +\caption/t % a numbered table caption +\caption/f % a numbered caption for the picture +\eqmark % a numbered equation + +\begitems % start list of the items +\enditems % end of list of the items +\begtt % start verbatim text +! % end verbatim text +\activettchar X % initialization character X for in-text verbatim +\verbinput % verbatim extract from the external file +\begmulti num % start multicolumn text (num columns) +\endmulti % end multicolumn text + +\cite [labnames] % refers to the item in the lits of references +\rcite [labnames] % similar to \cite but [] are not printed. +\sortcitations \shortcitations \nonumcitations % cite format +\bib [labname] % an item in the list of references +\usebibtex {bib-base}{bst-style} % use BibTeX for bibliography +\genbbl {bib-base}{bst-style} % prepare the bbl file generation +\usebbl/? bbl-base % use pre-generated bbl file, ? in {a,b,c} +\usebib/? (style) bib-base % direct using of .bib file, ? in {s,c} + +\typosize [font-size/baselineskip] % size setting of typesetting +\typoscale [factor-font/factor-baselineskip] % size scaling +\thefontsize [size] \thefontscale [factor] % current font size + +\inspic file.ext % insert a picture, extensions: jpg, png, pdf +\table {rule}{data} % simple macro for the tables like in LaTeX + +\fnote % footnote (local numbering on each page) +\mnote % note in the margin (left or right by page number) + +\hyperlinks {color-in}{color-out} % PDF links activate as clickable +\outlines {level} % PDF will have a table of contents in the left tab + +\magscale[factor] % resize typesetting, line/page breaking unchanged +\margins/pg format (left, right, top, bottom)unit % margins setting +\endtt + +\end |