summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/base/prefixed.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/base/prefixed.opm')
-rw-r--r--macros/luatex/optex/base/prefixed.opm138
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.