diff options
Diffstat (limited to 'macros/luatex/optex/base/prefixed.opm')
-rw-r--r-- | macros/luatex/optex/base/prefixed.opm | 138 |
1 files changed, 71 insertions, 67 deletions
diff --git a/macros/luatex/optex/base/prefixed.opm b/macros/luatex/optex/base/prefixed.opm index 8eb851cc2a..ff6dffa20a 100644 --- a/macros/luatex/optex/base/prefixed.opm +++ b/macros/luatex/optex/base/prefixed.opm @@ -1,4 +1,4 @@ -%% This is part of OpTeX project, see http://petr.olsak.net/optex +%% This is part of the OpTeX project, see http://petr.olsak.net/optex \_codedecl \public {Prefixing and code syntax <2020-02-14>} % preloaded in format @@ -18,7 +18,7 @@ \_doc ------------------ \`\ea` is useful shortcut for `\expandafter`. We recommend to use always the - private form of \`\_ea` + private form of \`\_ea` because there is high probability that `\ea` will be redefined by the user. \nl \`\public` `<sequence> <sequence> ... ;` does @@ -47,10 +47,10 @@ \_doc ----------------------- Each macro file should begin with \`\_codedecl` `\macro {<info>}`. If the `\macro` is defined already then the `\endpinput` protects to read - such file more than one times. Else the <info> is printed to the terminal + such file more than once. Else the <info> is printed to the terminal and the file is read.\nl - The {\`\_endcode`} is defined as `\endinput` in the `optex.ini` file. - \`\wterm` `{<text>}` prints `<text>` + The {\`\_endcode`} is defined as `\endinput` in the `optex.ini` file. + \`\wterm` `{<text>}` prints `<text>` to the terminal and to the `.log` file (as in plain \TeX/). \_cod ----------------------- @@ -100,7 +100,10 @@ } \_def \_nspublic {\_xargs \_nspublicA} -\_def \_nspublicA #1{\_ea\_let \_ea#1\_csname \_pkglabel _\_csstring #1\_endcsname} +\_def \_nspublicA #1{% + \_unless\_ifx #1\_undefined + \_opwarning{\_ea\_ignoreit\_pkglabel\_space redefines the meaning of \_string#1}\_fi + \_ea\_let \_ea#1\_csname \_pkglabel _\_csstring #1\_endcsname} \_def \_nsprivate {\_xargs \_nsprivateA} \_def \_nsprivateA #1{\_ea\_let \_csname \_pkglabel _\_csstring #1\_endcsname =#1} @@ -109,67 +112,67 @@ \_endcode %---------------------------------------------------- -\sec Concept of name spaces of control sequences +\sec[prefixed] Concept of namespaces of control sequences \secc Prefixing internal control sequences -All control sequences used in \OpTeX/ are used and defined with `_` prefix. +All control sequences used in \OpTeX/ are used and defined with `_` prefix. The user can be sure that when he/she does `\def\foo` then internal macros of \OpTeX/ nor \TeX/ primitives will be not damaged. For example -`\def\if{...}` will not damage macros because \OpTeX/'s macros +`\def\if{...}` will not damage macros because \OpTeX/'s macros are using `\_if` instead of `\if`. All \TeX/ primitives are initialized with two representative control sequences: `\word` and `\_word`, for example `\hbox` and `\_hbox`. -The first alternative is reserved for users or such control sequences -can be re-defined by user. +The first alternative is reserved for users or such control sequences +can be re-defined by a user. -\OpTeX/ sets the character `_` as letter, so it can be used in -control sequences. When a control sequence begins with this character +\OpTeX/ sets the character `_` as the letter, so it can be used in +control sequences. When a control sequence begins with this character then it means that it is a primitive or it is used in \OpTeX/ macros as -internal. User can redefine such prefixed control sequence only +internal. User can redefine such prefixed control sequence only if he/she explicitly know what happens. -We never change catcode of `_`, so internal macros can be -redefined by user without problems if it is desired. We need not +We never change catcode of `_`, so internal macros can be +redefined by user without problems if it is desired. We need not something like `\makealetter` from \LaTeX/. -\OpTeX/ defines all new macros as prefixed. For public usage of such macros -we need to set non-prefixed version. This is done by +\OpTeX/ defines all new macros as prefixed. For public usage of such macros, +we need to set non-prefixed version. This is done by -\begtt +\begtt \catcode`\<=13 \public <list of control sequences> ; \endtt For example \^`\public`` \foo \bar ;` does `\let\foo=\_foo`, `\let\bar=\_bar`. At the end of each code segment in \OpTeX/, the `\_public` macro is used. You -can see, what macros are defined for public usage in such code segment. +can see, what macros are defined for public usage in this code segment. The macro \^`\private` does a reverse job to `\public` with the same syntax. For example `\private \foo \bar ;` does `\let\_foo=\foo`, `\let\_bar=\bar`. -This should be used when unprefixed variant of control sequence is declared +This should be used when an unprefixed variant of a control sequence is declared already but we need the prefixed variant too. In this documentation: if both variants of a control sequence are declared (prefixed and unprefixed), then the accompanying text mentions only -unprefixed variant. The code typically defines prefixed variant +the unprefixed variant. The code typically defines the prefixed variant and then the \^`\public` (or `\_public`) macro is used. -\secc Name space of control sequences for users +\secc Namespace of control sequences for users -User can define or declare any control sequence with a name without any `_`. +Users can define or declare any control sequence with a name without any `_`. This does not make any problem. Only one exception is the reserved control -sequence `\par`. It is generated by tokenizer (at empty lines) +sequence `\par`. It is generated by tokenizer (at empty lines) and used as internal in \TeX/. User can define or declare control sequences with `_` character, for example `\my_control_sequence`, but with the following exceptions: \begitems -* Control sequences which begin with `_` are reserved for \TeX/ primitives, +* Control sequences which begin with `_` are reserved for \TeX/ primitives, \OpTeX/ internal macros and packages internal macros. -* Control sequences (terminated by non-letter) in the form +* Control sequences (terminated by non-letter) in the form `\<word>_` or `\<word>_<one-letter>`, where <word> is a sequence of letters, are inaccessible, because they are interpreted as `\<word>` followed by `_` or as `\<word>` followed by @@ -181,24 +184,24 @@ example `\my_control_sequence`, but with the following exceptions: \endtt This feature is implemented using lua code at input processor level, see the section~\ref[math-macros] for more details. You can deactivate this feature by - \^`\mathsboff`. After this, you can still write - `$`$\int$`_a^b$` (Unicode) or `$\int _a^b$` % $∫_a^b$ (Unicode) or $\int _a^b$ + \^`\mathsboff`. After this, you can still write + `$`$\int$`_a^b$` (Unicode) or `$\int _a^b$` % $∫_a^b$ (Unicode) or $\int _a^b$ without problems but `\int``_a^b` yields to undefined control sequence - `\int``_a`. You can activate this feature again by \^`\mathsbon`. The + `\int``_a`. You can activate this feature again by \^`\mathsbon`. The effect will take shape from next line read from input file. * Control sequences in the form `\_<pkg>_<word>` is intended for package - writers as internal macros for a package with `<pkg>` identifier, + writers as internal macros for a package with `<pkg>` identifier, see section~\ref[pkg-namespace]. \enditems -The single letter control sequences like `\%`, `\$`, `\^` etc. are not used -in internal macros. User can redefine them, but (of course) some classical +The single-letter control sequences like `\%`, `\$`, `\^` etc. are not used +in internal macros. Users can redefine them, but (of course) some classical features can be lost (printing percent character by `\%` for example). \secc Macro files syntax Each segment of \OpTeX/ macros is stored in one file with `.opm` extension -(means OPtex Macros). Your local macros should be in normal `*.tex` file. +(means OPtex Macros). Your local macros should be in a normal `*.tex` file. The code in macro files starts by \^`\_codedecl` and ends by \^`\_endcode`. The \^`\_endcode` is equivalent for `\endinput`, so documentation can follow. @@ -209,7 +212,7 @@ The \^`\_codedecl` has syntax: \endtt If the mentioned `\sequence` is defined, then \^`\_codedecl` does the same as -`\endinput`: this protect from reading the file twice. We suppose, that +`\endinput`: this protects from reading the file twice. We suppose, that `\sequence` is defined in the macro file. It is possible to use the \^`\_doc` ... \^`\_cod` pair between the macro lines. @@ -217,36 +220,37 @@ The documentation text should be here. It is ignored when macros are read but it can be printed using `doc.opm` macros like in this documentation. -\secc[pkg-namespace] Name spaces for package writers +\secc[pkg-namespace] Name spaces for package writers Package writer should use internal names in the form `\_<pgk>_<sequence>`, -where `<pkg>` is a package label. For example: +where `<pkg>` is a package label. For example: `\_qr_utfstring` from `qrcode.opm` package. -The package writer needs not write repeatedly `\_pkg_foo` `\_pkg_bar` +The package writer needs not to write repeatedly `\_pkg_foo` `\_pkg_bar` etc.\ again and again in the macro file.\fnote -{We have not adatped the idea from expl3 language:)} -When the \^`\_namespace` `{<pkg>}` +{We have not adopted the idea from expl3 language:)} +When the \^`\_namespace` `{<pkg>}` is declared at the beginning of the macro file then all occurrences of `\.foo` will be replaced by `\_<pkg>_foo` at the input processor level. -The macro writer can write (and backward can read his/her code) simply with -`\.foo`, `\.bar` control sequences and `\_<pkg>_foo`, `\_<pkg>_bar` +The macro writer can write (and backward can read his/her code) simply with +`\.foo`, `\.bar` control sequences and `\_<pkg>_foo`, `\_<pkg>_bar` control sequences are processed internally. The scope of the \^`\_namespace` command ends at the \^`\_endnamespace` command or when another \^`\_namespace` is used. This command checks if the same package label is not declared by the \^`\_namespace` twice. The \^`\_nspublic` macro does `\let\foo = \_<pkg>_foo` when -\^`\_namespace{<pkg>}` is declared. And the \^`\_nsprivate` macro does reverse -operation to it. Example: you can define `\def\.macro{...}` and then +\^`\_namespace{<pkg>}` is declared. Moreover, it prints a warning if `\foo` is +defined already. The \^`\_nsprivate` macro does reverse +operation to it without warnings. Example: you can define `\def\.macro{...}` and then set it to the user name space by `\_nspublic \macro;`. -Don't load another packages (which are using their own name space) inside your -name space. Do load them before your \^`\_namespace`~`{<pkg>}` is -initialized. Or close your name space by \^`\_endnamespace` and open it again +Don't load other packages (which are using their own namespace) inside your +namespace. Do load them before your \^`\_namespace`~`{<pkg>}` is +initialized. Or close your namespace by \^`\_endnamespace` and open it again (after other packages are loaded) by \^`\_resetnamespace`~`{<pkg>}`. -If the package writer needs to declare a control +If the package writer needs to declare a control sequence by \^`\newif`, then there is an exception of the rule described above. Use \^`\_newifi\_if<pkg>_bar`, for example `\_newifi\_ifqr_incorner`. Then the control sequences `\_qr_incornertrue` and @@ -256,35 +260,35 @@ and `\.incornerfalse` when `\_namespace{qr}` is used). \secc Summary about rules for external macro files published for \OpTeX/ -If you are writting a macro file which is intended to be published for +If you are writing a macro file that is intended to be published for \OpTeX/, then you are greatly welcome. You should follow these rules: \begitems -* Don't use a control sequences from user name space in the macro - bodies if there is not explicit and documented reason to do this. -* Don't declare control sequences in the user name space if there is not - explicit and documented reason to do this. -* Use control sequences from \OpTeX/ and primitive name space - in read only mode if there is not explicit and documented reason to - redefine them. -* Use `\_<pkg>_<name>` for your internal macros or `\.<name>` if the +* Don't use control sequences from the user namespace in the macro + bodies if there is not explicit and documented reason to do this. +* Don't declare control sequences in the user namespace if there are not + explicit and documented reasons to do this. +* Use control sequences from \OpTeX/ and primitive namespace + in read-only mode, if there is not an explicit and documented reason to + redefine them. +* Use `\_<pkg>_<name>` for your internal macros or `\.<name>` if the \^`\_namespace{<pkg>}` is declared. See section~\ref[pkg-namespace]. -* Use \^`\load` (or better: `\_load`) for loading more external macros - if you need them. Don't use `\_input` explicitly in such cases. - The reason is: the external macro file is not loaded - twice if another macro or the user needs it explicitly too. -* Use \^`\_codedecl` as your first command in the macro file and +* Use \^`\load` (or better: `\_load`) for loading more external macros + if you need them. Don't use `\_input` explicitly in such cases. + The reason is: the external macro file is not loaded + twice if another macro or the user needs it explicitly too. +* Use \^`\_codedecl` as your first command in the macro file and \^`\_endcode` to close the text of macros. * Use \^`\_doc` ... \^`\_cod` pairs for documenting the code pieces and/or write more documentation after the \^`\_endcode` command. \enditems -If the macro file accepts these recommendations then it should be -named by `<filename>.opm` where `<filename>` differs from file names -used directly in \OpTeX/ and from other published macros. -This extension `opm` has a precedence before `.tex` when +If the macro file accepts these recommendations then it should be +named by `<filename>.opm` where `<filename>` differs from file names +used directly in \OpTeX/ and from other published macros. +This extension `opm` has precedence before `.tex` when the \^`\load` macro is used. -The `qrcode.opm` is first example how an external macro file for \OpTeX/ +The `qrcode.opm` is the first example of how an external macro file for \OpTeX/ can look like. |