From 1450af3d3e883477599a3de6492b6cfdb8f2fba4 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 15 Apr 2016 21:39:56 +0000
Subject: cstex (15apr16)

git-svn-id: svn://tug.org/texlive/trunk@40539 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/cstex/opmac-u-en.tex | 183 ++++++++++++++++++++++++-----
 1 file changed, 155 insertions(+), 28 deletions(-)

(limited to 'Master/texmf-dist/doc/cstex/opmac-u-en.tex')

diff --git a/Master/texmf-dist/doc/cstex/opmac-u-en.tex b/Master/texmf-dist/doc/cstex/opmac-u-en.tex
index c81b6c9ac19..5cc91d877c9 100644
--- a/Master/texmf-dist/doc/cstex/opmac-u-en.tex
+++ b/Master/texmf-dist/doc/cstex/opmac-u-en.tex
@@ -5,14 +5,16 @@
 
 \typosize[11/13]
 
-\def\thefnote{$^{\locfnum}$}
+%\def\thefnote{$^{\locfnum}$}
+\addto\footstrut{\hang}
 
 \catcode`<=13
 \def<#1>{\hbox{$\langle$\it#1\/$\rangle$}}
 
 \activettchar"
 
-\insertoutline{CONTENTS} \outlines{0} \hyperlinks{\Blue}{\Green}
+\hyperlinks{\Blue}{\Green}
+\insertoutline{CONTENTS} \outlines{0} 
 
 
 \tit OPmac -- macros for plain\TeX\fnotemark1
@@ -27,7 +29,8 @@
 \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
+\notoc\nonum \sec Contents
+\maketoc
 
 \nonum \sec Introduction
 %%%%%%%%%%%%
@@ -67,7 +70,7 @@ 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
+package, however, does not care for the typography 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.
@@ -76,7 +79,7 @@ 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.
+mentioned on \url{http://petr.olsak.net/opmac-tricks-e.html} page.
 
 \secnum=-1
 
@@ -96,8 +99,9 @@ Here is a text.
 \bye
 \endtt
 
-You can use \TeX, pdf\TeX, Xe\TeX{} or lua\TeX{} with "etex.src" or \csplain{}
-preloaded. The \csplain{} is recommended but it is not explicitly requested if you
+You can use \TeX, pdf\TeX, Xe\TeX{} or lua\TeX{} with plain \TeX{} format 
+(classical "plain.tex", "etex.src" or \csplain{}).
+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{}.}.
@@ -183,14 +187,14 @@ This is {\em important} text.     % = This is {\it important\/} text.
 %%%%%%%%%%%%%%%%%%%%%%%%%%
 
 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
+by "\tit" command. The parameters are separed by the end of current 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>
+\tit Document title <end of line>
+\chap Chapter title <end of line>
+\sec Section title <end of line>
+\secc Subsection title <end of line>
 \endtt
 
 The chapters are numbered by one number, sections by two numbers
@@ -555,7 +559,7 @@ DRAFT on the background of every page.
 \sec Hyperlinks, outlines
 %%%%%%%%%%%%%%%%%%%%%%%%%
 
-If the command "\hyperlins{<color-in>}{<color-out>}" is used at the beginning of
+If the command "\hyperlinks{<color-in>}{<color-out>}" is used at the beginning of
 the file, then the following objects are hyperlinked when PDF output is used:
 
 \begitems
@@ -597,7 +601,7 @@ 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
+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.
@@ -606,10 +610,10 @@ 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}
+\ulink[http://petr.olsak.net/opmac-e.html]{OPmac page}
 \endtt
 creates
-\ulink[http://www.olsak.net/opmac-e.html]{OPmac page}.
+\ulink[http://petr.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
@@ -798,7 +802,7 @@ 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}.
+\url{http://petr.olsak.net/opmac-tricks-e.html}.
 
 \sec Images
 %%%%%%%%%%%
@@ -874,11 +878,16 @@ 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:
+"\def\thefnote{$^{\locfnum}$}".
+%\fnote{%
+%   Note the right parenthesis in the mark. This isn't bug, this is used in Czech
+%   traditional typography. If you need to remove it, you can define
+%   {\def\s{\string}\tt\s\def\s\thefnote\s{\$\s^\s{\s\locfnum\s}\$\s}}.
+%   }.
+User can redefine it, for example:
 
 \begtt
-\def\thefnote{\ifcase\locfnum\or
-   *\or**\or***\or$^{\dag}$\or
+\def\thefnote{\ifcase\locfnum\or *\or**\or***\or$^{\dag}$\or
    $^{\ddag}$\or$^{\dag\dag}$\fi}
 \endtt
 
@@ -1064,7 +1073,7 @@ of the entry) and "\the\bibmark" (the mark of the entry used when
 \endtt 
 
 Next examples can be found on the 
-\ulink[http://petr.olsak.net/opmac-tricks.html]{OPmac tricks WWW page}.
+\ulink[http://petr.olsak.net/opmac-tricks-e.html]{OPmac tricks WWW page}.
 
 
 \sec Typesetting math
@@ -1092,7 +1101,7 @@ manual (or TX-fonts manual) for complete list of symbols.
 
 The following math alphabets are available:
 
-{\def\tthook{\catcode`\$=3 \catcode`/=0 \medmuskip=0mu}%
+{\def\tthook{\catcode`\$=3 \catcode`/=0 \medmuskip=0mu \adef{ }{ }}%
 \begtt
 \mit     % mathematical variables    $abc-xyz,ABC-XYZ$
 \it      % text italics              $/it abc-xyz,ABC-XYZ$
@@ -1128,6 +1137,11 @@ You can change this behavior by following commands:
 \itvariables  % variables typeset by text italics.
 \mitvariables % variables typeset by math italics.
 \endtt
+%
+{\bf Note:} Due to the features described in this section (AMS symbols, "\bbchar",
+"\script", "\frak" characters and sans serif bold in math) more special fonts are loaded
+(from AMS package and from EC fonts). If you dislike such dependency, you
+can follow the \ulink[http://petr.olsak.net/opmac-tricks-e.html\#onlycm]{OPmac trick 0111}.
 
 
 \sec Setting the margins
@@ -1179,8 +1193,8 @@ mirrored in such case, it means that <left> is replaced by <right> and vice
 versa.
 
 The "<fmt>" can be in the form "(<width>,<height>)<unit>" where "<unit>" is
-optional. If it is missing then "<unit>" after margins sspecification is
-used. Fo example:
+optional. If it is missing then "<unit>" after margins specification is
+used. For example:
 
 \begtt
 \margins/1 (100,200) (7,7,7,7)mm
@@ -1224,15 +1238,128 @@ page'':
 \footline={\hss \rm \thefontsize[10]\the\pageno/\the\lastpage \hss}
 \endtt
 
+\sec Using other language
+%%%%%%%%%%%%%%%%%%%%%%%%%
+
+OPmac supports all languages but only English, Czech and Slovak languages
+are immediately ready for use. When using another language, you have to do
+little more work. First of all, use \TeX{} engine and \TeX{} format ready
+for such language (with hyphenation patterns preloaded). In order to not
+fall to the ``encoding hell'', I recommend to use Unicode engine ("xetex" or
+"luatex") and to use Unicode font family where all characters and letters
+needed for your language are prepared.
+
+The "xetex" and "luatex" run with e\TeX{} plain format (generated from
+"etex.src" sources) by default. This format includes hyphenation tables for
+all languages. For example, you can select Spanish language by
+"\uselanguage{espanol}".
+
+OPmac needs to know the translation of three auto-generated words
+``Chapter'', ``Table'' and ``Figure'' for selected language. And this
+language is marked by its ISO 639-1 code, "es" for Spanish, for example.
+
+If you are using e\TeX{} plain format you
+must set the connection between long language name and short ISO code 
+by the macro "\isolangset{<long-name>}{<iso-code>}". This command does nothing if
+\csplain{} is used, because \csplain{} sets ISO codes during format generation.
+
+The full example with Spanish language follows. Use "xetex example"
+or "luatex example" for compiling this.
+
+\mubyte \ntie ^^c3^^b1\endmubyte \def\ntie{\~n}
+\mubyte \ccedilla ^^c3^^a7\endmubyte \def\ccedilla{\c c}
+\mubyte \Ccedilla ^^c3^^87\endmubyte \def\Ccedilla{\c C}
+
+\begtt
+\input opmac
+
+\ifx\directlua\undefined \else \ifx\luafonts\undefined \input luafonts
+\fi\fi  % lua code to re-define \font primitive, irrelevant in XeTeX
+
+\font\tenrm="DejaVu Serif"    % Unicode font family, 
+\font\tenbf="DejaVu Serif/B"  % where all needed characters are ready  
+\font\tenit="DejaVu Serif/I"
+\font\tenbi="DejaVu Serif/IB"
+\tenrm
+
+\input tx-math   % Math setting using TX fonts
+
+\isolangset {espanol}{es}
+\sdef{mt:chap:es}{Capítulo}   % Chapter in es
+\sdef{mt:t:es}{Cuadro}        % Table in es
+\sdef{mt:f:es}{Figura}        % Figure in es
+
+\uselanguage{espanol} % Spanish hyphenation + autogenerated words
+\typosize[12/14.4]
+
+\tit Mañana
+
+\sec Mañana
+
+Mañana.
+
+\caption/f Test % generates the text "Figura 1.1 Test"
+
+\bye
+\endtt
+
+When sorting the index by "\makeindex" in the non-\csplain{} format, OPmac
+writes a warning: ``falling back to ASCII sorting''.
+If you want to use sorting rules given for your language, 
+you must define the macro "\sortingdata<iso-code>". And you can optionally
+define the "\specsortingdata<iso-code>" macro. Example:
+{\emergencystretch=2em\par}
+
+\begtt
+\def\sortingdataes {aAäÄáÁ,bB,cCçÇ,^^P^^Q^^R,dD,...,zZ,.}
+\def\specsortingdataes {ch:^^P Ch:^^Q CH:^^R}
+\endtt
+
+There are groups of letters separated by comma and ended by comma-dot in
+the macro "\sortingdata<iso-code>". (In the example above, three dots must
+be replaced by real data by the user.) All letters in one group are not
+distinguished during first step of sorting (primary sorting). If some items
+are equal from this point of view then the secondary sorting is processed
+for such items where all mentioned letters are distinguished in the order
+given in the macro. 
+
+Sorting algorithm can treat couple of letters (like Dz, Ch etc.) as one letter 
+if the macro "\specsortingdata<iso-code>" is defined. There is
+a space separated list of items in the form "<couple>:<one-token>". The
+replacing from <couple> to <one-token> is done before sorting, so you can
+use "<one-token>" in the "\sortingdata<iso-code>" macro. The "<one-token>"
+must be something special not used as the letter of the alphabet. The usage of "^^A",
+"^^B" etc. is recommended but you must avoid the "^^I" and "^^M" because
+these characters have special catcode.
+
+The macro "\sortingdata<iso-code>" (if it is defined and the hyphenation of
+given language is selected) has precedence before an internal "\sortingdata"
+defined in OPmac. The internal "\sortingdata" are optimized for Czech,
+Slovak and English languages.
+
+The list of ignored characters for sorting point of view is defined in the
+"\setignoredchars" macro. OPmac defines this macro like:
+
+{\catcode`\<=12
+\begtt
+\def\setignoredchars{\setlccodes ,.;.?.!.:.'.".|.(.).[.].<.>.=.+.{}{}}
+\endtt
+}%
+It means that comma, semicolon, question mark, \dots, plus mark are treated
+as dot and dot is ignored by sorting algorithm. You can redefine this macro,
+but you must keep the format, keep "\setlccodes" in the front and "{}{}" in
+the end.
+
+
 \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)
+\tit Title (terminated by end of line)
+\chap Chapter Title (terminated byend of line)
+\sec Section Title (terminated by end of line)
+\secc Subsection Title (terminanted by end of line)
 
 \maketoc         % table of contents generation
 \ii item1,item2  % insertion the items to the index
-- 
cgit v1.2.3

