optex (14feb24)

git-svn-id: svn://tug.org/texlive/trunk@69861 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 427 insertions, 13 deletions

diff --git a/Master/texmf-dist/doc/optex/base/README b/Master/texmf-dist/doc/optex/base/README
index 3dab8b68f15..aa84d46627b 100644
--- a/Master/texmf-dist/doc/optex/base/README
+++ b/Master/texmf-dist/doc/optex/base/README
@@ -22,6 +22,11 @@ doc/   ... PDF version of the OpTeX documentation and sources.
 
 History:
 
+<1.14> Feb 2024:
+       More links in doc: TeX primitives linked to TeX in a Nutshell.
+       \trykv returns unexpanded value of the key=value pair.
+       \bracedparam reimplemented, improved.
+       \optdef can create an expandable macro.
 <1.13> Nov 2023:
        \usebib completely reimplemented, libranian package not needed from now.
        Selected OpTeX tricks are automatically loaded when a relevant macro is used.
diff --git a/Master/texmf-dist/doc/optex/base/optex-doc.pdf b/Master/texmf-dist/doc/optex/base/optex-doc.pdf
index aebe78c6343..731b1ab1795 100644
--- a/Master/texmf-dist/doc/optex/base/optex-doc.pdf
+++ b/Master/texmf-dist/doc/optex/base/optex-doc.pdf
diff --git a/Master/texmf-dist/doc/optex/base/optex-doc.tex b/Master/texmf-dist/doc/optex/base/optex-doc.tex
index d780ceeeefb..eb0fcc56825 100644
--- a/Master/texmf-dist/doc/optex/base/optex-doc.tex
+++ b/Master/texmf-dist/doc/optex/base/optex-doc.tex
@@ -21,9 +21,9 @@
 \tit Format Based on Plain \TeX/ and OPmac\fnotemark1
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\hfill Version 1.13
+\hfill Version 1.14
 
-\centerline{\it Petr Olšák, 2020, 2021, 2022, 2023}
+\centerline{\it Petr Olšák, 2020, 2021, 2022, 2023, 2024}
 
 \bigskip
 \centerline{\url{http://petr.olsak.net/optex}}
@@ -65,7 +65,7 @@ The main goal of \OpTeX/ is:
 If you need to customize your document or you need to use something
 very specific, then you can copy relevant parts of \OpTeX/ macros into your macro
 file and do changes to these macros here. This is a significant difference from
-\LaTeX/ or ConTeXt, which is an attempt to create a new user level with a
+\LaTeX/ or \ConTeXt/, which is an attempt to create a new user level with a
 plenty of non-primitive parameters and syntax hiding \TeX/ internals.
 The macros from \OpTeX/ are simple and straightforward because they solve only
 what is explicitly needed, they do not create a new user level for
@@ -113,13 +113,28 @@ document \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]
 \nonum\chap Index
 
 \noindent
-There are all control sequences used in \OpTeX/ except \TeX/ primitives.
-If you want to know something about \TeX/ primitives then you can use another index from
-\ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf\#ref:index]{\TeX/ in a Nutshell}.
+Control sequences declared by \OpTeX/ have page list here and they are
+internal links to their main documentation point. \TeX/ primitives used by
+\OpTeX/ have no page list here and they are external links to
+\ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf]{\TeX/ in a Nutshell}
+to the place where the primitive is briefly described.
+%Only primitives used in \OpTeX/ macros are listed here. There are much more
+%primitives implemented in \LuaTeX/, see
+%\ulink[https://www.pragma-ade.com/general/manuals/luatex.pdf]{\LuaTeX/ manual},
+%section \"primitives".
 
 % active links directly to the main documentation point but not to the pages:
-\def\_printii #1&{\noindent\hskip-\iindent \link[cs:#1]\Blue{\bslash #1} }
+\def\_printii #1&{%
+   \noindent\hskip-\iindent
+   \ea\ifx \csname,#1\endcsname \empty % primitive
+      \_dest[cs:#1]% main documentation point for primitives is in the Index
+      \ulink[http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf\#cs:#1]{\bslash#1}
+      \ea\ea\ea\nopages
+   \else \link[cs:#1]\Blue{\bslash #1} % OpTeX macro
+   \fi
+}
 \def\_pgprintA #1{#1}
+\def\nopages#1&{*\_par}
 \begmulti 3 \tt \makeindex \endmulti
 
 \bye
diff --git a/Master/texmf-dist/doc/optex/base/optex-techdoc.tex b/Master/texmf-dist/doc/optex/base/optex-techdoc.tex
index 78156194047..894f2d8cd3f 100644
--- a/Master/texmf-dist/doc/optex/base/optex-techdoc.tex
+++ b/Master/texmf-dist/doc/optex/base/optex-techdoc.tex
@@ -5,6 +5,7 @@
 % (three times) to create whole documentation including all references and the index.
 
 \load [doc.opm]
+\input primitives
 
 \thisoutline {TECHNICAL DOCUMENTATION}
 
diff --git a/Master/texmf-dist/doc/optex/base/optex-userdoc.tex b/Master/texmf-dist/doc/optex/base/optex-userdoc.tex
index 61157b0d31d..c99e63c21d0 100644
--- a/Master/texmf-dist/doc/optex/base/optex-userdoc.tex
+++ b/Master/texmf-dist/doc/optex/base/optex-userdoc.tex
@@ -1896,7 +1896,7 @@ tests, if the current point is at odd page regardless of asynchronous processing
 \tpg[perpage]\t\incrpp. \t\thepp, \t\thepplast, \t\truepage\
 does per-page counting of objects.
 
-\tpg[keystrokes]\t\keystoke\
+\tpg[keystrokes]\t\keystroke\
 prints given text in a keystroke-like frame.
 
 \tpg[longtable]\t\longtable\
@@ -1905,15 +1905,21 @@ alows to break a table to more pages and repeates header.
 \tpg[lot]\t\makeLOF, \t\makeLOT, \t\captionF, \t\captionT\
 create list of tables and list of figures similar to \^`\maketoc`.
 
+\tpg[onlyifnew]\t\onlyifnew\
+only define a macro if it is not already defined.
+
+\tpg[pgforeground]\t\pgforeground\
+adds material to the foreground of each page.
+
 \tpg[linnum]\t\pstart, \t\pend\
 dispalys line numbers of the marked text in the margin.
 
-\tpg[shadedframe]\t\shadedframe\
-colored rectangular frames with simple shadows.
-
 \tpg[roundframe]\t\roundframe\
 colored frames with rounded corners and many options.
 
+\tpg[shadedframe]\t\shadedframe\
+colored rectangular frames with simple shadows.
+
 \tpg[scaleto]\t\scaleto, \t\scaletof\
 text font size changed to the desired width.
 
@@ -2072,8 +2078,8 @@ documentation.
    Example: \~`\isinlist\list{<text>}\iftrue` does `\iftrue` if <text> is in `\list`.\nl
 \^`\isnextchar`` <char>{<text1>}{<text2>}` performs <text1> if next
    character is <char>, else <text2>.\nl
-\~`\kv` `{<key>}` expands to value when key-value parameters are used.
-   See also \~`\iskv`, \~`\readkv`, \~`\kvx`, \~`\nokvx`.\nl
+\~`\kv` `{<key>}` expands to a value given by key=value.
+   See also \~`\trykv`, \~`\iskv`, \~`\readkv`, \~`\kvx`, \~`\nokvx`.\nl
 \^`\loop` `...` \^`\repeat` is classical Plain \TeX/ loop.\nl
 \^`\mathstyles`` {<math list>}` enables to create macros dependent on current math style.\nl
 \~`\_namespace`` {<pkg>}` declares name space used by package writers.\nl
diff --git a/Master/texmf-dist/doc/optex/base/primitives.tex b/Master/texmf-dist/doc/optex/base/primitives.tex
new file mode 100644
index 00000000000..11ced8bca16
--- /dev/null
+++ b/Master/texmf-dist/doc/optex/base/primitives.tex
@@ -0,0 +1,387 @@
+%% This is part of the OpTeX project, see http://petr.olsak.net/optex
+
+% There is a list of TeX primitives used by OpTeX, they are printed in the Index.
+
+\def\addprimitive#1{\_ea\addprimitiveA \_csname,\_csstring#1\_endcsname}
+\def\addprimitiveA#1{\ifx#1\relax\_addto\_iilist#1\fi \_gdef#1{}}
+\def\_intlink{\_link[cs:\_tmpa]{\choosecolor}{\_csstring\\\_tmpb}}
+\def\choosecolor{\_ea\ifx\csname,\_tmpa\endcsname\empty \primcolor\else\ulinkcolor\fi}
+\def\primcolor{\setcmykcolor{.7 0 .7 .5}}
+
+\xargs\addprimitive
+%\above
+\abovedisplayshortskip
+\abovedisplayskip
+%\abovewithdelims
+\accent
+\adjdemerits
+\advance
+\afterassignment
+\aftergroup
+\atop
+\atopwithdelims
+\attributedef
+\baselineskip
+%\batchmode
+\begingroup
+\belowdisplayshortskip
+\belowdisplayskip
+\binoppenalty
+%\botmark
+\box
+\boxmaxdepth
+\breakafterdirmode
+\brokenpenalty
+%\catcode
+\catcodetable
+\char
+\chardef
+\cleaders
+\closein
+\closeout
+\clubpenalty
+\copy
+\countdef
+\cr
+\crampeddisplaystyle
+\crampedscriptstyle
+\crampedscriptscriptstyle
+\crampedtextstyle
+\crcr
+\csname
+\csstring
+\day
+\def
+\defaulthyphenchar
+\defaultskewchar
+\delcode
+\delimiter
+\delimiterfactor
+\delimitershortfall
+\detokenize
+\dimen
+\dimendef
+\dimexpr
+\directlua
+\discretionary
+%\displaylimits
+\displaystyle
+\displaywidowpenalty
+\displaywidth
+\divide
+\doublehyphendemerits
+\dump
+\edef
+%\efcode
+\else
+\emergencystretch
+\end
+\endcsname
+\endgroup
+\endinput
+\endlinechar
+\eqno
+\errmessage
+\errorcontextlines
+%\errorstopmode
+\escapechar
+\everycr
+\everydisplay
+\everyeof
+%\everyhbox
+\everyjob
+\everymath
+\everypar
+%\everyvbox
+\exhyphenpenalty
+\expandafter
+\expanded
+\fi
+\finalhyphendemerits
+\firstmark
+\floatingpenalty
+\font
+\fontdimen
+\fontname
+\futurelet
+\gdef
+\glet
+\global
+\globaldefs
+\halign
+\hangafter
+\hangindent
+\hbadness
+\hbox
+\hfil
+\hfill
+%\hfilneg
+\hfuzz
+\hoffset
+\hrule
+\hsize
+\hskip
+\hss
+\hyphenation
+\hyphenchar
+\hyphenpenalty
+\if
+\ifcase
+\ifcat
+\ifcsname
+\ifdim
+\ifeof
+\iffalse
+%\ifhbox
+\ifhmode
+\ifinner
+\ifmmode
+\ifnum
+\ifodd
+\iftrue
+%\ifvbox
+\ifvmode
+\ifvoid
+\ifx
+\ignorespaces
+\immediate
+\immediateassigned
+\immediateassignment
+\indent
+\input
+\inputlineno
+\interlinepenalty
+\jobname
+\kern
+%\knaccode
+%\knbccode
+%\knbscode
+\language
+\lastbox
+\lastnamedcs
+\lastpenalty
+\lastskip
+\lccode
+\leaders
+\left
+\lefthyphenmin
+\leftskip
+\leqno
+\let
+%\letterspacefont
+\limits
+\linepenalty
+\lineskip
+\lineskiplimit
+\long
+%\looseness
+\lower
+\lowercase
+%\lpcode
+\luaescapestring
+\mag
+\mark
+\mathaccent
+\mathbin
+\mathchar
+\mathchardef
+\mathchoice
+\mathclose
+\mathcode
+\matheqdirmode
+\mathop
+\mathopen
+\mathord
+\mathpunct
+\mathrel
+\mathsurround
+\maxdepth
+\meaning
+\medmuskip
+\message
+\middle
+\mkern
+\month
+\moveleft
+\moveright
+\mskip
+\multiply
+\muskip
+\muskipdef
+\newlinechar
+\noalign
+\noexpand
+\noindent
+\nolimits
+\nonscript
+%\nonstopmode
+\nulldelimiterspace
+\nullfont
+\number
+\numexpr
+\omit
+\openin
+\openout
+\outer
+\output
+\outputmode
+\outputpenalty
+\over
+\overfullrule
+%\overwithdelims
+\par
+\parfillskip
+\parindent
+%\parshape
+\parskip
+\patterns
+%\pdfadjustinterwordglue
+%\pdfadjustspacing
+\pdfcatalog
+%\pdfcolorstack
+\pdfdest
+\pdfendlink
+\pdfextension
+\pdffeedback
+%\pdffontexpand
+\pdfhorigin
+\pdfinfo
+\pdflastximage
+\pdflastxpos
+\pdflastypos
+\pdfliteral
+%\pdfnormaldeviate
+\pdfoutline
+\pdfpageheight
+\pdfpagewidth
+%\pdfprotrudechars
+\pdfrefximage
+\pdfrestore
+\pdfsave
+\pdfsavepos
+\pdfsetmatrix
+%\pdfsetrandomseed
+\pdfstartlink
+%\pdfstrcmp
+%\pdfuniformdeviate
+\pdfvariable
+\pdfvorigin
+\pdfximage
+\penalty
+\postdisplaypenalty
+\predisplaypenalty
+\pretolerance
+\prevdepth
+\prevgraph
+\protected
+\protrudechars
+\radical
+\raise
+\read
+\relax
+\relpenalty
+\right
+\righthyphenmin
+\rightskip
+\romannumeral
+\root
+%\rpcode
+\savecatcodetable
+\scantextokens
+\scantokens
+\scriptfont
+\scriptscriptfont
+\scriptscriptstyle
+\scriptstyle
+%\scrollmode
+\setbox
+\sfcode
+%\shbscode
+\shipout
+\show
+\showbox
+\showboxbreadth
+\showboxdepth
+\showlists
+\showthe
+\skewchar
+\skip
+\skipdef
+\spacefactor
+\spaceskip
+\span
+%\special
+\splitmaxdepth
+\splittopskip
+\sqrt
+%\stbscode
+\string
+\suppressfontnotfounderror
+\tabskip
+\textfont
+\textstyle
+\the
+\thickmuskip
+\thinmuskip
+\time
+\toks
+\toksdef
+\tolerance
+%\topmark
+\topskip
+\tracingassigns
+\tracingcommands
+\tracinggroups
+\tracingifs
+\tracinglostchars
+\tracingmacros
+\tracingonline
+\tracingoutput
+\tracingpages
+\tracingparagraphs
+\tracingrestores
+\tracingscantokens
+\tracingstats
+\uccode
+\Uchar
+\uchyph
+\Udelcode
+\Udelimiter
+\Umathaccent
+\Umathchar
+\Umathchardef
+\Umathcode
+\unexpanded
+\unhbox
+\unhcopy
+\unless
+\unpenalty
+\unskip
+\unvbox
+\unvcopy
+\uppercase
+\Uradical
+\vadjust
+\valign
+\vbadness
+\vbox
+\vcenter
+\vfil
+\vfill
+\vfilneg
+\vfuzz
+\voffset
+\vrule
+\vsize
+\vskip
+\vsplit
+\vss
+\vtop
+\wd
+\widowpenalty
+\write
+\xdef
+%\xleaders
+\xspaceskip
+\year
+;